MiniMax H3 API

ReachAPI 通过公开模型 ID minimax-h3 提供 MiniMax Hailuo-03，并使用统一异步视频任务接口。

提交任务：POST /v1/vids/create
查询任务：GET /v1/tasks/{task_id}
执行方式：异步任务；轮询任务接口或提供 callback_url
模型 ID：minimax-h3

认证

Authorization: Bearer YOUR_REACH_API_KEY
Content-Type: application/json

能力与价格

时长	分辨率	比例	输入模式
`4` 到 `15` 秒整数	`2K`、`768P`	`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`adaptive`	文本、首帧、首尾帧、多模态参考

必须显式传入 input.content，且至少包含一个非空文本项。网关不会把旧字段 prompt、image_url 或 image_urls 自动转换为 content。

计费项	2K	768P
输出视频	$0.13 / 秒	$0.08 / 秒
参考视频输入	$0.13 / 秒	$0.08 / 秒
输入图片	前 5 张免费，第 6 张起 $0.04 / 张	前 5 张免费，第 6 张起 $0.04 / 张
输入音频	免费	免费

任务成功后根据实际用量结算；参考视频输入使用请求输出分辨率对应的秒价。

提交任务

{
  "model": "minimax-h3",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "content": [
      {
        "type": "text",
        "text": "A paper boat drifts through a rainy street at night"
      }
    ],
    "duration_seconds": 6,
    "resolution": "2K",
    "aspect_ratio": "16:9"
  }
}

顶层参数

字段	类型	必填	说明
`model`	string	是	固定为 `minimax-h3`
`callback_url`	string	否	任务终态 HTTPS 回调地址，最大 2048 字符，禁止本地或内网目标
`input`	object	是	视频生成参数

`input` 参数

字段	类型	必填	说明
`content`	object array	是	非空显式输入，至少含一个非空文本项
`resolution`	string	是	`2K` 或 `768P`
`duration_seconds`	integer	是	`4` 到 `15` 之间的整数
`aspect_ratio`	string	条件必填	纯文本请求必填，规则见下文

码率、帧率以及视频和音频编码由平台决定，不能配置。完整请求体不得超过 64 MB。

比例规则

输入模式	规则
纯文本	必填且不能是 `adaptive`，只能使用六种固定比例
首帧或首尾帧	输出始终跟随输入图片比例；即使传入 `aspect_ratio`，该值也会被忽略
多模态参考模式	可选；指定固定比例时会生效，省略或传 `adaptive` 时跟随参考素材比例

`input.content`

类型	`role`	上限	说明
`text`	无	—	至少一个非空文本项；每个文本项最多 7000 个字符
`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	音频参考

URL 分别放在 image_url.url、video_url.url 或 audio_url.url。视频必须使用 reference_video，音频必须使用 reference_audio。

同一请求不能混用首尾帧输入与 reference_image、reference_video、reference_audio。

支持四种模式：

文生视频：text
首帧图生视频：text + first_frame
首尾帧：text + first_frame + last_frame
多模态参考：text + 一个或多个 reference_*

多个素材按数组顺序在提示词中引用为 Image 1、Image 2、Video 1、Audio 1，不要使用 Seedance 风格的 @ 引用。

输入素材要求

输入	格式	大小	其他约束
图片	JPG、JPEG、PNG、WEBP、HEIC、HEIF	每张 ≤30 MB	每边 256–5760 px，宽高比 0.4–2.5
参考视频	MP4、MOV	每个 ≤50 MB	宽和高均为 256–5760 px；宽高比 0.4–2.5；H.264/H.265；AAC/MP3；单个 2–15 秒；总计 ≤15 秒；23.976–60 fps
参考音频	WAV、MP3	每个 ≤15 MB	单个 2–15 秒，总计 ≤15 秒

素材 URL 必须能被上游服务端抓取。不支持 Base64、data: URI 或 mm_file:// 句柄。

请求示例

首帧图生视频

{
  "model": "minimax-h3",
  "input": {
    "content": [
      { "type": "text", "text": "The camera slowly pulls back" },
      {
        "type": "image_url",
        "role": "first_frame",
        "image_url": { "url": "https://cdn.example.com/start.jpg" }
      }
    ],
    "duration_seconds": 5,
    "resolution": "2K"
  }
}

首尾帧

{
  "model": "minimax-h3",
  "input": {
    "content": [
      {
        "type": "text",
        "text": "A smooth transition from close-up to wide shot"
      },
      {
        "type": "image_url",
        "role": "first_frame",
        "image_url": { "url": "https://cdn.example.com/start.jpg" }
      },
      {
        "type": "image_url",
        "role": "last_frame",
        "image_url": { "url": "https://cdn.example.com/end.jpg" }
      }
    ],
    "duration_seconds": 5,
    "resolution": "768P",
    "aspect_ratio": "adaptive"
  }
}

多模态参考

{
  "model": "minimax-h3",
  "input": {
    "content": [
      {
        "type": "text",
        "text": "Replace the person in Video 1 with Image 1 and synchronize the action to Audio 1"
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://cdn.example.com/person.png" }
      },
      {
        "type": "video_url",
        "role": "reference_video",
        "video_url": { "url": "https://cdn.example.com/motion.mp4" }
      },
      {
        "type": "audio_url",
        "role": "reference_audio",
        "audio_url": { "url": "https://cdn.example.com/beat.mp3" }
      }
    ],
    "duration_seconds": 5,
    "resolution": "2K"
  }
}

响应与轮询

提交响应：

{
  "code": 200,
  "msg": "",
  "status": "queued",
  "task_id": "task_xxx",
  "data": []
}

轮询 GET /v1/tasks/task_xxx，直到 status 为 success 或 failed。

{
  "code": 200,
  "status": "success",
  "task_id": "task_xxx",
  "data": [{ "url": "https://cdn.example.com/generated/video-1.mp4" }],
  "cost": { "spend": 0.52 },
  "billing": [
    {
      "metric": "VIDEO_SECONDS",
      "quantity": 4,
      "unit": 1,
      "price": 130000,
      "amount": 520000,
      "conditions": { "resolution": "2K" }
    }
  ]
}

cost.spend 以美元展示，billing 是 credits 计费明细。结果 URL 可能过期，请及时转存。5 秒 / 2K 文生视频通常约需 3 分钟，请据此配置轮询。

错误

状态码	说明
400	字段缺失或非法、模式冲突、素材超限
401	API Key 无效
402	余额不足
422	内容安全拦截
429	限流，请退避重试
500 / 502	模型或上游服务暂时不可用

失败任务会返回 status: "failed" 和 error_code；未产生费用时 cost.spend 为 0。

MiniMax H3 API

On this page