MiniMax H3 视频生成对接说明

MiniMax H3 提供 768P 与 2K 两档清晰度并生成原生音频。基础档支持文生、图生、首尾帧、参考图和参考音频；需要参考视频驱动时使用 Pro 档。

API Base URLhttps://api2.cgapi.top/v1查看模型广场

选择模型

模型 ID	清晰度	参考规格	参考视频	输出时长
`minimax-h3-768p`	768P	503	不支持	4-15 秒
`minimax-h3-2k`	2K	503	不支持	4-15 秒
`minimax-h3-pro-768p`	768P	913	1 段，2-5 秒	4-15 秒
`minimax-h3-pro-2k`	2K	913	1 段，2-5 秒	4-15 秒

以上模型按输出时长计费，生成失败不计费。本文不保存固定金额，实际价格与可用状态以模型广场和控制台消费记录为准。

全能参考规格

三位数字依次表示最多支持的图片、视频和音频数量。例如 933 表示 9 图、3 视频、3 音频。

规格	图片	视频	音频	使用方式
`503`	最多 5 张	0 段	最多 3 段	基础档默认能力
`913`	最多 9 张	最多 1 段	最多 3 段	Pro 档默认能力
`933`	最多 9 张	最多 3 段	最多 3 段	需要联系客服开通

参考素材可使用公网可直接下载的 URL 或 base64。不要使用需要登录、临时授权或有防盗链限制的地址。

生成模式

模式	最少必传	说明
文生视频	`prompt`	纯文字生成；`ratio` 不能使用 `adaptive`
图生视频	`prompt` + `referenceImages`	基础档最多 5 张，Pro 档最多 9 张
首尾帧	`first_image`，可加 `last_image`	不能与 `referenceImages` 同时使用
参考音频	参考图 + `referenceAudios`	最多 3 段，合计不超过 15 秒
参考视频	Pro 模型 + `referenceVideos`	最多 1 段，时长 2-5 秒

请求参数

字段	类型	要求
`model`	string	使用本页列出的 4 个精确模型 ID 之一
`prompt`	string	提示词，最多 7000 个字符
`duration`	integer	4-15 秒，也是按秒计费依据
`ratio`	string	`16:9`、`9:16`、`1:1`、`21:9`、`4:3`、`3:4`、`adaptive`
`referenceImages`	string[]	基础档最多 5 张，Pro 档最多 9 张
`referenceAudios`	string[]	最多 3 段，须配参考图，合计不超过 15 秒
`referenceVideos`	string[]	仅 Pro 档；最多 1 段，时长 2-5 秒
`first_image` / `last_image`	string	首帧与尾帧；不能与 `referenceImages` 同时使用

调用示例

文生视频

curl --request POST "https://api2.cgapi.top/v1/videos" \
  --header "Authorization: Bearer <CGAPI_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{"model":"minimax-h3-2k","prompt":"A calm ocean wave at golden sunset, cinematic","duration":5,"ratio":"16:9"}'

图生视频

curl --request POST "https://api2.cgapi.top/v1/videos" \
  --header "Authorization: Bearer <CGAPI_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{"model":"minimax-h3-768p","prompt":"角色转身微笑，镜头缓慢推近","duration":6,"ratio":"16:9","referenceImages":["https://cdn.example.com/ref1.jpg"]}'

Pro 参考视频驱动

curl --request POST "https://api2.cgapi.top/v1/videos" \
  --header "Authorization: Bearer <CGAPI_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{"model":"minimax-h3-pro-768p","prompt":"角色跟随参考视频的动作与镜头运动","duration":5,"ratio":"16:9","referenceVideos":["https://cdn.example.com/ref.mp4"]}'

轮询与下载

调用 POST /v1/videos 后保存返回的 task_id。
每 5-10 秒请求 GET /v1/videos/{task_id}。
状态为 completed 时读取 video_url；状态为 failed 时停止轮询。
直接 GET video_url 下载 MP4。

curl "https://api2.cgapi.top/v1/videos/TASK_ID" \
  --header "Authorization: Bearer <CGAPI_API_KEY>"

curl --location "VIDEO_URL" --output result.mp4

创建接口返回成功只代表任务已提交。取得 completed 和可下载的 video_url 后，才算生成完成。

约束与排错

2K 和参考视频任务通常更慢；任务仍在排队或处理中时继续轮询同一个 task_id，不要重复提交。
只有任务明确进入 failed 后才考虑修正参数并重新创建；失败任务不计费。
referenceAudios 必须搭配参考图，且全部音频总时长不能超过 15 秒。
first_image / last_image 与 referenceImages 互斥。
文生视频不支持 ratio=adaptive。
业务端应保存请求和任务 ID，并把 API Key 仅保存在服务端。