请求格式
POST https://top.qingyuntop.ai/v1/videos，支持 JSON 或单首图 multipart。JSON 的 metadata 必须是对象；表单的 metadata 必须是 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 | number | 单位秒；统一入口可传数字或整数字符串，推荐数字5；原生格式对应 duration 字符串。 |
mode | string | std / pro；v1与v1-6默认std，v2-master只能pro。也可放metadata.mode，避免重复冲突。 |
metadata.aspect_ratio | string | 文生视频比例：16:9 / 9:16 / 1:1。图生主要跟随输入图片，不能据此强制任意尺寸。 |
metadata.cfg_scale | number | 提示词遵循强度；默认0.5。按所选型号支持使用，建议0到1范围内；并非所有型号都会采用。 |
input_reference | string | 首帧图片URL或裸Base64字符串；本地文件可用multipart。不要加data:image/...前缀。 |
seconds 优先于兼容字段 duration，默认5秒。时长请按具体型号支持范围填写，不要提交任意秒数。size（字符串）只转换宽高比：1280x720 / 1920x1080 → 16:9，720x1280 / 1080x1920 → 9:16，1024x1024 / 512x512 → 1:1；未填或不能识别时为1:1。显式 metadata.aspect_ratio 会覆盖该结果。
metadata 扩展与优先级
metadata 的同名字段会覆盖默认请求值，例如 metadata.duration、metadata.model_name、metadata.image。请只在一个位置填写同一项参数，尤其不要重复填写冲突的模型名或时长，以免请求失败或用量与预期不一致。
可选透传字段包括 negative_prompt（字符串，负向描述）、image_tail（字符串，尾帧）、callback_url（字符串，公网回调地址）、external_task_id（字符串，业务关联号），以及上游具体型号支持的选项。这是透传能力，不是对任意字段、模型或功能的承诺。新型号的 sound、multi_shot、voice_list 等不属于本文三个模型的已确认能力。
尾帧字段能转发，但旧型号支持范围未由当前官方能力表完整确认。默认示例仅使用一张首帧；需要首尾帧时先确认具体型号及模式，再配合首图使用 metadata.image_tail，不把两张图解释成多图参考。
图像规范
按官方旧版接口，首图使用可访问的HTTPS地址或裸Base64，支持 JPG/JPEG/PNG，文件≤10 MB，宽高均不小于300 px，比例约0.4–2.5。本站 multipart 单文件上限10 MiB；同时遵守官方10 MB要求。图生支持范围仍由具体型号与模式决定。