功能介绍

MiniMax-H3 支持文生、首帧/首尾帧和多模态参考。参考模式可以组合图片、视频、音频；首尾帧模式与参考模式互斥。两种模式都必须有非空文字描述。

鉴权与操作步骤

所有请求发送到 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，不要调用官方 /v2/video_generation 路径。

参数类型说明
modelstring填 MiniMax-H3。本页不适用于 H3-Max。
secondsinteger可选，默认 5；必须是 4–15 的整数，单位秒。
metadata.resolutionstring可选，默认 768P，只支持 768P / 2K。
metadata.ratiostring可选：adaptive、21:9、16:9、4:3、1:1、3:4、9:16；纯文/纯音参考不可使用 adaptive。
metadata.contentarray完整多模态内容数组。提供时优先于自动组装字段；必须有非空 text。
metadata.callback_urlstring可选，直接传给上游的回调地址。
metadata.aigc_watermarkboolean可选，是否添加水印。

纯文或仅参考音频时，填写具体比例，例如 16:9。未提供比例时，含图片/视频的请求默认 adaptive，其他请求默认 16:9。首尾帧输出按图片比例处理，官方会忽略其他有效比例并使用 adaptive。

content 中每一项的结构

  • 文本：{"type":"text","text":"描述"}。每个 text 必须非空，最多 7000 个字符。
  • 图片：{"type":"image_url","image_url":{"url":"图片地址"},"role":"reference_image"}。帧模式的 role 改为 first_frame 或 last_frame。
  • 视频：{"type":"video_url","video_url":{"url":"视频地址"},"role":"reference_video"}。
  • 音频：{"type":"audio_url","audio_url":{"url":"音频地址"},"role":"reference_audio"}。

metadata.content 内已有非空 text 时，以该文字为准；顶层 prompt 不会替换它。没有 text 时使用顶层 prompt；两者均为空会报错。使用完整 content 时，不要再重复填首尾帧或参考素材快捷字段。

未提供 content 时，可用 prompt、metadata.first_frame_image/last_frame_image 或最多两张 images 指定首尾帧，也可读取 metadata.reference_video/reference_audio（字符串或数组）。参考图片没有同名快捷字段，请使用 content。

素材限制

素材数量官方文件与尺寸限制
首尾帧图片首帧≤1、尾帧≤1JPG/JPEG/PNG/WebP/HEIC/HEIF；每张≤30 MB；宽高各 256–5760 px；宽高比 0.4–2.5
参考图片最多9张同上；不能和首尾帧混用
参考视频最多3段MP4/MOV；H.264/H.265；每段≤50 MB；每段2–15秒，总时长≤15秒；宽高各256–5760 px、比例0.4–2.5、23.976–60 FPS
参考音频最多3段WAV/MP3；每段≤15 MB；每段2–15秒，总时长≤15秒

请求体官方总大小上限为 64 MB；本站还可能有更低的网关限制。大素材优先用公网 URL。统一 multipart 首图上传仍受本接口 20 MiB 文件限制，不能以 H3 官方 30 MB 替代。本接口图片总数不得超过 9 张。

运行示例前

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-H3",
  "prompt": "一只狐狸穿过秋日森林，镜头跟随，树叶随风飘动。",
  "seconds": 8,
  "metadata": {
    "resolution": "2K",
    "ratio": "16:9"
  }
}'

首尾帧示例

curl --fail-with-body "https://top.qingyuntop.ai/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "MiniMax-H3",
  "prompt": "让首帧场景自然过渡到尾帧，运镜平稳。",
  "seconds": 5,
  "metadata": {
    "resolution": "768P",
    "ratio": "adaptive",
    "first_frame_image": "https://example.com/start.png",
    "last_frame_image": "https://example.com/end.png"
  }
}'

多模态参考示例

curl --fail-with-body "https://top.qingyuntop.ai/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "MiniMax-H3",
  "prompt": "参考人物形象和视频中的运动节奏，让人物在花园中行走。",
  "seconds": 5,
  "metadata": {
    "resolution": "768P",
    "ratio": "16:9",
    "content": [
      {
        "type": "text",
        "text": "参考人物形象和视频中的运动节奏，让人物在花园中行走。"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/character.png"
        },
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": {
          "url": "https://example.com/movement.mp4"
        },
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": {
          "url": "https://example.com/rhythm.mp3"
        },
        "role": "reference_audio"
      }
    ]
  }
}'

哪些字段不需要填写

input_images、input_video_seconds 是用量字段，不是请求参数，无需填写。除本页生成参数外，可选设置 metadata.callback_url 和 metadata.aigc_watermark；请勿直接添加未列出的厂商字段，例如 extra。

返回结果与下一步

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