使用青云TOP API 的 /v1/videos 提交 Veo 视频任务，随后查询进度并下载 MP4。本文介绍模型选择、鉴权、输入限制和后续操作。
功能与适用场景
Veo 是 Google 的视频生成模型。文生视频把场景描述生成视频；图生视频让起始图片产生动作。Veo 3.1 支持同步生成对白、环境音和音乐。标准版与 Fast 使用相同调用流程，切换时更改 model 即可。
本目录的“统一视频格式”是本站提供的 OpenAI 风格视频兼容接口，使用 /v1/videos 路径和统一任务对象。Veo 由 Google 提供；本接口与 Google 原生 REST 的请求结构不同，也不使用旧 /v1/video/create 路径。
第一步：鉴权
在控制台 API 密钥获取青云 API Key。每次创建、查询和下载都携带同一个请求头：
Authorization: Bearer YOUR_API_KEY将 YOUR_API_KEY 替换为完整的青云 API Key，保留 Bearer 和后面的一个空格。鉴权随请求发送，无需先调用登录接口。代码应在你的服务端运行。
第二步：调用模型生成
| 操作 | 方法与本站地址 | 返回内容 |
|---|---|---|
| 提交生成 | POST https://top.qingyuntop.ai/v1/videos | 视频任务对象，保存顶层 id |
| 查询结果 | GET https://top.qingyuntop.ai/v1/videos/{task_id} | 顶层 status |
| 下载文件 | GET https://top.qingyuntop.ai/v1/videos/{task_id}/content | 视频字节 |
生成是异步的。先提交一次，约每 10 秒查询一次；completed 后下载，failed 后停止查询。不要通过反复提交创建请求来等待结果。
模型选择
| 模型 ID | 说明 |
|---|---|
veo-3.1-generate-preview-c | 当前公开 pricing 中的 Veo 3.1 标准版路由 ID；以账号模型列表为准 |
veo-3.1-fast-generate-preview-c | 当前公开 pricing 中的 Veo 3.1 Fast 路由 ID；使用同一请求格式 |
veo-3.1-generate-preview | Google 原生型号名；仅在你的 Key 的模型列表出现时使用 |
veo-3.1-fast-generate-preview | Google 原生 Fast 型号名；仅在你的 Key 的模型列表出现时使用 |
公开目录核对（2026-10-30）：pricing 快照匹配到veo-3.1-generate-preview-c和veo-3.1-fast-generate-preview-c。这不是完整模型清单，也不替代当前 Key 的GET /v1/models；模型可见性和参数组合仍需按本文说明。模型 ID 的-c后缀是青云/New API 路由 ID，不是 Google 官方型号的一部分。
你的 Key 可用的模型以模型价格和携带该 Key 请求 GET /v1/models 的结果为准。3.1 的分辨率、时长限制不要套用到 3.0；本目录的参数组合说明以 3.1 为主。
Veo 3.1 常用组合
| 项目 | 可选值与限制 |
|---|---|
| 时长 | seconds: 4、6、8；使用参考图、1080p 或 4k 时必须为 8 秒 |
| 分辨率 | metadata.resolution 为 720p、1080p、4k |
| 比例 | metadata.aspectRatio 为 16:9 或 9:16 |
| 音频 | Veo 3.1 原生生成音频；本目录不提供关闭音频的开关 |
| 帧率 | 官方为 24 fps，本接口不提供自定义帧率 |
| 输出数量 | 每次请求生成 1 个视频 |
| 参考图（Google 原生） | referenceImages 最多 3 张；与 1080p/4K 一起使用时必须 8 秒 |
参考图（青云 /v1/videos） | 当前适配只读取一张起始图：multipart 的 input_reference 或 JSON 的 images[0] |
Google 原生 Veo 3.1 支持最多 3 张参考图，可用来保持主体、角色或风格一致；lastFrame、视频延长等原生能力不等于青云统一接口已开放。青云 /v1/videos 当前不会启用额外 referenceImages、lastFrame 或 video 字段，提交多张 images 也只读取第一项。
参数说明、默认行为、限制和语言示例分别见下方文档。首次接入建议使用 8 秒、720p、16:9，并只上传一张起始图片。
选择调用格式
本站提供两种 Veo 调用方式：本目录的 /v1/videos，以及支持同步、流式和后台模式的 /v1/responses。两者均用于生成 Veo 视频，参数位置和返回结构有所不同。
Google 原生 REST 使用 predictLongRunning 和 instances / parameters。本站本目录不提供该原生入口，请使用上表地址，勿将 Google 示例直接换成本站域名。已使用 Responses 的程序可阅读 Responses 格式。
按功能阅读
功能、鉴权、参数和横向语言示例
Veo 图生视频上传起始图片与 JSON 图片编码
查询任务与下载视频查询、自动等待和保存 MP4
任务状态与错误状态判断与常见问题
Responses 格式同步、流式、后台生成与结果查询