MiniMax 海螺：视频生成 API

可用型号

请使用精确 ID MiniMax-H3 / MiniMax-H3-Max / MiniMax-H3-SelfHosted:没有别名,未知模型名会被拒绝。H3-Max 为快速生成版,5 秒成片通常数秒即可生成。分档价与完整规格见模型卡 MiniMax-H3、MiniMax-H3-Max。

MiniMax-H3-SelfHosted 是海螺 H3 的自部署版,效果对标 H3、价格更低。请求契约与 MiniMax-H3 相同,差异如下:分辨率增加 480P、1080P、4K(完整列表见上表);参考视频与参考音频必须是公网 http(s) 地址,不接受 data: 内嵌(图片仍可内嵌);单条成片通常需要 3-6 分钟。它由分组 MiniMax H3 自部署 提供,在控制台归入「自部署」分类。规格与分档价见模型卡 MiniMax-H3-SelfHosted。

MiniMax-H3 与 MiniMax-H3-Max 分属两个分组——MiniMax H3 官方直连与MiniMax H3 Max 官方直连;speech-2.8-hd / speech-2.8-turbo 属于第三个分组 MiniMax 语音 官方直连,用法见语音合成 API。MiniMax-H3-SelfHosted 属于分组 MiniMax H3 自部署;MiniMax-H3-Max 另可通过分组 MiniMax H3 Max 云厂商 调用(同一官方模型,价格不同)。

密钥只能调它所含分组的模型；H3 与 H3-Max 都要用时，把两个分组加进同一把密钥。请在发起付费任务前用 GET /v1/models 确认密钥能调用哪些模型。

请求参数

HopBase 按 MiniMax 官方 v2 接口接入海螺 H3。请求体镜像 MiniMax 官方 POST /v2/video_generation,并做严格解码:未知字段与多余 JSON 值会在请求发出前被拒绝。

顶层只接受下表字段;其他字段(包括 OpenAI 的 prompt / size / n / seconds / image)返回 400。

首尾帧模式的 ratio 接受任意合法值,成片恒为 adaptive(跟随图片);需要特定比例请先裁剪帧图。所有请求使用 Authorization: Bearer sk-your-key 与 Content-Type: application/json。

content 元素

数量、role 与组合在提交时校验;文件大小、尺寸、编码与时长由 MiniMax 在执行时校验。首尾帧与 reference_* 元素在同一请求内互斥,单个请求的媒体素材合计最多 12 个。

媒体 url 接受公网绝对 http(s) 地址或 data: URI(base64 内嵌)。mm_file:// 会被拒绝——该文件归属你自己的 MiniMax 账号,网关无法代取。MiniMax-H3-SelfHosted 的 video_url 与 audio_url 必须是公网 http(s) 地址,data: 仅限图片。

素材规格

输出与请求体大小

• 输出为 24 FPS,每条成片原生自带双声道音频。
• 台词与配音在模型内生成,TTS 覆盖 11 种语言(中/英/日/韩/法/德/西等)。
• 2K 指 16:9~9:16 之间短边 1440 像素;更宽比例保持约 370 万总像素,如 21:9 → 2976×1248。
• 768P 同规则,短边 768 / 约 100 万像素。
• 整个 JSON 请求体上限 64 MiB,超出返回 413。
• base64 会把数据放大约 4/3,改用 data: 内嵌也不会放宽数量与时长限制,大素材请用 URL。

返回结果

MiniMax 任务的字段在响应顶层,没有 task 包装。

提交响应

提交返回 202 与 HopBase 任务 ID:

{
  "id": "mmt60x430684635582774",
  "object": "video.generation.task",
  "model": "MiniMax-H3",
  "status": "queued",
  "billing_bucket": "2k"
}

任务查询字段

只有 completed 与 failed 是终态,其他任何值都按进行中处理。单条成片通常 1.5-3 分钟完成。

进行中

{
  "id": "mmt60x430684635582774",
  "status": "processing"
}

成功

{
  "id": "mmt60x430684635582774",
  "status": "completed",
  "outputs": ["https://api.hop-base.com/..."],
  "usage": { "bucket": "2k", "billed_seconds": 4, "input_seconds": 0, "extra_input_images": 0, "cost": 3.4, "cost_usd": 0.5, "currency": "CNY" }
}

失败

失败任务没有错误码,只能看 error.message(异步任务失败):

{ "id": "mmt60x...", "status": "failed", "error": { "message": "..." } }

最小示例

# 1. 提交,文生视频必须带 ratio
curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [{
      "type": "text",
      "text": "无人机航拍视角,清晨的雪山山脉,云海翻涌,金色阳光洒在山峰上"
    }],
    "resolution": "2K",
    "duration": 4,
    "ratio": "16:9"
  }'

# 2. 用返回的 id 轮询
curl https://api.hop-base.com/v1/video/tasks/mmt你的任务ID \
  -H "Authorization: Bearer sk-your-key"

图生视频把首帧图放进 content:

{
  "model": "MiniMax-H3",
  "content": [
    { "type": "text", "text": "镜头缓缓向前推近,画面中的光影微微流动" },
    { "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,..." }, "role": "first_frame" }
  ],
  "resolution": "768P",
  "duration": 4
}

注意事项

• image_url 不写 role 时按首帧处理,参考模式下每张图都要写 "role": "reference_image"。
• 创建超过 2 小时仍未结束的任务会被自动判为失败,MiniMax 任务不支持取消。
• outputs 是 api.hop-base.com 域名下的签名地址,自任务完成起 24 小时有效。再次查询返回同一地址、不会续期,过期访问返回 410,请在有效期内下载保存。

常见报错 → 改法

网关自身校验返回 {"error":{"message":…,"type":"invalid_request_error"}},不带 code,以 message 为准。

常见的 400 与 413 / 404 原文:

400 first/last-frame image-to-video and multimodal reference generation are mutually exclusive: ...
400 {"error":{"message":"request body does not match the JSON contract: json: unknown field \"prompt\"","type":"invalid_request_error"}}
400 callback_url is not supported yet; poll /v1/video/tasks/{id} for task progress
request body exceeds the 64 MiB limit (got N bytes)
invalid task ID format
task not found            # 用其他用户的密钥查询也是这条

第一条通常是参考模式下漏写了 role;第二条是传了顶层 prompt,提示词请放进 content。

任务失败时按 error.message 处理:

计费

两个模型 MiniMax 都「按秒计费」,单价随输出分辨率走,不按 token 计量:

本次扣费 = usage.billed_seconds × usage.bucket 档的单价

• 参考视频按输入时长以同档单价另计,即 MiniMax 自己的 input_seconds。
• 参考图有免费额度,usage.extra_input_images 是超额张数。
• H3-Max 官方口径是仅输出视频计费,输入素材不计费。
• H3-SelfHosted 的参考视频输入时长向上取整到整秒,按输出档位同价计费;超出 5 张的参考图按张计费。

提交 MiniMax 任务时按「可用余额 − 进行中任务的预估费用 − 本次预估费用」判断,不足返回 402,code 为 insufficient_balance,任务结束后预估自动释放。失败的任务一律不计费。任务结束后,查询响应根对象的 usage 还会带 cost_usd（本任务从余额实际扣除的美元金额，未扣费的失败为 0）、cost（同一笔的人民币金额）与 currency（恒为 CNY）。

官方牌价见价格页。你的实际单价以登录后的模型广场为准,每次请求的实际扣费见用量记录。视频任务通用规则详见视频总览。

下一步

• 视频总览——各视频系列对比与共用的余额预占、超时与结果地址规则
• 语音合成 API——MiniMax Speech 2.8 与声音克隆
• 错误码与重试——含异步任务失败
• 并发、超时与计费