POST/v1/video/create

Veo 文生视频

用一段文字描述生成短视频：先提交任务，再轮询任务状态，完成后下载 MP4。本文按青云TOP API 的实际调用方式编写，适合第一次接入 Veo 的用户。

API Key application/json

这项功能能做什么

文生视频会把“主体、动作、场景、镜头和声音”组合成一段视频。例如，提示词可以描述一只橙色的猫在雨后屋顶行走、镜头缓慢推进，并加入雨声。Veo 3 系列会生成原生音频，输出通常为 24 fps，并带有 Google 的 SynthID 标识。

当前网关公开的常用模型是 veo-3.1-generate-preview 和 veo-3.1-fast-generate-preview。Fast 是独立模型，必须填写完整模型 ID。模型和分组以你的账号在模型价格及 GET /v1/models 返回的结果为准。

第一步：鉴权

在控制台 API 密钥取得青云 API Key，在每次请求头中填写：

Authorization: Bearer YOUR_API_KEY

替换完整占位符，保留 Bearer 和其后一个空格。鉴权直接随请求发送，不需要先调用登录接口。

第二步：调用模型生成

提交下面的创建请求，保存响应中的 id。生成是异步的：随后用同一 Key 查询 GET /v1/videos/{id}，completed 后下载 GET /v1/videos/{id}/content。具体代码见查询任务与下载视频。

创建接口

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

请求头：Authorization: Bearer YOUR_API_KEY、Content-Type: application/json。

Request

请求

/v1/video/create

Body

必填

Bodyobject

imagesarray<string>必填

图片链接

元素string

modelstring必填

模型名字

orientationstring必填

portrait 竖屏 landscape 横屏

promptstring必填

提示词

sizestring必填

large 高清1080p

durationinteger必填

支持 15，25

watermarkboolean必填

默认为： true 会优先无水印，如果出错，会兜底到有水印传递 false 的话会强制让视频无水印，遇到去水印错误的会一直自动重试

privateboolean必填

是否隐藏视频，true-视频不会发布，同时视频无法进行 remix(二次编辑)，默认为 false

路径、查询与 Header 参数

参数	位置	类型	必填	说明	示例
`Content-Type`	Header	string	是	-	application/json
`Accept`	Header	string	是	-	application/json
`Authorization`	Header	string	是	必填。使用青云TOP API 的 API Key，保留 Bearer 后的空格。	Bearer YOUR_API_KEY

请求示例application/json

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

Response

返回响应 `200`

HTTP 响应

响应 200object

idstring必填

objectstring必填

createdinteger必填

choicesarray<object>必填

元素object

indexinteger

messageobject

rolestring必填

contentstring必填

finish_reasonstring

usageobject必填

prompt_tokensinteger必填

completion_tokensinteger必填

total_tokensinteger必填

代码示例

下面的代码只是在同一个请求上切换语言，点击标签即可查看对应写法。运行示例会提交真实生成请求。Python 需安装 requests，Node.js 22+ 示例保存为 .mjs；cURL 为 Bash 写法。

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

成功响应

提交成功通常先返回排队中的视频对象。请保存 id，不要要求创建响应立即带视频 URL。

{
  "id": "task_veo_example",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "queued",
  "progress": 0,
  "created_at": 1789689600
}

queued 表示已接收，in_progress 表示生成中。请按查询任务与下载视频继续操作。创建请求超时但没有拿到 ID 时，先查看任务日志，不要马上重复提交。

常用变体

竖屏：把 metadata.aspectRatio 改为 9:16。
高清：把 metadata.resolution 改为 1080p 或 4k，同时保持 seconds: 8。
Fast：把 model 改为 veo-3.1-fast-generate-preview，其余字段不变。

单次请求只生成一个视频；增加 n 不会批量生成。有关旧版 /v1/video/generations 的兼容说明，请查看查询任务与下载视频。