MiniMax H3 视频生成

使用 EasyRouter 统一接口调用 MiniMax H3（MiniMax-H3）视频生成模型，支持文生视频、图生视频、参考生视频，并按上游用量精确计费。

MiniMax H3（MiniMax-H3）是 MiniMax 推出的新一代视频生成模型。EasyRouter 将其 v2 异步任务接口封装为统一的 /v1/video/generations 接口对外提供服务，一个模型名即可覆盖文生视频、图生视频、参考生视频三种能力——生成模式由你传入的媒体内容自动判定。

MiniMax H3 是异步任务型接口：提交后立即返回 task_id，你需要轮询任务状态，成功后从 data.result_url 下载视频。

一、模型与能力

只有一个模型名：MiniMax-H3。生成模式由请求中带了什么媒体输入自动决定：

生成模式	触发条件	媒体输入
文生视频（t2v）	只有 `prompt`	无
图生视频（i2v）	传入首帧图（可选尾帧图）	`input_reference` / `images`
参考生视频（r2v）	传入参考图 / 参考视频 / 参考音频	顶层 `media[]` 数组

无论哪种模式，prompt（文本提示词）始终必填。

二、计费说明（重要）

MiniMax H3 按上游返回的真实用量精确计费，公式：

费用(USD) = 总计费秒数 × 分辨率单价 + 计费参考图数 × $0.04
其中：总计费秒数 = 输入参考视频计费时长 + 生成视频时长

分辨率	单价
2K	$0.13 / 秒
768P	$0.09 / 秒（暂未开放调用）

要点：

输入参考视频也计费：r2v 传入参考视频时，其计费时长按输出视频的分辨率单价计入总秒数。
参考图另计：每张计费参考图 $0.04。
提交时预扣、完成时按真实用量结算：提交任务时按输出时长预扣一笔；任务成功后 EasyRouter 用上游返回的 usage 精确重算，多退少补。因此文生/图生视频提交时即可算准，参考生视频（含输入视频）以完成时的真实用量为最终费用。
与 MiniMax 官方刊例价保持一致。

当前 v2 接口 resolution 仅支持 2K。768P 单价已配置，待上游开放后即可调用。

三、提交任务

POST /v1/video/generations

请求头

Header	必填	说明
`Authorization`	✓	`Bearer sk-你的APIKey`
`Content-Type`	✓	`application/json`

请求体字段

字段	类型	必填	说明
`model`	string	✓	固定为 `MiniMax-H3`
`prompt`	string	✓	文本提示词
`resolution`	string	—	分辨率，目前仅 `2K`（默认 `2K`）
`duration`	int	—	生成视频时长（秒），取值 `4~15`，默认 `6`
`ratio`	string	—	宽高比，如 `16:9` / `9:16` / `1:1` / `adaptive`。文生视频默认 `16:9`；图生视频默认 `adaptive`（跟随首帧图）
`input_reference`	string	图生视频	首帧图 URL（公网可访问 / base64）
`images`	string[]	图生视频	图像数组：第 1 张作首帧、第 2 张作尾帧
`media`	object[]	参考生视频	结构化媒体输入，见下

`media[]` 元素

用于参考生视频（r2v），精确指定每个参考素材的角色：

`type`	映射角色	用途
`reference_image`	参考图	参考图片（可多张）
`reference_video`	参考视频	参考视频（其计费时长计入总秒数）
`reference_audio`	参考音频	参考音频
`first_frame` / `last_frame`	首帧 / 尾帧	图生视频的首/尾帧图

{
  "media": [
    { "type": "reference_image", "url": "https://.../ref.jpg" },
    { "type": "reference_video", "url": "https://.../ref.mp4" },
    { "type": "reference_audio", "url": "https://.../ref.mp3" }
  ]
}

未传结构化 media 时，EasyRouter 会从 images / input_reference 按扩展名与顺序自动推断：视频→参考视频、音频→参考音频、第 1 张图→首帧、第 2 张图→尾帧。需要精确控制角色时请使用 media[]。

参考音频（reference_audio）目前受上游支持限制：实测上游会返回任务失败（EasyRouter 会自动全额退款）。如需音频输入能力，请先与我们确认可用性。文生视频、图生视频（首帧 / 首+尾帧）、参考图 / 参考视频生视频均可正常使用。

响应

{
  "id": "task_9dxfuz8h5gxBvdIqvyoVnZr3DVJxzI1o",
  "task_id": "task_9dxfuz8h5gxBvdIqvyoVnZr3DVJxzI1o",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "queued",
  "progress": 0,
  "created_at": 1778250615
}

id / task_id 是 EasyRouter 生成的公开 ID（task_ 前缀），用于后续查询，不等于上游 MiniMax 的 task_id。

四、查询任务状态

GET /v1/video/generations/{task_id}

响应采用 EasyRouter 统一的 {code, message, data} 包装格式。

响应（成功 / SUCCESS）

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_9dxfuz8h5gxBvdIqvyoVnZr3DVJxzI1o",
    "status": "SUCCESS",
    "result_url": "https://.../output.mp4",
    "progress": "100%",
    "quota": 390000,
    "properties": {
      "upstream_model_name": "MiniMax-H3",
      "origin_model_name": "MiniMax-H3"
    },
    "data": {
      "task": {
        "status": "succeeded",
        "content": { "url": "https://.../output.mp4" },
        "resolution": "2K",
        "duration": 6,
        "ratio": "16:9",
        "usage": {
          "total_seconds": 6,
          "input_seconds": 0,
          "output_seconds": 6,
          "input_image_count": 0
        }
      }
    }
  }
}

状态枚举

统一状态	对应 MiniMax 状态	说明
`QUEUED`	`queued` / `preparing`	已进入队列
`IN_PROGRESS`	`running`	生成中
`SUCCESS`	`succeeded`	已完成，`result_url` 为视频地址
`FAILURE`	`failed` / `cancelled` / `expired`	生成失败，`fail_reason` 为失败原因

关键字段

字段	说明
`data.result_url`	视频结果 URL（仅 `SUCCESS` 时非空）
`data.quota`	本次任务最终扣费 quota（完成后已按真实用量结算）
`data.data.task.usage`	上游返回的精确用量，即计费依据

视频 URL 是上游临时签名链接，有效期有限，获取后请尽快下载或转存到你自己的存储。

五、完整调用示例

# Step 1: 提交任务
curl -X POST https://easyrouter.io/v1/video/generations \
  -H "Authorization: Bearer sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "一只猫在阳光下打盹，毛毛随风轻轻摇曳",
    "resolution": "2K",
    "duration": 6,
    "ratio": "16:9"
  }'

# Step 2: 轮询（建议间隔 10~15 秒）
curl https://easyrouter.io/v1/video/generations/task_9dxfuz8h5gxBvdIqvyoVnZr3DVJxzI1o \
  -H "Authorization: Bearer sk-你的APIKey"

# Step 3: data.status == "SUCCESS" 后，从 data.result_url 下载视频

# i2v：input_reference 传首帧图；如需尾帧，用 images 传两张
curl -X POST https://easyrouter.io/v1/video/generations \
  -H "Authorization: Bearer sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "镜头缓慢推近，画面生动起来",
    "resolution": "2K",
    "duration": 6,
    "input_reference": "https://example.com/first.jpg"
  }'

图生视频默认宽高比 adaptive（跟随首帧图）。首帧+尾帧插值时用 "images": ["首帧URL", "尾帧URL"]。

# r2v：通过顶层 media[] 传入参考图 / 参考视频 / 参考音频
curl -X POST https://easyrouter.io/v1/video/generations \
  -H "Authorization: Bearer sk-你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "参考给定素材生成一段连贯的视频",
    "resolution": "2K",
    "duration": 6,
    "media": [
      { "type": "reference_image", "url": "https://example.com/ref.jpg" },
      { "type": "reference_video", "url": "https://example.com/ref.mp4" },
      { "type": "reference_audio", "url": "https://example.com/ref.mp3" }
    ]
  }'

参考生视频含输入参考视频时，其时长会计入计费总秒数，最终费用以任务成功后 usage 的真实用量为准。

六、轮询建议

项	建议
轮询间隔	10~15 秒一次，不要小于 5 秒以避免限流
终态判断	`data.status == "SUCCESS"` 或 `data.status == "FAILURE"`
总超时时间	建议 5~10 分钟
视频 URL 有效期	有限，获取后请立即下载或转存

七、错误处理

场景	说明
未传 `prompt`	HTTP 400，`prompt is required`（提交前拦截，不扣费）
`401 / 403`	API Key 无效 / 无权访问此模型
`402`	余额不足（`insufficient user quota`），请充值
任务 `FAILURE`	上游生成失败，见 `data.fail_reason`；EasyRouter 会自动退款