📢 【模型上新】现支持MiniMax-H3、Hi3D模型，可前往 模型广场 查看调用~
MiniMax 视频生成接口文档（API Reference）
通用说明
Base URL
https://vg-api.aig-ai.com/v3/minimax鉴权（所有接口共用）
Authorization: Bearer <token>
Content-Type: application/json| 请求头 | 类型 | 必填 | 说明 |
|---|---|---|---|
| Authorization | string | 是 | Bearer <API_key> |
| Content-Type | enum | 是 | 固定为 application/json 。 |
模型说明
model 字段切换模型：| 模型 | 说明 | 分辨率 | 时长 |
|---|---|---|---|
| MiniMax-H3 | 支持文生视频、图生视频（首帧/尾帧）、多模态参考生视频 | 768P / 2K | 4~15 秒 |
| MiniMax-H3-Max | 极速生成版本，仅支持文生视频与图生视频（首帧/尾帧），不支持多模态参考；不支持 2K | 480P / 768P（默认 768P） | 5~15 秒（不支持 4 秒） |
多模态 content 输入规范（创建/IR 类接口共用）
content 为对象数组，每个元素通过 type 区分类型（text / image_url / video_url / audio_url），并可通过 role 标注用途。每次请求必须包含一个非空的 text 项（prompt 必填），缺失会返回参数错误。text 元素。text + 1 张 image_url（role=first_frame 或不填）。text + 1 张 image_url（role=last_frame）。text + 2 张 image_url（role 分别为 first_frame、last_frame）。text + 参考图片（role=reference_image）+ 参考视频（role=reference_video）+ 参考音频（role=reference_audio）。⚠️ 图生视频与多模态参考生视频互斥： content中出现reference_image/reference_video/reference_audio任一 role，就不能再出现first_frame/last_frame（反之亦然），二者不可混用。
输入媒体限制（请求体总大小 ≤ 64 MB，大文件请用公网 URL，勿用 Base64）
image_url：| 项 | 限制 |
|---|---|
| 格式 | JPG、JPEG、PNG、WEBP、HEIC、HEIF |
| 单文件大小 | ≤ 30 MB |
| 宽高范围 | [256, 5760] px |
| 长宽比（宽/高） | [0.4, 2.5] |
| 数量 | 首帧 ≤ 1、尾帧 ≤ 1、参考图 ≤ 9 |
video_url（仅多模态参考场景）：| 项 | 限制 |
|---|---|
| 容器/格式 | MP4（.mp4）、MOV（.mov） |
| 编码 | 视频 H.264/AVC、H.265/HEVC；音频 AAC、MP3 |
| 单文件大小 | ≤ 50 MB |
| 个数 | ≤ 3 |
| 单段时长 | [2, 15] s；总时长 ≤ 15 s |
| 宽高范围 | [256, 5760] px |
| 长宽比（宽/高） | [0.4, 2.5] |
| 帧率 | [23.976, 60] |
audio_url（仅多模态参考场景）：| 项 | 限制 |
|---|---|
| 格式 | WAV、MP3 |
| 单文件大小 | ≤ 15 MB |
| 个数 | ≤ 3 |
| 单段时长 | [2, 15] s；总时长 ≤ 15 s |
回调（callback）说明（创建类接口共用）
callback_url 后，MiniMax 服务器会：1.
challenge 字段的验证请求，需在 3 秒内原样返回 challenge 完成验证；2.
queued（排队中）、running（运行中）、succeeded（成功）、failed（失败）、cancelled（已取消）。1. 创建视频生成任务
基本信息
| 项 | 值 |
|---|---|
| 方法 | POST |
| 路径 | /v2/video_generation |
| 功能 | 视频生成 V2 接口，通过多模态 content 数组（文本/图片/视频/音频）生成视频，最高 2K 输出。 |
请求参数（body，JSON）
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | enum | 是 | 模型名称：MiniMax-H3 、MiniMax-H3-Max 。 |
| content | object[] | 是 | 多模态输入内容数组，详见上方「content 输入规范」。必须包含一个非空 text 项。 |
| resolution | enum | 是 | 视频分辨率。MiniMax-H3：768P、2K；MiniMax-H3-Max：480P、768P（默认 768P，不支持 2K）。 |
| duration | enum | 是 | 生成视频时长（秒），整数。MiniMax-H3：4 |
| ratio | enum | 否 | 生成视频宽高比，默认 adaptive（自动，由输入自适应；实际比例可在查询接口 ratio 字段获取）。 可选：adaptive、21:9、16:9、4:3、1:1、3:4、9:16。⚠️ 文生视频（content 仅含 text）：ratio 必填且不能为 adaptive；图生视频：宽高比由输入图片决定，ratio 恒为 adaptive（传入其他值被忽略）。 |
| callback_url | string | 否 | 任务状态变更回调通知地址，见上方「回调说明」。 |
| aigc_watermark | boolean | 否 | 是否在生成视频中添加 AIGC 标识水印，默认 false。 |
请求示例
响应
task_id。使用 task_id 调用「查询任务」接口获取任务状态与结果。{
"task": {
"id": "424010985738629",
"model": "MiniMax-H3",
"status": "succeeded",
"created_at": 1785125529,
"updated_at": 1785125946,
"content": {
"url": "https://your-cdn.example.com/h3-generated-2k-output.mp4"
},
"resolution": "2K",
"duration": 5,
"usage": {
"total_seconds": 5,
"input_seconds": 0,
"output_seconds": 5,
"input_image_count": 0
},
"ratio": "16:9",
"task_type": "generation",
"modality": "video"
}
}2. 查询任务
基本信息
| 项 | 值 |
|---|---|
| 方法 | GET |
| 路径 | /v2/query/video_generation/{task_id} |
| 功能 | 查询指定视频生成任务的状态与结果。 |
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| task_id | string | 是 | 要查询的任务 ID（创建任务返回的 task_id）。 |
请求示例
响应
task 对象，字段如下：| 字段 | 类型 | 说明 |
|---|---|---|
| task.id | string | 任务 ID。 |
| task.model | string | 使用的模型名称。 |
| task.status | string | 任务状态：queued / running / succeeded / failed / cancelled。 |
| task.created_at | integer | 任务创建时间戳（秒）。 |
| task.updated_at | integer | 任务更新时间戳（秒）。 |
| task.content.url | string | 生成视频的下载地址（status=succeeded 时返回）。 |
| task.content.prompt | string | 增强后的提示词（仅 H3-Context-IR 任务成功后返回）。 |
| task.resolution | string | 视频分辨率，如 2K、768P、480P。 |
| task.duration | integer | 视频时长（秒）。 |
| task.ratio | string | 视频宽高比，如 16:9；自适应场景可能为空字符串。 |
| task.task_type | string | 任务类型：generation / h3_context_ir / regeneration。 |
| task.modality | string | 输出模态：video / text。 |
| task.usage | object | 用量统计（见下表）。 |
usage 对象字段：| 字段 | 类型 | 说明 |
|---|---|---|
| total_seconds | integer | 总视频秒数。 |
| input_seconds | integer | 输入视频秒数。 |
| output_seconds | integer | 输出视频秒数。 |
| input_image_count | integer | 输入图片数量。 |
| input_audio_seconds | integer | 输入音频秒数（多模态参考场景）。 |
| total_tokens | integer | 总 token 数。 |
| prompt_tokens | integer | 输入 token 数。 |
| completion_tokens | integer | 输出 token 数。 |
响应示例（含完整 usage）
{
"task": {
"id": "424010985738629",
"model": "MiniMax-H3",
"status": "succeeded",
"created_at": 1785125529,
"updated_at": 1785125946,
"content": {
"url": "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/h3_promo_eval_ref2va/gallery/sr_v2p26_trio_seed42_20260724/inputs/89f8c0bbee5b_denoise_ids_0_final.mp4"
},
"resolution": "2K",
"duration": 5,
"usage": {
"total_seconds": 5,
"input_seconds": 0,
"output_seconds": 5,
"input_image_count": 1,
"input_audio_seconds": 6,
"total_tokens": 273890,
"prompt_tokens": 13500,
"completion_tokens": 260390
},
"ratio": "16:9",
"task_type": "generation",
"modality": "video"
}
}3. 创建 H3-Context-IR 任务
基本信息
| 项 | 值 |
|---|---|
| 方法 | POST |
| 路径 | /v2/h3_context_ir |
| 功能 | H3-Context-IR 对文本、图像、音频、视频等多模态上下文进行深度理解，分析素材之间及素材与目标生成结果之间的关系并进行复杂逻辑推理，将理解结果转换为结构化表达，丰富语义细节返回增强提示词。 |
content.prompt 获取增强提示词，task_type 为 h3_context_ir。请求参数（body，JSON）
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | enum | 是 | 模型名称，当前可用值：MiniMax-H3。 |
| content | object[] | 是 | 多模态上下文输入数组，规范同「content 输入规范」。必须包含一个非空 text 项。 |
| duration | enum | 是 | 目标视频时长（秒），整数，可用值 4~15。 |
| ratio | enum | 否 | 目标视频宽高比，默认 adaptive，可选：adaptive、21:9、16:9、4:3、1:1、3:4、9:16。⚠️ 文生视频：ratio 必填且不能为 adaptive；图生视频：宽高比由输入图片决定，恒为 adaptive。 |
| callback_url | string | 否 | 任务状态变更回调通知地址，见「回调说明」。 |
resolution、aigc_watermark 参数（只产出提示词文本，不生成视频）。请求示例
响应
task_id，使用 task_id 调用「查询任务」接口获取状态与结果；任务成功后从 content.prompt 获取增强提示词。{
"task_id": "424010985738629"
}{
"task": {
"id": "426586401755526",
"model": "MiniMax-H3",
"status": "succeeded",
"created_at": 1785702855,
"updated_at": 1785702884,
"content": {
"prompt": "integrated_multimodal_description: [Shot 1] Cinematic, wide shot ..."
},
"duration": 5,
"usage": {
"total_tokens": 9090,
"prompt_tokens": 5664,
"completion_tokens": 3426
},
"ratio": "16:9",
"task_type": "h3_context_ir",
"modality": "text"
}
}4. 创建视频再生成任务
基本信息
| 项 | 值 |
|---|---|
| 方法 | POST |
| 路径 | /v2/video_regeneration |
| 功能 | 对符合 MiniMax-H3 768P 输出规格的源视频再生成，输出 2K 视频。仅支持 H3 768P 生成视频的再生成，不支持任意视频的通用处理。 |
source_task_idcontent 中传 base_videotask_type 为 regeneration，可通过共用的「查询任务」「查询任务列表」「取消或删除任务」接口管理。请求参数（body，JSON）
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | enum | 是 | 模型名称，当前支持 MiniMax-H3。 |
| source_task_id | string | 是* | 已有 /v2/video_generation 成功任务的 task_id，以其产物为源再生成。限制：需开通白名单；源任务须属于当前账号、状态为 succeeded，且仍可通过 /v2/query/video_generation 查到（创建于 7 天内）。 |
| resolution | enum | 是 | 再生成目标分辨率，当前支持 2K。 |
| callback_url | string | 否 | 任务状态变更回调 URL，行为同创建视频生成任务的 callback_url。 |
| aigc_watermark | boolean | 否 | 是否为生成视频添加 AIGC 水印，默认 false。 |
| content | object[] | 是* | 按源视频再生成时，在 content 中传 base_video（与 source_task_id 二选一）。 |
source_task_id 与 content（base_video）二选一必填。请求示例（按任务 ID）
响应
task_id，使用 task_id 调用「查询任务」接口获取状态与结果。{
"task_id": "424010985738629"
}{
"task": {
"id": "424010985738631",
"model": "MiniMax-H3",
"status": "succeeded",
"created_at": 1785126000,
"updated_at": 1785126300,
"content": {
"url": "https://your-cdn.example.com/h3-regenerated-2k-output.mp4"
},
"resolution": "2K",
"duration": 5,
"usage": {
"total_seconds": 5,
"input_seconds": 0,
"output_seconds": 5,
"input_image_count": 0
},
"ratio": "",
"task_type": "regeneration",
"modality": "video"
}
}附录：任务类型与状态速查
task_type 取值
| 值 | 接口 | 输出 |
|---|---|---|
| generation | 创建视频生成任务 | 视频（modality=video） |
| h3_context_ir | 创建 H3-Context-IR 任务 | 增强提示词（modality=text，取 content.prompt） |
| regeneration | 创建视频再生成任务 | 视频（modality=video） |
status 取值
queued（排队中）、running（运行中）、succeeded（成功）、failed（失败）、cancelled（已取消）。