请求格式
POST https://top.qingyuntop.ai/v1/videos 支持 JSON，也支持上传一张 input_reference 文件的 multipart。JSON 中 metadata 是对象；multipart 中它是 JSON 字符串。
鉴权与操作步骤
所有请求发送到 https://top.qingyuntop.ai。在请求头填写 Authorization: Bearer YOUR_API_KEY，将 YOUR_API_KEY 替换为青云TOP API 控制台创建的 API Key；Bearer 与密钥之间保留一个空格。
- 携带鉴权请求头，按本页参数创建任务。
- 保存返回的任务标识，查询至成功后下载视频。创建成功仅表示任务已受理。
JSON 请求使用 Content-Type: application/json。示例中的占位密钥需替换为你的 API Key。实际业务请在服务端保存密钥，不要放进公开网页。
传统系列参数
| 参数 | 类型 | 说明 |
|---|---|---|
model | string | 必填。使用模型清单中的精确名称；不同系列不可共用所有参数。 |
prompt | string | 视频描述，传统系列最多 2000 字符。文生视频必填；描述主体、动作、镜头和风格。 |
seconds | integer | 本站统一视频时长字段，单位秒。优先于兼容字段 duration；只填一个。可用值见模型表。 |
resolution | string | 明确写 768P / 1080P 等档位，按模型选择；不要把宽高比写在这里。 |
metadata.prompt_optimizer | boolean | 可选。官方默认 true，自动优化提示词；false 更直接遵循原提示词。 |
metadata.fast_pretreatment | boolean | 可选，默认 false，缩短提示词优化耗时；与 prompt_optimizer=true 配合。文生适用于 2.3、02；图生另包括 2.3-Fast。 |
metadata.aigc_watermark | boolean | 可选。是否添加水印，官方默认 false。 |
metadata.callback_url | string | 可选。上游直接回调你的公网地址；见错误与回调说明。 |
metadata.first_frame_image | string | 首帧图片。也可用顶层 input_reference；同时填写时 metadata 中的首帧优先。 |
metadata.last_frame_image | string | 尾帧图片。传统系列首尾帧使用 MiniMax-Hailuo-02。 |
metadata.subject_reference | array | 仅 S2V-01，使用人物参考对象数组，不能用 images 代替。 |
顶层 input_reference（字符串）是首帧的 HTTPS URL 或图片 data URL；本地文件用 multipart。metadata（对象）放模型专属字段，不能把 first_frame_image、subject_reference 等直接摆在顶层。
分辨率优先级是顶层 resolution → metadata.resolution → size → 模型默认值。size 用于识别分辨率档位，不代表能指定任意像素尺寸；推荐直接填 resolution。
传统系列不要使用顶层 images 数组传首尾帧：它虽会被识别为带图请求，却不会自动转换成上游首帧字段。请使用 input_reference 或明确的 metadata.first_frame_image / metadata.last_frame_image。
模型组合限制
按模型清单选择时长和分辨率。10 秒不能与 1080P 组合；Fast 必须带首图；T2V 模型不应传图，I2V 模型必须有首图。请严格按模型表选择组合，提交成功不代表参数组合一定有效。
H3 参数另行说明
H3 使用 4–15 秒、768P / 2K、metadata.content、metadata.ratio 等字段。其分辨率优先级是 metadata.resolution → 顶层 resolution → size；不要在多个位置重复写不同值。详见H3 多模态视频。