功能介绍

把一张图片作为视频首帧，通过提示词控制后续运动。支持 2.3、2.3-Fast、02 和 I2V-01 系列。2.3-Fast 适合此场景，必须提供图片。

鉴权与操作步骤

所有请求发送到 https://top.qingyuntop.ai。在请求头填写 Authorization: Bearer YOUR_API_KEY，将 YOUR_API_KEY 替换为青云TOP API 控制台创建的 API Key；Bearer 与密钥之间保留一个空格。

  1. 携带鉴权请求头，按本页参数创建任务。
  2. 保存返回的任务标识，查询至成功后下载视频。创建成功仅表示任务已受理。

JSON 请求使用 Content-Type: application/json。示例中的占位密钥需替换为你的 API Key。实际业务请在服务端保存密钥，不要放进公开网页。

输入与参数

POST /v1/videos。填 model、首图 input_reference，建议同时填 prompt、seconds、resolution。02 的单首帧图生可以选择 512P（6/10 秒）；该规则不扩展到首尾帧模式。

传统系列图片支持 JPG/JPEG/PNG/WebP，文件小于 20 MB，短边大于 300 px，宽高比在 2:5 到 5:2 之间。JSON 可传 HTTPS URL 或 data:image/png;base64,...。不要填写本机路径。更多字段见统一视频参数。

运行示例前

cURL 示例使用 Bash 换行语法；Python 需要安装 requests；Node.js 使用 20 或更高版本，将代码保存为 .mjs。带素材的示例必须把 https://example.com/... 替换为上游能直接读取的真实 HTTPS 文件地址，不是网页地址或本机文件路径。

公网首图示例

curl --fail-with-body "https://top.qingyuntop.ai/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "MiniMax-Hailuo-2.3-Fast",
  "prompt": "画面中的人物轻轻转头，镜头缓慢拉近，保持面部和服装一致。",
  "input_reference": "https://example.com/first-frame.png",
  "seconds": 6,
  "resolution": "768P"
}'

本地图片上传

把本地图片命名为 first-frame.png，与脚本放在同一目录。只允许一个文件字段 input_reference，本接口单文件上限为 20 MiB；同时遵守上述官方图片要求。metadata 必须序列化为 JSON 字符串。使用表单时不要手动填写 Content-Type，让客户端生成 boundary。

curl --fail-with-body "https://top.qingyuntop.ai/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F 'model=MiniMax-Hailuo-2.3-Fast' \
  -F 'prompt=镜头缓慢拉近，保持主体一致。' \
  -F 'seconds=6' \
  -F 'resolution=768P' \
  -F 'metadata={"prompt_optimizer":true}' \
  -F "input_reference=@first-frame.png"

返回结果与下一步

返回的 id 是本站任务 ID，请原样保存。通过视频任务查询与下载等待 status=completed 后获取 MP4。不要从 ID 猜测厂商任务号，也不要把 progress=100 或存在 completed_at 当作成功条件。