MiniMax H3 视频生成 API

MiniMax H3 使用异步任务模式：创建任务后保存返回的 id，再查询任务状态或通过下载接口获取成片。

接口概览

操作	方法	路径
创建视频	`POST`	`/v1/videos`
查询任务	`GET`	`/v1/videos/{task_id}`
下载成片	`GET`	`/v1/videos/{task_id}/content`

基础地址：https://www.dianlitoken.com

所有接口均使用 Bearer Key：

http

Authorization: Bearer sk-你的KEY

当前模型名：minimax-h3-v2。

创建任务

http

POST /v1/videos
Authorization: Bearer sk-你的KEY
Content-Type: application/json

请求参数

字段	类型	必填	说明
`model`	string	是	`minimax-h3-v2`
`content`	array	条件必填	推荐使用；一个文本项，以及当前模式所需的图片、视频或音频项。纯文生视频可改用 `prompt`
`resolution`	string	是	`768P` 或 `2K`，不区分大小写
`duration`	integer	是	输出时长，4～15 秒整数
`ratio`	string	视模式	文生视频必填；首帧/首尾帧固定为 `adaptive`；参考模式支持固定比例或 `adaptive`
`aigc_watermark`	boolean	否	是否添加 AI 生成水印，默认 `false`

固定画幅支持：21:9、16:9、4:3、1:1、3:4、9:16。

content 必须且只能包含一个非空文本项。素材 URL 必须是服务端可访问的公网 URL，并在任务处理期间保持有效。

素材结构

类型	角色	上限	用途
`text`	无	1	提示词
`image_url`	`first_frame`	1	首帧；图片未写 `role` 时也按首帧处理
`image_url`	`last_frame`	1	尾帧，可单独或配合首帧使用
`image_url`	`reference_image`	9	人物、场景、服装或风格参考
`video_url`	`reference_video`	3	动作、运镜或画面参考
`audio_url`	`reference_audio`	3	声音或节奏参考

参考图片、参考视频和参考音频合计最多 15 个。参考音频不能单独使用，至少还要提供一张参考图片或一个参考视频。

首帧、尾帧和首尾帧属于帧驱动模式，不能与 reference_image、reference_video、reference_audio 混用。

文生视频

bash

curl -X POST 'https://www.dianlitoken.com/v1/videos' \
  -H 'Authorization: Bearer sk-你的KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "minimax-h3-v2",
    "content": [
      {
        "type": "text",
        "text": "清晨的海面薄雾弥漫，镜头缓慢向前推进，电影级光影"
      }
    ],
    "resolution": "768P",
    "duration": 6,
    "ratio": "16:9",
    "aigc_watermark": false
  }'

纯文生视频也支持使用顶层 prompt 代替 content：

json

{
  "model": "minimax-h3-v2",
  "prompt": "清晨的海面薄雾弥漫，镜头缓慢向前推进",
  "resolution": "768P",
  "duration": 6,
  "ratio": "16:9"
}

prompt 与 content 不能同时传入。

图生视频（单首帧）

将输入图片标记为 first_frame，画幅使用 adaptive。这不会被解释为首尾帧模式，除非请求中同时出现 last_frame。

bash

curl -X POST 'https://www.dianlitoken.com/v1/videos' \
  -H 'Authorization: Bearer sk-你的KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "minimax-h3-v2",
    "content": [
      {"type": "text", "text": "人物缓慢转身看向镜头，衣摆随风轻动，镜头平稳推进"},
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/first-frame.jpg"},
        "role": "first_frame"
      }
    ],
    "resolution": "2K",
    "duration": 8,
    "ratio": "adaptive",
    "aigc_watermark": false
  }'

首尾帧生成

同时传入一张 first_frame 和一张 last_frame，模型会生成两帧之间的连续过渡。

bash

curl -X POST 'https://www.dianlitoken.com/v1/videos' \
  -H 'Authorization: Bearer sk-你的KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "minimax-h3-v2",
    "content": [
      {"type": "text", "text": "人物自然转身，镜头稳定，从首帧平滑过渡到尾帧"},
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/first.jpg"},
        "role": "first_frame"
      },
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/last.jpg"},
        "role": "last_frame"
      }
    ],
    "resolution": "2K",
    "duration": 8,
    "ratio": "adaptive",
    "aigc_watermark": false
  }'

多模态参考生成

参考模式可组合图片、视频和音频素材。提示词中可以用 @图片1、@视频1、@音频1 描述对应素材的用途；编号按同类素材在 content 中出现的顺序计算。

bash

curl -X POST 'https://www.dianlitoken.com/v1/videos' \
  -H 'Authorization: Bearer sk-你的KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "minimax-h3-v2",
    "content": [
      {"type": "text", "text": "保持@图片1的人物外观，参考@视频1的运镜，并配合@音频1的节奏"},
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/character.jpg"},
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": {"url": "https://example.com/camera-motion.mp4"},
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": {"url": "https://example.com/rhythm.mp3"},
        "role": "reference_audio"
      }
    ],
    "resolution": "2K",
    "duration": 10,
    "ratio": "adaptive",
    "aigc_watermark": false
  }'

创建成功响应

json

{
  "id": "task_01k3example",
  "task_id": "task_01k3example",
  "object": "video",
  "model": "minimax-h3-v2",
  "status": "queued",
  "progress": 0,
  "created_at": 1787659200
}

请持久化 id。创建响应中的 task_id 是兼容字段，值与 id 相同。

查询任务

bash

curl 'https://www.dianlitoken.com/v1/videos/task_01k3example' \
  -H 'Authorization: Bearer sk-你的KEY'

任务状态：

`status`	含义	建议处理
`queued`	已进入队列	稍后继续查询
`in_progress`	正在生成	稍后继续查询
`completed`	生成完成	读取 `metadata.url` 或调用下载接口
`failed`	生成失败	读取 `error.code` 与 `error.message`

建议每 5～10 秒查询一次，直到进入 completed 或 failed 终态。

生成中响应

json

{
  "id": "task_01k3example",
  "object": "video",
  "model": "minimax-h3-v2",
  "status": "in_progress",
  "progress": 42,
  "created_at": 1787659200
}

成功响应

json

{
  "id": "task_01k3example",
  "object": "video",
  "model": "minimax-h3-v2",
  "status": "completed",
  "progress": 100,
  "created_at": 1787659200,
  "completed_at": 1787659320,
  "metadata": {"url": "https://example.com/generated-video.mp4"}
}

失败响应

json

{
  "id": "task_01k3example",
  "object": "video",
  "model": "minimax-h3-v2",
  "status": "failed",
  "progress": 0,
  "created_at": 1787659200,
  "completed_at": 1787659260,
  "error": {
    "code": "video_generation_failed",
    "message": "视频生成失败，请调整素材或提示词后重试"
  }
}

下载成片

推荐使用带鉴权的下载接口，避免依赖结果地址的有效期：

bash

curl -L 'https://www.dianlitoken.com/v1/videos/task_01k3example/content' \
  -H 'Authorization: Bearer sk-你的KEY' \
  -o result.mp4

参数边界与组合规则

duration 必须是 4～15 的整数；也兼容字段 seconds。如果两个字段同时传入，其值必须一致。
resolution 仅支持 768P、2K。
文生视频必须使用固定画幅，不能使用 adaptive。
首帧、尾帧、首尾帧模式必须使用 adaptive。
参考模式支持固定画幅或 adaptive；未传画幅时按 adaptive 处理。
content 中必须且只能有一个非空 text 项。
最多 9 张参考图片、3 个参考视频、3 个参考音频，且参考素材总数最多 15 个。
参考音频不能单独使用。
帧驱动模式与多模态参考模式不能混用。

常见错误

情况	原因	处理方式
`400` 参数校验失败	时长、分辨率、画幅、角色或素材组合不合法	根据返回的 `error.message` 修正请求
`401` 未授权	API Key 缺失或无效	检查 Bearer Key
`404` 任务不存在	任务 ID 错误，或任务不属于当前账号	使用创建响应中的 `id` 查询
`429` 请求过多	请求频率超过限制	降低频率并采用退避重试
`5xx` 服务异常	网关或模型服务暂时不可用	稍后重试；若已拿到任务 ID，应查询原任务而不是重复创建

创建请求返回 504 Gateway Timeout 且没有任务 ID 时，任务是否已提交成功属于未知状态。为避免产生重复任务和重复费用，请不要立即无条件重复创建；先在任务记录中确认，仍无法确认时再联系支持并提供请求时间与请求 ID。

计费说明

H3 使用组合计费，除了输出视频，还可能包含参考视频、超额参考图片和 Context IR 费用。完整公式、算例、扣费时点与失败退款规则见 H3 计费说明。

MiniMax H3 视频生成 API ​

接口概览 ​

创建任务 ​

请求参数 ​

素材结构 ​

文生视频 ​

图生视频（单首帧） ​

首尾帧生成 ​

多模态参考生成 ​

创建成功响应 ​

查询任务 ​

生成中响应 ​

成功响应 ​

失败响应 ​

下载成片 ​

参数边界与组合规则 ​

常见错误 ​

计费说明 ​

MiniMax H3 视频生成 API

接口概览

创建任务

请求参数

素材结构

文生视频

图生视频（单首帧）

首尾帧生成

多模态参考生成

创建成功响应

查询任务

生成中响应

成功响应

失败响应

下载成片

参数边界与组合规则

常见错误

计费说明