MiniMax-H3-Max 视频生成 API 文档

概述

MiniMax-H3-Max 是极速视频生成模型，专为高速视频生成而优化。与 MiniMax-H3 共用同一套 /v1/video/generations 接口，分辨率档位和时长范围有所不同。

支持三种生成场景：

文生视频：根据文本描述生成视频

图生视频：首帧、尾帧或首尾帧控制

多模态参考生视频：输入参考图片、参考视频、参考音频驱动生成

不支持再生成（regeneration）和 Context-IR，传入会返回参数错误。

与 MiniMax-H3 的差异对照

维度	MiniMax-H3	MiniMax-H3-Max
模型名	`MiniMax-H3`	`MiniMax-H3-Max`
分辨率	`768P` / `2K`	`480P` / `768P`（不支持 2K）
时长范围	4 ~ 15 秒	5 ~ 15 秒（不支持 4 秒）
额外参数	无	`metadata.prompt_expansion_mode`
再生成	支持	不支持
Context-IR	支持	不支持
输入素材计费	图片/视频按量加收	暂不计费

1. 提交任务与响应结构

鉴权方式：在请求头加 Authorization: Bearer <你的 API Key>，API Key 在平台个人中心获取。

文生视频

提交成功响应（HTTP 200，扁平结构）：

{
  "id": "435190535455101",
  "task_id": "435190535455101",
  "object": "video",
  "model": "MiniMax-H3-Max",
  "status": "",
  "progress": 0,
  "created_at": 1787801999
}

字段	类型	说明
`id`	string	任务 ID，用于后续查询。推荐读这个字段
`task_id`	string	与 `id` 值相同，兼容旧接口保留
`status`	string	建单瞬间为空字符串 `""`，请以查询接口为准
`progress`	integer	建单瞬间为 `0`
`created_at`	integer	建单时间（Unix 秒）

⚠️ 提交响应没有 code/message/data 包裹层，id 在顶层。正确取法：resp["id"]，不是 resp["data"]["task_id"]。

图生视频（首帧）

{
  "model": "MiniMax-H3-Max",
  "prompt": "镜头缓缓推进，人物轻轻转过头望向远方",
  "duration": 8,
  "resolution": "768P",
  "metadata": {
    "first_frame_image": "https://your-cdn.example.com/frame.jpg"
  }
}

图生视频（首尾帧）：

{
  "model": "MiniMax-H3-Max",
  "prompt": "人物从窗边走向书桌，坐下翻开书本",
  "duration": 6,
  "resolution": "480P",
  "metadata": {
    "first_frame_image": "https://your-cdn.example.com/start.jpg",
    "last_frame_image": "https://your-cdn.example.com/end.jpg"
  }
}

图生视频场景下 ratio 由输入图片决定，传了具体比例也会被忽略、强制按 adaptive 处理。

输入图片约束：

格式：JPG、JPEG、PNG、WEBP、HEIC、HEIF

单文件大小：≤ 30 MB

尺寸范围：宽高均在 [256, 5760] px

长宽比：[0.4, 2.5]

数量：首帧 ≤ 1 张，尾帧 ≤ 1 张，参考图 ≤ 9 张

多模态参考生视频

支持三种参考素材，可单独使用也可组合使用。

参考视频 + 参考音频（角色说话）：

{
  "model": "MiniMax-H3-Max",
  "prompt": "角色用参考音色说：欢迎来到未来世界，参考视频中的人物动作",
  "duration": 6,
  "resolution": "768P",
  "ratio": "adaptive",
  "metadata": {
    "reference_videos": ["https://your-cdn.example.com/ref.mp4"],
    "reference_audios": ["https://your-cdn.example.com/voice.mp3"]
  }
}

参考图片（人物或场景参考）：

{
  "model": "MiniMax-H3-Max",
  "prompt": "一位女性角色在海边散步，保持参考图中的人物形象",
  "duration": 5,
  "resolution": "768P",
  "ratio": "16:9",
  "metadata": {
    "reference_images": [
      "https://your-cdn.example.com/character.jpg"
    ]
  }
}

输入视频约束：

格式：MP4 (.mp4)、MOV (.mov)

编码：视频 H.264/AVC、H.265/HEVC；音频 AAC、MP3

单文件大小：≤ 50 MB

数量：≤ 3 段；单段时长 [2, 15] 秒；总时长 ≤ 15 秒

尺寸范围：宽高均在 [256, 5760] px；帧率 [23.976, 60]

输入音频约束：

格式：WAV、MP3

单文件大小：≤ 15 MB

数量：≤ 3 段；单段时长 [2, 15] 秒；总时长 ≤ 15 秒

reference_images 最多 9 张；reference_videos 和 reference_audios 最多各 3 段。

⚠️ 场景互斥：first_frame_image / last_frame_image（图生视频）与 reference_images / reference_videos / reference_audios（多模态参考）不可同时传入，混用返回 400，错误信息：MiniMax-H3: first_frame/last_frame cannot mix with reference_image/video/audio。

2. 查询任务状态

查询响应统一为 {code, message, data:{...}} 包裹结构，业务字段全部在 data 内。

处理中响应：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "435190535455101",
    "action": "generate",
    "status": "IN_PROGRESS",
    "fail_reason": "",
    "submit_time": 1787801998,
    "start_time": 1787802005,
    "finish_time": 0,
    "progress": "50%",
    "data": {
      "task": {
        "id": "435190535455101",
        "model": "MiniMax-H3-Max",
        "status": "running",
        "ratio": "16:9",
        "duration": 5,
        "resolution": "768P",
        "task_type": "generation",
        "created_at": 1787801999,
        "updated_at": 1787801999
      }
    }
  }
}

成功响应：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "435190535455101",
    "action": "generate",
    "status": "SUCCESS",
    "fail_reason": "",
    "result_url": "https://cdn.example.com/output-video.mp4?Expires=...&Signature=...",
    "submit_time": 1787801998,
    "start_time": 1787802005,
    "finish_time": 1787802045,
    "progress": "100%",
    "data": {
      "task": {
        "id": "435190535455101",
        "model": "MiniMax-H3-Max",
        "status": "succeeded",
        "content": {
          "url": "https://cdn.example.com/output-video.mp4?Expires=..."
        },
        "ratio": "16:9",
        "duration": 5,
        "resolution": "768P",
        "task_type": "generation",
        "created_at": 1787801999,
        "updated_at": 1787802043
      }
    }
  }
}

视频地址在 data.result_url（同一地址也出现在 data.data.task.content.url）。该地址为限时地址，请在任务成功后尽快下载或转存。

失败响应：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "435190535455101",
    "action": "generate",
    "status": "FAILURE",
    "fail_reason": "content[1].image_url: media not found (HTTP 404)",
    "result_url": "",
    "submit_time": 1787746910,
    "start_time": 1787746919,
    "finish_time": 1787746925,
    "progress": "100%"
  }
}

status 取值

外层 `data.status`（大写）	`data.data.task.status`（小写）	说明
`NOT_START`	—	未开始
`SUBMITTED`	—	已提交，排队中
`QUEUED`	`queued`	排队中
`IN_PROGRESS`	`running`	生成中
`SUCCESS`	`succeeded`	已完成
`FAILURE`	`failed` / `cancelled`	失败

判断成败以外层大写 data.status 为准。code 字段表示平台调用是否成功，任务本身失败时 code 仍为 "success"，具体原因在 data.fail_reason。

3. 请求参数说明

公共参数

参数	类型	必填	说明
`model`	string	是	固定值 `"MiniMax-H3-Max"`
`prompt`	string	是	视频描述，最多 7000 字符，不可为空
`resolution`	string	是	`480P` 或 `768P`，传其他值返回 400
`duration`	integer	是	视频时长（秒），范围 5 ~ 15，传 4 返回 400
`ratio`	string	条件必填	文生视频必填且不能为 `adaptive`；可选值 `16:9`、`9:16`、`4:3`、`3:4`、`1:1`、`21:9`

metadata 字段

通过请求体顶层 metadata 对象透传，所有字段均可选。

字段	类型	默认值	说明
`prompt_expansion_mode`	string	`balanced`	提示词扩写模式：`disabled` 关闭 / `balanced` 均衡 / `quality` 质量优先
`first_frame_image`	string	—	首帧图片 URL（图生视频）
`last_frame_image`	string	—	尾帧图片 URL（图生视频首尾帧）
`reference_images`	array	—	参考图片 URL 列表（多模态参考生视频，最多 9 张）
`reference_videos`	array	—	参考视频 URL 列表（多模态参考生视频，最多 3 段）
`reference_audios`	array	—	参考音频 URL 列表（多模态参考生视频，最多 3 段）
`callback_url`	string	—	任务状态变更回调地址
`aigc_watermark`	bool	false	是否添加 AIGC 水印

4. 计费规则

按输出视频秒数计费：

分辨率	单价
480P	0.33 元/秒
768P	0.50 元/秒

输入素材（图片、参考视频、参考音频）暂不计费。

5. 常见错误

以下均为实测结果。注意错误可能在不同校验层返回，HTTP 状态码不统一，请勿只按 HTTP 状态码分支，应结合 code 字段判断。

错误场景	HTTP 状态	code	message 示例
传入 `resolution=2K`	400	`invalid_resolution`	`invalid resolution "2K" for MiniMax-H3-Max, only "480P" and "768P" are supported`
传入 `duration=4`	500	`build_request_failed`	`convert request payload failed: duration must be within [5,15] for MiniMax-H3-Max`
`prompt` 为空	400	`invalid_request`	`prompt is required`
首帧图与参考素材混用	500	`build_request_failed`	`convert request payload failed: MiniMax-H3: first_frame/last_frame cannot mix with reference_image/video/audio`
余额不足（禁止阈值）	403	`quota_below_block_threshold`	`余额不足，低于禁止阈值...`
余额预警 + 并发超限	200	`quota_warning_concurrency_limit`	`余额低于预警阈值，视频并发任务数已达上限...`
内容违规	200 任务失败	—	`data.status=FAILURE`，`fail_reason` 含违规描述
素材 URL 不可达	200 任务失败	—	`fail_reason` 含 `media not found (HTTP 404)`

H3-Max 不支持再生成（regeneration）。若传 metadata.task_type=regeneration，请求会被透传到再生成端点并被拒，返回 400 fail_to_fetch_task，message 内嵌上游原始错误（如 unsupported resolution for enhancement）。再生成请改用 MiniMax-H3。

6. 最佳实践

客户端解析

轮询建议

提交后立即返回 task_id，客户端需轮询查询接口

H3-Max 极速版通常比 H3 快，建议间隔：前 20 秒每 2 秒一次，之后每 5 秒一次

超时时间建议 3 分钟

素材输入建议

优先使用公网 HTTPS URL，避免 Base64 大文件导致请求体超限（64 MB）

素材 URL 必须可被公网访问；不可达的 URL 提交时不报错，会在异步执行阶段变成 FAILURE

7. 完整示例：文生视频提交到获取结果

8. 技术支持

如有问题，请联系技术支持团队或查阅完整 API 文档。

MiniMax-H3-Max 视频生成 API 文档

概述#

与 MiniMax-H3 的差异对照#

1. 提交任务与响应结构#

文生视频#

图生视频（首帧）#

多模态参考生视频#

2. 查询任务状态#

status 取值#

3. 请求参数说明#

公共参数#

metadata 字段#

4. 计费规则#

5. 常见错误#

6. 最佳实践#

客户端解析#

轮询建议#

素材输入建议#

7. 完整示例：文生视频提交到获取结果#

8. 技术支持#

概述