Responses 文生视频 | 青云TOP API 文档

用文字描述主体、动作、场景、镜头和声音，通过 /v1/responses 创建 Veo 视频。本文使用后台模式，适合需要稳定保存任务 ID 的服务端程序。

这项功能能做什么

把场景描述生成一段带音频的视频。例如，描述雨后屋顶上的猫、跟随镜头和环境雨声。Veo 3.1 标准版与 Fast 的输入格式一致；Fast 要填写完整模型名 veo-3.1-fast-generate-preview。

第一步：鉴权

请求头使用 Authorization: Bearer YOUR_API_KEY。将占位符替换为青云 API Key，保留 Bearer 后的空格。鉴权随创建、查询和下载请求发送，无需先登录 API。

第二步：调用模型生成

POST https://top.qingyuntop.ai/v1/responses

请求头还需 Content-Type: application/json。后台创建返回顶层 id（resp_…），随后按查询结果与下载视频等待完成并保存视频。

请求参数

参数	类型	必填	详细说明
model	string	是	完整 Veo 模型 ID；示例使用 veo-3.1-generate-preview
input	string 或 array	文生视频需要	建议使用字符串。描述主体、动作、环境、镜头和声音；数组写法见图生视频页
background	boolean	否	默认 false；设为 true 且 stream 为 false 时，提交后返回任务快照
stream	boolean	否	默认 false；true 返回 SSE，详见模式页
seconds	integer	建议填写	Veo 3.1 使用 4、6 或 8；高清 1080p、4k 必须为 8
metadata	object	否	Veo 生成选项。用于控制生成效果，不用于存放任意业务标签
metadata.resolution	string	建议填写	720p、1080p、4k；首次接入建议 720p
metadata.aspectRatio	string	建议填写	16:9 横屏或 9:16 竖屏
metadata.personGeneration	string	否	人物生成规则；Veo 3.1 文生通常为 allow_all，部分地区限制为 allow_adult，以上游模型和服务地区为准
metadata.seed	integer	否	随机种子，有助于相似结果，不保证完全可复现
size	string	否	例如 1280x720；仅在 metadata 对应字段缺省时推断清晰度和比例，建议直接填写 metadata

省略清晰度和比例时由上游默认值决定，Google 3.1 通常为 720p、16:9。不要同时传入冲突的参数。本入口还接受 duration 作为 seconds 的别名（seconds 优先），接受 prompt 作为 input 文本为空时的备用值。Responses 的顶层 resolution 会覆盖 metadata.resolution；统一视频接口没有相同的转发行为，因此本目录统一把它放在 metadata 中。

本入口不使用 tools、previous_response_id、instructions、temperature、max_output_tokens 来控制视频。请直接使用 input 和上述视频字段；metadata 也不能用于放置 referenceImages、lastFrame 或视频延长输入。

代码示例

点击标签切换语言。cURL 为 Bash 写法；Python 需安装 requests；Node.js 使用 22+，保存为 .mjs。示例会创建一个真实视频任务。

curl --fail-with-body https://top.qingyuntop.ai/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "input": "An orange cat walks across a wet rooftop after rain. Slow tracking shot, soft evening light, gentle rain sounds.",
    "seconds": 8,
    "metadata": {"resolution": "720p", "aspectRatio": "16:9"},
    "background": true,
    "stream": false
  }'

创建响应

以下为关键字段示意，实际响应还会包含其他字段。初次状态也可能已进入 in_progress。

{
  "id": "resp_veo_example",
  "object": "response",
  "model": "veo-3.1-generate-preview",
  "status": "queued",
  "background": true,
  "output": [],
  "error": null,
  "metadata": {
    "task_id": "task_veo_example",
    "task_status": "queued",
    "retrieval_path": "/v1/responses/resp_veo_example"
  }
}

保存 id 和 metadata.task_id。HTTP 200 不是视频完成的标志；继续查询结果与下载视频。创建超时且未收到 ID 时，先检查控制台任务日志，避免重复提交。