功能与模型
官方当前文生型号为 viduq3-turbo、viduq3-pro、viduq2、viduq1。下表是当前插件离线核验的可执行组合；Q3 的时长、分辨率和音画同步限制请以官方页面及当前 GET /v1/models 结果复核，不能只把示例模型名替换成 Q3。
| 当前插件已核验组合 | 模型 | 秒数 | 分辨率 |
|---|---|---|---|
| 文生视频 | viduq2 | 1–10（整数） | 540p / 720p / 1080p |
| 文生视频 | viduq1 | 5 | 1080p |
官方型号（2026-10-02）：viduq3-turbo、viduq3-pro、viduq2、viduq1。这是 Vidu 官方动作页面的型号清单；青云TOP 当前 pricing 快照未匹配到 Vidu，且本地插件离线核验范围仍为旧型号。提交前请用当前 API Key 调用GET /v1/models，只有返回该型号且分组开放时才可使用；不能只替换model字符串。
1. 设置鉴权
所有本站请求使用基础地址 https://top.qingyuntop.ai。请求头为 Authorization: Bearer YOUR_API_KEY，将 YOUR_API_KEY 替换为青云TOP API 的 API Key，保留 Bearer 后的一个空格。无需额外登录接口，也不需要 Vidu 厂商 Token。
2. 调用模型生成
POST https://top.qingyuntop.ai/v1/videos，请求头 Content-Type: application/json。metadata.action 填 text_to_video，不要传 images。
| 参数 | 类型 | 说明 |
|---|---|---|
model | string | 必填。当前插件离线核验为 viduq2、viduq1；Vidu 官方文生页面还列出 viduq3-turbo、viduq3-pro。只有当前 Key 的 GET /v1/models 返回并且分组开放时才可使用新增型号。 |
metadata.style | string | 选填，放入 metadata。general（默认）或 anime；viduq2 不生效。 |
prompt | string | 必填，最多 5000 字符。描述主体、动作、场景和镜头。 |
seconds | integer | 选填；本站优先使用 seconds（单位：秒），不要同时设置 duration。模型组合见本页表格。 |
metadata.seed | integer | 选填，放入 metadata。整数随机种子；省略时由上游随机生成，不保证跨任务像素级一致。 |
metadata.aspect_ratio | string | 选填，放入 metadata。默认 16:9；支持 16:9、9:16、1:1；viduq2 另支持 3:4、4:3。 |
resolution | string | 选填。显式使用本页允许的档位；不表示画面比例。 |
metadata.movement_amplitude | string | 选填，放入 metadata。auto（默认）、small、medium、large；viduq2 不生效。 |
metadata.bgm | boolean | 选填，放入 metadata，默认 false。true 为视频添加背景音乐；viduq2 的 9/10 秒任务不生效。不是独立音频生成。 |
metadata.audio | boolean | 本页基础示例不使用。Vidu 官方文生页面将音画同步 audio 限定在 Q3 型号；当前插件离线示例仍是 Q2/Q1。启用 Q3 前先确认 GET /v1/models 和分组权限。 |
metadata.payload | string | 选填，放入 metadata。业务透传字符串，最多 1048576 字符；统一视频结果不会承诺回显，关联任务请自行保存返回 ID。 |
metadata.off_peak | boolean | 选填，放入 metadata，默认 false。初次接入建议保持 false；当前文档不提供取消任务入口，不承诺官方直连的退款规则适用于本站。 |
metadata.callback_url | string | 选填，上游回调地址，放入 metadata。不能用本站 API Key 验证厂商回调签名；建议先采用查询接口。详见状态码、错误与回调。 |
代码示例
点击标签切换 cURL、Python 或 Node.js。cURL 为 Bash 写法；Python 需安装 requests；Node.js 使用 18 或更新版本（含导入语句时保存为 .mjs）。图片示例使用 Vidu 官方示例素材，也可换成你自己的公开可访问图片 URL。
curl --fail-with-body "https://top.qingyuntop.ai/v1/videos" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "viduq2",
"prompt": "清晨的湖面薄雾缓缓散开，镜头平稳向前推进，写实摄影。",
"seconds": 5,
"resolution": "720p",
"metadata": {
"action": "text_to_video",
"aspect_ratio": "16:9"
}
}'示例使用当前插件已核验的 viduq2、5 秒、720p 组合。若 GET /v1/models 显示 viduq3-turbo 或 viduq3-pro，请先按官方文生页面确认秒数、分辨率和 audio 条件，再替换示例；未确认前不要宣称新型号已由本站开放。
查询与下载
创建成功后保存返回的 id，按查询任务与下载视频查询。只有 status=completed 才下载；创建请求返回成功不等于视频已经生成。
metadata.bgm=true 请求的是视频中的背景音乐，不是独立音频文件。官方 Q3 还描述了 audio 音画同步字段；当前示例不启用它，且 Q2/Q1 的参数不能直接套用 Q3。
参考：官方文生视频。调用本站时请使用上表的字段位置，不能直接套用官方请求 URL 或 Token 鉴权。