MiniMax H3 视频 API 调用说明

本文说明本系统对 MiniMax H3 视频模型的统一异步接口。请求先提交到本系统，再由 MiniMax 渠道适配器调用上游 V2 接口：

本系统 POST /v1/video/generations
        -> MiniMax POST /v2/video_generation
本系统 GET  /v1/video/generations/{task_id}
        -> MiniMax GET /v2/query/video_generation/{upstream_task_id}

调用方使用本系统令牌，不需要直接暴露 MiniMax API Key。查询时使用本系统返回的 task_id；上游任务 ID 只保存在服务端。

示例来源与转换规则

本文的提示词和素材地址取自以下来源：

官方创建视频生成任务文档：太空歌剧文生视频、拉面首帧图片、角色说话的参考视频与音频。

官方视频生成使用指南：女孩成长的首尾帧图片，以及街舞参考图片与视频。

官方查询任务文档：查询响应示意中使用的视频产物地址。

供应商提供的《H3 所有版本说明》私有文档：H3 480P、H3-Fast 的提示词与 style1 要求，以及 H3-Max-Turbo 的能力和参数。未公开 SKU 的规格以这份私有文档为准。

示例保留来源中的完整提示词与媒体 URL。为适配本系统，纯文本请求使用 prompt，多模态请求将上游 content 放入 metadata.content，扩写选项放入 metadata.extra；请求地址及令牌改为本系统的地址及令牌。跨 SKU 复用素材的示例会单独标明。

只需替换 <NEW_API_BASE_URL>、<NEW_API_TOKEN> 和查询时的 <TASK_ID>。文档中的官方素材地址可以直接作为请求参数，远端资源的后续有效性由供应商维护。

创建任务

基本请求体

{
  "model": "MiniMax-H3",
  "prompt": "史诗级太空歌剧院线预告：女舰长独自站在巨大观景窗前，最后一支舰队正在集结并跃迁离去，强光爆闪、舰桥震动，她被留在原地。",
  "resolution": "2K",
  "duration": 5,
  "ratio": "16:9"
}

字段说明：

字段	类型	必填	说明
`model`	string	是	MiniMax H3 SKU，见下表。也可以使用管理员配置的本地模型名，再通过模型重定向映射到上游 SKU。
`prompt`	string	条件必填	非空文本提示词，最多 7000 个字符。使用 `metadata.content` 时，在该数组中提供非空 `text` 项即可，网关会提取文本供统一校验，无需重复填写顶层 `prompt`；顶层 `prompt` 不会自动补入数组。
`image`	string	否	单张图片 URL、`mm_file://{file_id}` 或 data URI，作为首帧。
`images`	string[]	否	图片数组。没有显式角色时，第一张为首帧、第二张为尾帧。
`resolution` / `size`	string	否	`480P`、`768P`、`2K`。也接受常见大小写写法；最终按模型能力校验。
`duration`	integer	否	输出时长，单位秒。H3 为 4~~15 秒，其他 H3 SKU 为 5~~15 秒；默认 5 秒。
`seconds`	string	否	`duration` 的兼容写法。两者同时存在时优先使用 `duration`。
`ratio`	string	文生必填	`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。图生视频固定按输入图片使用 `adaptive`。参考生视频默认 `adaptive`。
`style`	string	部分模型	H3 480P 可选私有 style；H3-Fast 必须为 `style1`。其他模型不能随意传入。
`metadata`	object	否	多模态内容和模型专属扩展参数，见下文。
`callback_url`	string	否	本系统任务回调地址。回调由网关发送，不会透传给 MiniMax；验证和回调格式以本系统视频任务回调文档为准。

支持的模型

模型	分辨率	时长	支持模式	额外要求
`MiniMax-H3`	`480P`、`768P`、`2K`	4~15 秒	文生、图生、首尾帧、参考生	`480P` 可选私有 `style`。
`MiniMax-H3-Fast`	`480P`	5~15 秒	文生、图生、首尾帧、参考生	必须传 `style: "style1"`。
`MiniMax-H3-Max`	`480P`、`768P`	5~15 秒	文生、图生、首尾帧、参考生	支持 `extra.prompt_expansion_mode`。
`MiniMax-H3-Max-Turbo`	`480P`、`768P`	5~15 秒	图生、首尾帧、参考生	不支持纯文生；支持 `extra.prompt_expansion_mode`。

H3 的默认分辨率为 768P，H3-Fast 的默认分辨率为 480P，H3-Max 和 H3-Max-Turbo 的默认分辨率为 768P。

旧的 MiniMax-Hailuo-* 模型仍使用旧 Hailuo 协议，不属于本文的 H3 V2 请求格式。

刊例价

以下价格来自供应商提供的 H3 私有版本说明，按生成或输入素材的实际秒数计费。本文先列国内价格，价格仅用于接口调用和管理员配置参考，实际扣费还会叠加本系统的模型价格、分组倍率和客户侧倍率。

视频输出价格

模型	分辨率	国内刊例价
`MiniMax-H3`	`480P`	0.25 元/秒
`MiniMax-H3`	`768P`	0.50 元/秒
`MiniMax-H3`	`2K`	0.80 元/秒
`MiniMax-H3-Fast`	`480P`	0.30 元/秒
`MiniMax-H3-Max`	`480P`	0.33 元/秒
`MiniMax-H3-Max`	`768P`	0.50 元/秒
`MiniMax-H3-Max-Turbo`	`480P`	0.17 元/秒
`MiniMax-H3-Max-Turbo`	`768P`	0.26 元/秒

例如 H3 生成 5 秒 2K 视频，供应商输出刊例价为 0.80 × 5 = 4.00 元

输入素材价格

模型	音频	图片	参考视频
`MiniMax-H3`	免费	5 张以内免费，超出部分 0.20 元/张	按生成分辨率计费：`2K` 为 0.80 元/秒；`768P` 为 0.50 元/秒
`MiniMax-H3-Fast`	免费	5 张以内免费，超出部分 0.20 元/张	按输入视频时长计费，0.30 元/秒
`MiniMax-H3-Max`	免费	2 张以内免费，超出部分 0.50 元/张	`480P` 为 0.37 元/秒；`768P` 为 0.97 元/秒
`MiniMax-H3-Max-Turbo`	免费	2 张以内免费，超出部分 0.50 元/张	`480P` 为 0.37 元/秒；`768P` 为 0.97 元/秒

H3 参考视频输入价格：480P、768P 均为 0.50 元/秒，2K 为 0.80 元/秒。

音频输入免费。参考视频输入费用按视频时长计费，任务完成后的费用以 MiniMax 返回的实际用量为准。

多模态输入

需要显式指定用途、首尾帧或参考素材时，建议使用 metadata.content。数组必须包含一个非空 text 项；媒体项必须带 role。

支持的内容类型和角色：

`type`	`role`	用途
`text`	不填	视频提示词。每次请求至少一个非空文本项。
`image_url`	`first_frame`	首帧图生视频。
`image_url`	`last_frame`	尾帧图生视频，需与 `first_frame` 成对。
`image_url`	`reference_image`	多模态参考生视频。最多 9 张。
`video_url`	`reference_video`	多模态参考生视频。最多 3 段，总时长不超过 15 秒。
`audio_url`	`reference_audio`	多模态参考生视频。最多 3 段，总时长不超过 15 秒。

first_frame / last_frame 与 reference_image / reference_video / reference_audio 不能混用。媒体地址会原样转发，支持公网 URL、mm_file://{file_id} 和对应 data URI。

H3 480P 文生视频

以下提示词和参数来自私有文档的 H3 480P 文生视频示例。H3 480P 可以选传供应商约定的 style，原示例未填写，因此这里也不填。

curl.exe -X POST "https://<NEW_API_BASE_URL>/v1/video/generations" `
  -H "Authorization: Bearer <NEW_API_TOKEN>" `
  -H "Content-Type: application/json" `
  -d '{
    "model": "MiniMax-H3",
    "prompt": "史诗级太空歌剧院线预告：女舰长独自站在巨大观景窗前，最后一支舰队正在集结并跃迁离去，强光爆闪、舰桥震动，她被留在原地。",
    "resolution": "480P",
    "duration": 5,
    "ratio": "16:9"
  }'

H3-Fast 文生视频

来自私有文档 2.5.1，保留原提示词、480P 和 style1。

{
  "model": "MiniMax-H3-Fast",
  "prompt": "一艘飞船驶过星云",
  "style": "style1",
  "resolution": "480P",
  "duration": 5,
  "ratio": "16:9"
}

也可以将 style 放在 metadata.style。缺少 style1 或传入其他值时，网关会在提交上游前返回 400。

H3-Max 提示词扩写

prompt_expansion_mode 仅对 H3-Max 和 H3-Max-Turbo 生效，可选 disabled、balanced、quality。不传时由上游使用默认的 balanced。

此例复用官方 H3 文生视频的原提示词，将模型改为 H3-Max、分辨率改为其支持的 768P，并演示开启 quality 扩写。

{
  "model": "MiniMax-H3-Max",
  "prompt": "史诗级太空歌剧院线预告：女舰长独自站在巨大观景窗前，最后一支舰队正在集结并跃迁离去，强光爆闪、舰桥震动，她被留在原地。",
  "resolution": "768P",
  "duration": 5,
  "ratio": "16:9",
  "metadata": {
    "extra": {
      "prompt_expansion_mode": "quality"
    }
  }
}

首帧图生视频

提示词、首帧图片、2K 和 5 秒参数来自官方创建接口的 i2va 示例。单图可以直接使用 image：

{
  "model": "MiniMax-H3",
  "prompt": "Pull focus to the people in the background and add more steam to the ramen bowl.",
  "image": "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/H3_AA_I2VA/gallery/sr_v17_variants_seed42_43_20260724/inputs/4a3a90bf9100_KDmcbkhzYo5sjjxr9FqcVmWVnzb.png",
  "resolution": "2K",
  "duration": 5,
  "ratio": "adaptive"
}

也可以用 metadata.content 明确标注首帧：

{
  "model": "MiniMax-H3",
  "resolution": "2K",
  "duration": 5,
  "ratio": "adaptive",
  "metadata": {
    "content": [
      {
        "type": "text",
        "text": "Pull focus to the people in the background and add more steam to the ramen bowl."
      },
      {
        "type": "image_url",
        "role": "first_frame",
        "image_url": {
          "url": "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/H3_AA_I2VA/gallery/sr_v17_variants_seed42_43_20260724/inputs/4a3a90bf9100_KDmcbkhzYo5sjjxr9FqcVmWVnzb.png"
        }
      }
    ]
  }
}

图生视频的宽高比由输入图片决定，网关会将 ratio 处理为 adaptive。即使传入具体比例，也不会覆盖图片比例。

H3-Fast 首帧图生视频

来自私有文档 2.5.2，保留其提示词和原图片地址，仅修复原文复制时插入 URL 的空格与换行。

{
  "model": "MiniMax-H3-Fast",
  "style": "style1",
  "resolution": "480P",
  "duration": 5,
  "ratio": "adaptive",
  "metadata": {
    "content": [
      {
        "type": "text",
        "text": "让画面中的飞船缓慢驶过星云，保持电影感的镜头运动。"
      },
      {
        "type": "image_url",
        "role": "first_frame",
        "image_url": {
          "url": "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/H3_AA_I2VA/gallery/sr_v17_variants_seed42_43_20260724/inputs/4a3a90bf9100_KDmcbkhzYo5sjjxr9FqcVmWVnzb.png"
        }
      }
    ]
  }
}

首尾帧图生视频

官方视频生成使用指南提供了真实成对的首尾帧图片，配套提示词为 A little girl grows up.：

{
  "model": "MiniMax-H3",
  "resolution": "2K",
  "duration": 5,
  "ratio": "adaptive",
  "metadata": {
    "content": [
      {
        "type": "text",
        "text": "A little girl grows up."
      },
      {
        "type": "image_url",
        "role": "first_frame",
        "image_url": {
          "url": "https://filecdn.minimax.chat/public/fe9d04da-f60e-444d-a2e0-18ae743add33.jpeg"
        }
      },
      {
        "type": "image_url",
        "role": "last_frame",
        "image_url": {
          "url": "https://filecdn.minimax.chat/public/97b7cd08-764e-4b8b-a7bf-87a0bd898575.jpeg"
        }
      }
    ]
  }
}

使用顶层 images 时，第一张和第二张会按首帧、尾帧处理；需要角色以外的内容时应改用 metadata.content。

H3-Max-Turbo 首尾帧视频

私有文档中的 Turbo 首尾帧示例使用的是占位图片。下面复用官网指南中成对的真实图片及原提示词，按私有文档将型号设为 MiniMax-H3-Max-Turbo、分辨率设为 768P，并使用 quality 扩写：

{
  "model": "MiniMax-H3-Max-Turbo",
  "resolution": "768P",
  "duration": 5,
  "ratio": "adaptive",
  "metadata": {
    "content": [
      {
        "type": "text",
        "text": "A little girl grows up."
      },
      {
        "type": "image_url",
        "role": "first_frame",
        "image_url": {
          "url": "https://filecdn.minimax.chat/public/fe9d04da-f60e-444d-a2e0-18ae743add33.jpeg"
        }
      },
      {
        "type": "image_url",
        "role": "last_frame",
        "image_url": {
          "url": "https://filecdn.minimax.chat/public/97b7cd08-764e-4b8b-a7bf-87a0bd898575.jpeg"
        }
      }
    ],
    "extra": {
      "prompt_expansion_mode": "quality"
    }
  }
}

删除 last_frame 项即可改为首帧图生视频。Turbo 不支持纯文生视频。

多模态参考生视频

来自官方创建接口的 r2va 示例，保留完整提示词、参考视频与音频地址，以及 2K、5 秒和 adaptive 参数：

{
  "model": "MiniMax-H3",
  "resolution": "2K",
  "duration": 5,
  "ratio": "adaptive",
  "metadata": {
    "content": [
      {
        "type": "text",
        "text": "角色说话：Follow the wind, live free.Leave worries behind, enjoy the moment，音色参考音频1"
      },
      {
        "type": "video_url",
        "role": "reference_video",
        "video_url": {
          "url": "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/h3_promo_eval_ref2va/gallery/sr_v2p26_trio_seed42_20260724/inputs/297573323635_00_%E8%A7%86%E9%A2%911_YnyRbxEwio_video_20260525_163755_1927e9d3.mp4"
        }
      },
      {
        "type": "audio_url",
        "role": "reference_audio",
        "audio_url": {
          "url": "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/h3_promo_eval_ref2va/gallery/sr_v2p26_trio_seed42_20260724/inputs/f463d523c5ce_01_%E9%9F%B3%E9%A2%911_RSLcbpzJPo_6%E6%9C%885%E6%97%A5(1).mp3"
        }
      }
    ]
  }
}

H3-Fast 多模态参考生视频

来自私有文档 2.5.3，使用同一组参考视频、音频和完整提示词；模型为 H3-Fast，必须传 style1，分辨率为 480P。

{
  "model": "MiniMax-H3-Fast",
  "style": "style1",
  "resolution": "480P",
  "duration": 5,
  "ratio": "adaptive",
  "metadata": {
    "content": [
      {
        "type": "text",
        "text": "角色说话：Follow the wind, live free.Leave worries behind, enjoy the moment，音色参考音频1"
      },
      {
        "type": "video_url",
        "role": "reference_video",
        "video_url": {
          "url": "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/h3_promo_eval_ref2va/gallery/sr_v2p26_trio_seed42_20260724/inputs/297573323635_00_%E8%A7%86%E9%A2%911_YnyRbxEwio_video_20260525_163755_1927e9d3.mp4"
        }
      },
      {
        "type": "audio_url",
        "role": "reference_audio",
        "audio_url": {
          "url": "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/h3_promo_eval_ref2va/gallery/sr_v2p26_trio_seed42_20260724/inputs/f463d523c5ce_01_%E9%9F%B3%E9%A2%911_RSLcbpzJPo_6%E6%9C%885%E6%97%A5(1).mp3"
        }
      }
    ]
  }
}

参考图片与视频组合

以下提示词、两张参考图片及参考视频来自官方视频生成使用指南的街舞示例：

{
  "model": "MiniMax-H3",
  "resolution": "2K",
  "duration": 5,
  "metadata": {
    "content": [
      {
        "type": "text",
        "text": "人物参考视频1的动作，表演街舞，人物参考图1 图2"
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": {
          "url": "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/h3_promo_eval_ref2va/gallery/sr_v2p26_trio_seed42_20260724/inputs/9d5c7a33fa6e_01_%E5%9B%BE1_MHGgbVga3o_gpt4o-image-1780651118146.png"
        }
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": {
          "url": "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/h3_promo_eval_ref2va/gallery/sr_v2p26_trio_seed42_20260724/inputs/7af326902315_00_%E5%9B%BE2_YqtKbY1jpo_u4391985813_Young_male_wearing_cream_hoodie_and_dark_brown_sh_45d56ed0-d626-4c37-9a5b-77f51f374982_1.png"
        }
      },
      {
        "type": "video_url",
        "role": "reference_video",
        "video_url": {
          "url": "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/h3_promo_eval_ref2va/gallery/sr_v2p26_trio_seed42_20260724/inputs/d9060f5cb9ab_02_%E8%A7%86%E9%A2%911_HDvmbpQrEo_%E8%A1%97%E8%88%9E3.mp4"
        }
      }
    ]
  }
}

素材时长与实际核算

reference_video_seconds / reference_audio_seconds 用于计算输入素材费用，应填写对应素材的总时长，取值为 2~15 秒。

任务成功后，费用以 MiniMax 返回的实际输出时长、参考视频时长和输入图片数量为准；音频输入免费。若未返回实际输出时长，则按任务返回的输出时长计算。

水印

可通过 metadata.aigc_watermark 或 metadata.watermark 指定是否添加 AIGC 水印：

这里复用官方创建接口 schema 中的“一个男孩在海边打篮球”提示词，增加水印开关。

{
  "model": "MiniMax-H3",
  "prompt": "一个男孩在海边打篮球",
  "duration": 5,
  "ratio": "16:9",
  "metadata": {
    "aigc_watermark": true
  }
}

创建响应

创建成功后，返回本系统生成的任务 ID。响应为 OpenAI Video 风格对象：

{
  "id": "video_01J...",
  "task_id": "video_01J...",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "queued",
  "progress": 0
}

不要使用 MiniMax 返回的上游 task_id 调用本系统查询接口。

查询任务

curl.exe -X GET "https://<NEW_API_BASE_URL>/v1/video/generations/<TASK_ID>" `
  -H "Authorization: Bearer <NEW_API_TOKEN>"

以下为统一接口响应结构示意，任务 ID、费用和时间以实际返回为准；视频地址采用官方查询文档中的示例产物地址。

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "video_01J...",
    "action": "generate",
    "status": "SUCCESS",
    "quota": 1250000,
    "result_url": "https://video-product.cdn.minimax.io/inference_output/rollout/2026-07-27/6c68f487-4b33-48cb-8c92-1631f63f6682/output.mp4",
    "submit_time": 1785125529,
    "start_time": 1785125530,
    "finish_time": 1785125946,
    "progress": "100%",
    "resolution": "2K",
    "seconds": 5,
    "completion_tokens": 0
  }
}

统一接口状态值为：

状态	含义
`NOT_START` / `SUBMITTED`	已接受，尚未开始轮询。
`QUEUED`	上游排队中。
`IN_PROGRESS`	上游生成中。
`SUCCESS`	生成成功，`result_url` 为视频地址。
`FAILURE`	生成失败、取消或过期，查看 `fail_reason`。

OpenAI Video 兼容查询路径为：

该路径返回 object: "video" 的对象，成功后视频地址位于 metadata.url。两种查询路径都使用本系统任务 ID。

错误处理

网关会在本地优先校验模型、时长、分辨率、文本、角色和素材组合。常见错误包括：

情况	处理
未使用 `metadata.content` 时缺少非空 `prompt`，或使用该数组但缺少非空 `text` 项	返回 400，不提交上游。
H3-Fast 未传 `style1`	返回 400，不提交上游。
H3-Max-Turbo 纯文生	返回 400，不提交上游。
模型不支持的分辨率或时长	返回 400，不提交上游。
首尾帧与参考素材混用	返回 400，不提交上游。
上游敏感内容、余额不足、限流或服务异常	返回上游错误，任务状态为失败。

提交失败后可以根据 HTTP 状态码和 error.message 判断原因。不要把 API Key、完整 data URI 或上游响应中的敏感信息写入业务日志。

媒体限制

以下限制来自 MiniMax H3 私有接口说明；网关额外执行内容类型、角色、数量和参考音视频时长校验，格式、文件大小、尺寸和编码仍可能由上游最终校验。

类型	限制
请求体	总大小不超过 64 MB。Base64 会放大约 33%，大文件建议使用公网 URL 或 `mm_file://`。
图片	JPG/JPEG/PNG/WEBP/HEIC/HEIF；单文件不超过 30 MB；宽高 256~~5760 px；宽高比 0.4~~2.5。首帧最多 1 张、尾帧最多 1 张、参考图最多 9 张。
视频	MP4/MOV；H.264/H.265；音频 AAC/MP3；单文件不超过 50 MB；单段 2~~15 秒，总时长不超过 15 秒；23.976~~60 FPS；宽高 256~~5760 px；宽高比 0.4~~2.5。最多 3 段。
音频	WAV/MP3；单文件不超过 15 MB；单段 2~15 秒，总时长不超过 15 秒。最多 3 段。

生成视频下载地址可能有有效期。查询成功后应及时转存，不要把临时地址当作永久资源地址。

计费提示

MiniMax H3 的输出价格按秒计费，输入图片、参考视频也可能产生额外费用。管理员配置方式、每个 SKU 的价格和后台 ModelPrice 规则见管理员配置说明。

MiniMax-H3使用说明

MiniMax H3 视频 API 调用说明#

示例来源与转换规则#

创建任务#

基本请求体#

支持的模型#

刊例价#

视频输出价格#

输入素材价格#

多模态输入#

H3 480P 文生视频#

H3-Fast 文生视频#

H3-Max 提示词扩写#

首帧图生视频#

H3-Fast 首帧图生视频#

首尾帧图生视频#

H3-Max-Turbo 首尾帧视频#

多模态参考生视频#

H3-Fast 多模态参考生视频#

参考图片与视频组合#

素材时长与实际核算#

水印#

创建响应#

查询任务#

错误处理#

媒体限制#

计费提示#