跳到主要内容

MiniMax H3 接入指南

MiniMax H3 使用原生异步接口，支持 H3/H3-Max 视频生成、H3 2K 升级和 Context-IR 提示词生成。使用平台模型密钥提交任务，保存返回的 task_id，再查询任务结果。

能力与模型名​

能力方法与路径请求体 model分辨率／时长令牌需允许的模型
H3 视频生成POST /v2/video_generationMiniMax-H3必填 768P 或 2K；4–15 秒MiniMax-H3
H3-Max 视频生成POST /v2/video_generationMiniMax-H3-Max480P 或 768P，省略默认 768P；5–15 秒MiniMax-H3-Max
H3 2K 升级POST /v2/video_regenerationMiniMax-H3必填 2KMiniMax-H3-Regeneration
Context-IR 提示词生成POST /v2/h3_context_irMiniMax-H3不传分辨率；4–15 秒MiniMax-H3-Context-IR
查询以上任一任务GET /v2/query/video_generation/{task_id}无请求体返回任务状态与结果使用任务所属用户的模型密钥

升级和 Context-IR 的令牌权限模型名与请求体 model 不同，不能把 MiniMax-H3-Regeneration 或 MiniMax-H3-Context-IR 填入请求体。模型可用性和价格以当前控制台、令牌分组及权限为准。

鉴权与地址​

  • 使用 Authorization: Bearer {apiKey}，其中 {apiKey} 是控制台创建的 sk- 模型密钥，不是管理接口访问令牌或上游 MiniMax 密钥。
  • {baseUrl} 是平台 API 根地址，不含末尾 / 或 /v1。完整地址为 {baseUrl}/v2/...。
  • JSON 参数直接放在请求体顶层，不要增加 body 包装。这组接口使用 /v2 路径及原生字段，请按本目录格式调用。

最小调用示例​

curl -X POST "{baseUrl}/v2/video_generation" \
  -H "Authorization: Bearer {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{"model":"MiniMax-H3","resolution":"768P","duration":4,"ratio":"16:9","content":[{"type":"text","text":"一只小猫在阳光下伸懒腰，镜头缓慢推进"}]}'
{"task_id":"task_platform_example"}

保存返回的真实平台任务 ID，建议每 5–10 秒调用一次查询接口：

curl "{baseUrl}/v2/query/video_generation/{task_id}" \
  -H "Authorization: Bearer {apiKey}"
提交 generation / regeneration / h3_context_ir
                    ↓
             保存平台 task_id
                    ↓
          queued → running → 终态
                              ├─ succeeded：视频取 task.content.url
                              │             IR 取 task.content.prompt
                              └─ failed / cancelled：查看 task.error

HTTP 200 和 task_id 只表示平台已建单，不表示上游一定受理或生成成功。只有查询到 task.status=succeeded 才能按结果字段取用产物。

媒体输入规则​

类型结构role数量限制
文本{"type":"text","text":"提示词"}不需要content 模式至少包含一个非空文本项
图片image_url: {"url":"https://..."}first_frame、last_frame、reference_image；省略时按首帧处理首、尾帧各最多 1 张；参考图最多 9 张
视频video_url: {"url":"https://..."}reference_video；升级接口另支持 base_video参考视频最多 3 个；升级时恰好 1 个 base_video
音频audio_url: {"url":"https://..."}reference_audio最多 3 个
  • 首尾帧不能与任何 reference_* 参考素材混用。
  • 普通生成和 Context-IR 每个文本项最多 7,000 个字符，升级每项最多 40,000 个字符。
  • 普通生成和 Context-IR 只有文本、没有首尾帧或参考素材时，ratio 必须为具体宽高比，不能省略或用 adaptive。
  • ratio 可选值：21:9、16:9、4:3、1:1、3:4、9:16、adaptive。
  • 媒体地址可用上游可访问的 HTTP(S) URL；不支持 asset://。素材尺寸、编解码、时长和模型实际能力还需符合上游要求。
  • Data URI 需要平台启用 Base64-to-OSS；平台会先转存再提交。支持图片 JPEG/PNG/WebP/HEIC/HEIF、视频 MP4/MOV、音频 WAV/MP3。解码后单文件上限分别为图片 30 MiB、视频 50 MiB、音频 15 MiB；请求体总上限 64 MiB。格式、MIME 与文件内容必须匹配。

提交异常与费用​

创建接口不提供客户幂等键。请求可能已发送但无法确认上游受理时，平台可能仍返回 task_id：请保留它并查询，避免重复提交和重复计费。客户端超时且未取得 ID 时，先检查控制台任务日志或联系支持核实，再决定是否重试。

任务先预扣，最终按平台冻结的计价配置及认证查询所得实际用量结算。视频涉及输出时长、输入视频时长和图片数量，Context-IR 涉及输入／输出 Token；以控制台最终结算为准。平台总超时判失败并全额退款后，迟到成功不会恢复任务或补扣。

接口目录​