接口与鉴权
创建：POST https://top.qingyuntop.ai/v1/videos。一般使用 Content-Type: application/json；上传单张本地图片时使用 multipart/form-data，由客户端自动生成 boundary。
所有本站请求使用基础地址 https://top.qingyuntop.ai。请求头为 Authorization: Bearer YOUR_API_KEY，将 YOUR_API_KEY 替换为青云TOP API 的 API Key，保留 Bearer 后的一个空格。无需额外登录接口，也不需要 Vidu 厂商 Token。
当前核验范围与官方型号
本页的组合表来自当前仓库内 Vidu 插件的离线 decoder/builder 核验，目的是给出可以复现的本站字段和旧型号组合。Vidu 官方页面已更新到 Q3、Q2 Pro/Turbo/Fast 和 Q1 Classic 等型号，但公开 pricing 快照暂未匹配 Vidu；使用新型号前必须用当前 Key 调用 GET /v1/models 并确认分组权限。
| 动作 | 官方页面型号（需逐项确认本站开放） |
|---|---|
| 文生 | viduq3-turbo、viduq3-pro、viduq2、viduq1 |
| 图生 | viduq3-pro-fast、viduq3-turbo、viduq3-pro、viduq2-pro-fast、viduq2-pro、viduq2-turbo、viduq1、viduq1-classic、vidu2.0 |
| 首尾帧 | viduq3-turbo、viduq3-pro、viduq2-pro-fast、viduq2-pro、viduq2-turbo、viduq1、viduq1-classic、vidu2.0 |
| 非主体参考 | viduq3-mix、viduq3-turbo、viduq3-pro、viduq2-pro、viduq2、viduq1、vidu2.0 |
| 主体参考 | viduq3-turbo、viduq3、viduq2、viduq1、vidu2.0 |
通用字段与扩展参数
model、prompt、seconds、resolution、images 放在请求体顶层。Vidu 专属参数放在 metadata 对象，例如 action、aspect_ratio、bgm、seed 和 subjects。下表以文生视频为基础；各生成方式页面会列出差异和完整参数。
| 参数 | 类型 | 说明 |
|---|---|---|
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 验证厂商回调签名；建议先采用查询接口。详见状态码、错误与回调。 |
seconds 优先于兼容字段 duration。只写其中一个。不要在 metadata 再重复设置 model、prompt、images、duration、resolution 等顶层字段；元数据覆盖可能使校验、用量和实际生成参数不一致。
明确选择生成方式
metadata.action 是字符串，推荐始终填写以下四个值之一：
| action | 所需素材 | 对应文档 |
|---|---|---|
text_to_video | 无图，填写提示词 | 文生视频 |
image_to_video | 1 张首帧图片 | 图生视频 |
first_tail_to_video | 2 张图片，按首帧、尾帧排序 | 首尾帧 |
reference_to_video | 1–7 张参考图，或 metadata.subjects | 非主体参考、主体参考 |
省略 action 时，接口按顶层 images 数量自动判断：0 张为文生、1 张为图生、2 张为首尾帧、超过 2 张为参考生。只有 1 或 2 张参考图时，必须明确指定 reference_to_video。仅在 metadata 中设置图片或主体不会改变自动判断。
生成方式仅使用上表四种 action。不要使用 remix、remixGenerate 或自定义 action：它们不能在本站启用视频编辑或续写。
时长、分辨率与比例
| 当前插件已核验组合 | 模型 | 秒数 | 分辨率 |
|---|---|---|---|
| 文生视频 | viduq2 | 1–10（整数） | 540p / 720p / 1080p |
| 文生视频 | viduq1 | 5 | 1080p |
| 图生视频 | viduq1 | 5 | 1080p |
| 图生视频 | vidu2.0 | 4 | 360p / 720p / 1080p |
| 图生视频 | vidu2.0 | 8 | 720p |
| 首尾帧 | viduq1 | 5 | 1080p |
| 首尾帧 | vidu2.0 | 4 | 360p / 720p / 1080p |
| 首尾帧 | vidu2.0 | 8 | 720p |
| 参考图 | viduq2 | 1–10（整数） | 540p / 720p / 1080p |
| 参考图 | viduq1 | 5 | 1080p |
| 参考图 | vidu2.0 | 4 | 360p / 720p |
| 主体参考 | viduq2 | 1–10（整数） | 540p / 720p / 1080p |
| 主体参考 | viduq1 | 5 | 1080p |
顶层 resolution 优先于 metadata.resolution，然后才是 size 和模型默认值。Responses 入口的位置不同，详见 Responses 创建。
size 是兼容性的分辨率转换字段，不是画面宽高比。建议直接指定 resolution；文生/参考视频比例使用 metadata.aspect_ratio，图生和首尾帧主要遵循输入图片构图。viduq1 在当前插件转换中固定为 1080p；新型号不要套用这个旧规则。
素材与上传边界
URL 必须能被上游直接下载；不要使用本地磁盘路径、需要登录的网页或防盗链链接。支持 PNG、JPEG/JPG、WebP；data URL 需形如 data:image/png;base64,...。
图生和首尾帧官方图片上限为每张 50MB、请求体不超过 20MB。非主体参考图的 Base64 解码后须小于 10MB。本站 multipart 单文件上限为 15MiB，转为 Base64 后体积会增加，接近上限时推荐改用 URL。
结果与费用
创建后根据返回 id 查询任务；查询与下载说明状态和文件保存。返回用量中的 credits 是厂商积分，不是人民币价格。本站扣费以控制台模型价格、账户分组和实际用量记录为准。