MiniMax-H3 视频生成 API 文档

概述

MiniMax-H3 是新一代视频生成模型，通过魔芋平台提供 API 服务。支持三种任务类型：

文生视频 / 图生视频 (Generation)：根据文本描述或输入图片生成视频

视频再生成 (Regeneration)：基于已有视频再生成，通常用于 768P → 2K 升级

Context-IR (智能扩写)：将简短提示词扩写为结构化的详细描述（产出文本，非视频）

所有任务通过统一的 /v1/video/generations 接口提交，使用 metadata.task_type 字段区分任务类型。

提交与查询的响应结构不同，这是最容易踩坑的地方：
提交（POST /v1/video/generations）返回扁平结构，任务 ID 在顶层 id（同时提供 task_id 别名）。
查询（GET /v1/video/generations/{task_id}）返回 {code, message, data:{...}} 包裹结构，业务字段全部在 data 里。
详见第 1 节与第 4 节的响应示例。

1. 提交任务与响应结构

基础文生视频

提交成功响应（HTTP 200，扁平结构）：

{
  "id": "435190535455101",
  "task_id": "435190535455101",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "",
  "progress": 0,
  "created_at": 1787801999
}

字段说明：

字段	类型	说明
`id`	string	任务 ID，用于后续查询。推荐读这个字段
`task_id`	string	与 `id` 值相同，兼容旧接口保留，后续可能废弃
`object`	string	固定为 `"video"`
`model`	string	提交时使用的模型名
`status`	string	建单瞬间为空字符串 `""`，不要据此判断任务状态，请以查询接口为准
`progress`	integer	建单瞬间为 `0`（注意：提交响应里是整数，查询响应里是字符串）
`created_at`	integer	建单时间（Unix 秒）

⚠️ 提交响应没有 code/message/data 包裹层，id 在顶层。正确取法：resp["id"]（或 resp["task_id"]），不是 resp["data"]["task_id"]。

图生视频 (Image-to-Video)

支持首帧、尾帧或参考图三种模式：

首帧图生视频：

{
  "model": "MiniMax-H3",
  "prompt": "画面中的女孩转过身来，微笑着挥手",
  "duration": 5,
  "resolution": "2K",
  "metadata": {
    "first_frame_image": "https://your-cdn.example.com/first-frame.jpg"
  }
}

尾帧图生视频：

{
  "model": "MiniMax-H3",
  "prompt": "镜头推进，最终定格在城市天际线",
  "duration": 8,
  "resolution": "2K",
  "metadata": {
    "last_frame_image": "https://your-cdn.example.com/last-frame.jpg"
  }
}

图生视频（首帧/尾帧）场景下 ratio 由输入图片决定，即使你传了具体比例，平台也会强制改写为 adaptive 后再发往上游。

参考图生视频（多模态）：

{
  "model": "MiniMax-H3",
  "prompt": "一位女性角色在海边散步，参考提供的人物形象和场景氛围",
  "duration": 6,
  "resolution": "2K",
  "ratio": "16:9",
  "metadata": {
    "reference_images": [
      "https://your-cdn.example.com/ref1.jpg",
      "https://your-cdn.example.com/ref2.jpg"
    ]
  }
}

输入图片约束：

格式：JPG、JPEG、PNG、WEBP、HEIC、HEIF

单文件大小：≤ 30 MB

尺寸范围：宽高均在 [256, 5760] px

长宽比：[0.4, 2.5]

数量限制：首帧 ≤ 1 张、尾帧 ≤ 1 张、参考图 ≤ 9 张

多模态参考生成 (Reference Video/Audio)

支持输入参考视频和参考音频：

{
  "model": "MiniMax-H3",
  "prompt": "角色说话：Hello, welcome to the future. 参考视频中的人物动作和音频1的音色",
  "duration": 5,
  "resolution": "2K",
  "ratio": "adaptive",
  "metadata": {
    "reference_videos": [
      "https://your-cdn.example.com/reference.mp4"
    ],
    "reference_audios": [
      "https://your-cdn.example.com/reference.mp3"
    ]
  }
}

输入视频约束：

格式：MP4 (.mp4)、MOV (.mov)

编码：视频 H.264/AVC、H.265/HEVC；音频 AAC、MP3

单文件大小：≤ 50 MB

数量：≤ 3 段

单段时长：[2, 15] 秒；总时长 ≤ 15 秒

尺寸范围：宽高均在 [256, 5760] px

长宽比：[0.4, 2.5]

帧率：[23.976, 60]

输入音频约束：

格式：WAV、MP3

单文件大小：≤ 15 MB

数量：≤ 3 段

单段时长：[2, 15] 秒；总时长 ≤ 15 秒

2. 视频再生成 (Regeneration)

对符合 768P 输出规格的源视频再生成为 2K 视频。支持两种方式，二选一。

方式一：按任务 ID（推荐）

直接引用平台上已完成的生成任务，无需提供视频地址，也不受下游限时下载地址过期影响。

source_task_id 只能引用自己账号下已成功的任务，平台会校验归属与状态；引用不存在或未成功的任务会返回 build_request_failed（见第 7 节）。

方式二：按源视频地址

源视频不是本平台产出时使用。

提交响应结构与第 1 节完全一致（扁平，id 在顶层）。

说明：

metadata.task_type 必须设置为 "regeneration"

source_task_id 与 base_video_url 二选一，同时提供时以 source_task_id 为先

base_video_url 支持公网 URL、mm_file://{file_id}、Base64 data URI

prompt 必填（平台入口层强制校验，缺失直接 400）

不需要传 duration，输出时长由源视频决定

可额外传 reference_audios 等参考素材在提升分辨率的同时调整画面

3. Context-IR (智能扩写)

将简短的用户提示词扩写为结构化的详细描述（包含镜头、音效、配乐等），可用于后续精准生成。

支持多模态输入：

{
  "model": "MiniMax-H3",
  "prompt": "角色说话：Follow the wind, live free. 参考音频1的音色和视频1的人物动作",
  "duration": 5,
  "ratio": "adaptive",
  "metadata": {
    "task_type": "h3_context_ir",
    "reference_videos": [
      "https://your-cdn.example.com/reference.mp4"
    ],
    "reference_audios": [
      "https://your-cdn.example.com/reference.mp3"
    ]
  }
}

提交响应结构与第 1 节完全一致（扁平，id 在顶层）。

说明：

metadata.task_type 必须设置为 "h3_context_ir"

prompt 必填

任务产出的是文本内容（扩写后的结构化提示词），而非视频

Context-IR 不接受 resolution（只输出文本，无分辨率概念），传了也会被忽略

支持传入 duration 和 ratio 以影响扩写内容的时长描述和构图描述

扩写结果的取法与视频任务不同，见第 4 节「成功响应（Context-IR）」

4. 查询任务状态

查询响应统一为 {code, message, data:{...}} 包裹结构，业务字段全部在 data 内。

处理中响应：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "435190535455101",
    "action": "generate",
    "status": "IN_PROGRESS",
    "fail_reason": "",
    "submit_time": 1787801998,
    "start_time": 1787802005,
    "finish_time": 0,
    "progress": "50%",
    "data": {
      "task": {
        "id": "435190535455101",
        "model": "MiniMax-H3",
        "status": "running",
        "ratio": "16:9",
        "duration": 5,
        "resolution": "768P",
        "task_type": "generation",
        "usage": {},
        "created_at": 1787801999,
        "updated_at": 1787801999
      }
    }
  }
}

成功响应（文生视频 / 图生视频 / 视频再生成）：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "435190535455101",
    "action": "generate",
    "status": "SUCCESS",
    "fail_reason": "",
    "result_url": "https://algeng-video-infer.oss-cn-shanghai.aliyuncs.com/infer/output_aigc.mp4?Expires=...&Signature=...",
    "submit_time": 1787801998,
    "start_time": 1787802005,
    "finish_time": 1787802115,
    "progress": "100%",
    "data": {
      "task": {
        "id": "435190535455101",
        "model": "MiniMax-H3",
        "status": "succeeded",
        "content": { "url": "https://.../output_aigc.mp4?Expires=..." },
        "usage": {
          "total_tokens": 162745,
          "completion_tokens": 162745,
          "prompt_tokens": 0,
          "total_seconds": 5,
          "output_seconds": 5,
          "input_seconds": 0,
          "input_image_count": 0
        },
        "ratio": "16:9",
        "duration": 5,
        "resolution": "768P",
        "task_type": "generation",
        "created_at": 1787801999,
        "updated_at": 1787802113
      }
    }
  }
}

视频地址在 data.result_url（同一地址也出现在透传层 data.data.task.content.url）。该地址为限时地址，请在任务成功后尽快下载或转存；也可直接用 GET /v1/videos/{task_id}/content 由平台代理拉流，无需处理下游限时地址过期。

成功响应（Context-IR）：

Context-IR 产出的是文本，外层没有 result_url 字段，扩写结果在透传层 data.data.task.content.prompt：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "435194938720659",
    "action": "generate",
    "status": "SUCCESS",
    "fail_reason": "",
    "submit_time": 1787802032,
    "start_time": 1787802036,
    "finish_time": 1787802073,
    "progress": "100%",
    "data": {
      "task": {
        "id": "435194938720659",
        "model": "MiniMax-H3",
        "status": "succeeded",
        "modality": "text",
        "task_type": "h3_context_ir",
        "content": {
          "prompt": "integrated_multimodal_description: [Shot 1] 一个穿着白色T恤的十岁男孩站在金色沙滩上...\noverall_soundscape: 海浪拍打沙滩的声音，篮球弹跳的清脆响声...\nnon_diegetic_music: 轻快的钢琴旋律伴随弦乐，节奏明快..."
        },
        "usage": { "total_tokens": 6114, "prompt_tokens": 5648, "completion_tokens": 466 }
      }
    }
  }
}

Context-IR 任务的 data.action 仍是 "generate"，不是 "h3_context_ir"。任务类型以透传层 data.data.task.task_type 与 modality: "text" 为准。

失败响应：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "435190535455101",
    "action": "generate",
    "status": "FAILURE",
    "fail_reason": "content[1].image_url: media not found (HTTP 404)",
    "result_url": "",
    "submit_time": 1787746910,
    "start_time": 1787746919,
    "finish_time": 1787746925,
    "progress": "100%"
  }
}

判断任务成败以 data.status 为准。code 表示平台层调用是否成功，任务本身失败时 code 仍为 "success"，具体失败原因在 data.fail_reason。

查询响应 data 字段

字段	类型	说明
`task_id`	string	任务 ID
`action`	string	任务动作标识，H3 全部任务类型均为 `"generate"`
`status`	string	任务状态，大写，取值见下表
`fail_reason`	string	失败原因，成功时为空字符串
`result_url`	string	结果地址（限时）。视频任务为视频 URL；Context-IR 任务无此字段
`submit_time`	integer	任务提交时间（Unix 秒）
`start_time`	integer	任务开始处理时间（Unix 秒）
`finish_time`	integer	任务完成时间（Unix 秒），未完成时为 0
`progress`	string	任务进度，字符串且带百分号，如 `"0%"`、`"50%"`、`"100%"`
`data`	object	上游原始对象透传层，内含 `task`（见下）

透传层 data.data.task 字段

字段	类型	说明
`id`	string	上游任务 ID
`model`	string	模型名
`status`	string	上游状态，小写，取值见下表
`content.url`	string	视频任务产物地址
`content.prompt`	string	Context-IR 任务的扩写文本
`usage`	object	用量与计费信息
`resolution` / `duration` / `ratio`	-	上游实际采用的参数（可能与请求值不同，见第 5 节）
`task_type`	string	`generation` / `regeneration` / `h3_context_ir`
`modality`	string	Context-IR 任务为 `"text"`

status 取值与两层状态对照

外层 `data.status`（大写）	透传层 `data.data.task.status`（小写）	说明
`NOT_START`	—	未开始
`SUBMITTED`	—	已提交，排队中
`QUEUED`	`queued`	排队中
`IN_PROGRESS`	`running`	生成中
`SUCCESS`	`succeeded`	已完成
`FAILURE`	`failed` / `cancelled`	失败

两套状态词并存，调用方判断成败建议以外层大写 data.status 为准。实际观测中进度通常跳变 0% → 50% → 100%，任务提交后很快进入 IN_PROGRESS，NOT_START/SUBMITTED 窗口很短。

5. 请求参数说明

公共参数

参数	类型	必填	说明
`model`	string	是	固定值：`"MiniMax-H3"`
`prompt`	string	是	文本描述。所有任务类型均强制非空，包括 regeneration 与 Context-IR；缺失或为空返回 400 `invalid_request`
`duration`	integer	否	生成视频时长（秒），范围 `[4, 15]` 的整数，默认 5。传字符串（如 `"5"`）会返回 400；超范围返回 500 `build_request_failed`。regeneration 任务不需要此参数
`resolution`	string	否	清晰度，可选值 `"768P"`、`"2K"`。未传或传无法识别的值时默认按 `"2K"` 处理
`ratio`	string	否	宽高比，可选值 `"adaptive"`、`"21:9"`、`"16:9"`、`"4:3"`、`"1:1"`、`"3:4"`、`"9:16"`。平台会按场景改写，见下方说明
`aigc_watermark`	boolean	否	是否在生成视频中添加 AIGC 标识水印，默认 `false`。也可放在 `metadata` 内

ratio 的实际处理规则（平台会按场景改写后再发往上游）：

场景	处理
纯文生视频	未传或传 `adaptive` 时改写为 `16:9`；传具体比例则原样使用
图生视频（首帧/尾帧）	强制改写为 `adaptive`，请求中传入的值被忽略
多模态参考（参考图/视频/音频）	传了就用传入值，未传则用 `adaptive`

非法比例值（如 "5:5"）不会在平台侧拦截，会被上游拒绝并返回 400 fail_to_fetch_task。

metadata 参数

参数	类型	说明
`task_type`	string	任务类型： - 不传或 `"generation"`：文生视频/图生视频 - `"regeneration"`：视频再生成 - `"h3_context_ir"`：智能扩写传其他值按 `generation` 处理，不报错
`first_frame_image`	string	首帧图片 URL（仅 generation）
`last_frame_image`	string	尾帧图片 URL（仅 generation）
`reference_images`	array	参考图片 URL 列表，最多 9 张（仅 generation）
`reference_videos`	array	参考视频 URL 列表，最多 3 段（generation / context_ir）
`reference_audios`	array	参考音频 URL 列表，最多 3 段（generation / context_ir）
`source_task_id`	string	源任务 ID（仅 regeneration，与 `base_video_url` 二选一）。只能引用自己账号下已成功的任务。别名：`base_task_id`
`base_video_url`	string	源视频 URL（仅 regeneration，与 `source_task_id` 二选一）。支持公网 URL、`mm_file://{file_id}`、Base64 data URI
`content`	array	高级用法：完全自定义上游多模态 content 数组。传了此字段时上面的 `first_frame_image` 等便捷字段不再生效
`callback_url`	string	任务完成后的回调地址（可选）。配置后平台会先发送含 `challenge` 字段的验证请求（需 3 秒内原样返回 `challenge`），验证成功后每当任务状态变更即向该地址 POST 推送，推送体结构与查询接口响应一致

首帧/尾帧模式与参考图/视频/音频模式不可混用，混用返回 500 build_request_failed。
顶层 images 数组可作为便捷写法：images[0] 当首帧、images[1] 当尾帧；多张参考图请显式走 metadata.reference_images。
请求体总大小 ≤ 64 MB，大文件请使用公网 URL，避免 Base64。

6. 三种响应信封

平台不同环节返回的信封结构不同，客户端需要都能兼容：

信封	出现场景	结构
扁平体	提交任务成功	`{id, task_id, object, model, status, progress, created_at}`
业务包裹	查询任务、业务层错误	`{code, message, data}`
网关错误	鉴权、路由、模型不可用等	`{error: {code, message, type}}`
代理拉流错误	`GET /v1/videos/{id}/content` 出错	`{error: {message, type}}`（OpenAI 风格）

网关错误示例（HTTP 状态码为真实错误码）：

{
  "error": {
    "code": "",
    "message": "无效的令牌 (request id: 20260827102641657613236tt6sxSxB)",
    "type": "moyu_api_error"
  }
}

业务层错误示例（如任务不存在）：

{
  "code": "task_not_exist",
  "message": "task_not_exist",
  "data": null
}

7. 错误处理

错误在不同校验层返回不同的 HTTP 状态码与 code，请勿只按 HTTP 状态码分支：

场景	HTTP	code / 信封	message 示例
缺少 Authorization	401	网关，`code` 为空	`未提供令牌`
令牌无效	401	网关，`code` 为空	`无效的令牌`
缺少或空 `model`	400	网关，`code` 为空	`未指定模型名称...`
模型无可用渠道	503	网关 `model_not_found`	`分组 default 下模型 ... 无可用渠道（distributor）`
请求体非合法 JSON	400	网关，`code` 为空	`Invalid request, 无效的请求, invalid character ...`
缺少或空 `prompt`	400	业务 `invalid_request`	`prompt is required`
`duration` 类型错误	400	业务 `invalid_request`	`json: cannot unmarshal string into Go struct field .Alias.duration of type int`
余额低于阈值	403	业务 `quota_below_block_threshold`	`余额不足，低于禁止阈值...`
`duration` 超出 [4,15]	500	业务 `build_request_failed`	`convert request payload failed: duration must be within [4,15] for MiniMax-H3`
首尾帧与参考素材混用	500	业务 `build_request_failed`	`convert request payload failed: MiniMax-H3: first_frame/last_frame cannot mix with reference_image/video/audio`
regeneration 源任务不存在/未成功	500	业务 `build_request_failed`	`convert request payload failed: MiniMax-H3 regeneration: source task ... not found`
`ratio` 非法、content 文本为空等上游拒绝	400	业务 `fail_to_fetch_task`	内嵌上游原始错误 JSON，见下
查询的任务不存在	400	业务 `task_not_exist`	`task_not_exist`
代理拉流任务不存在	404	代理，OpenAI 风格	`Task not found`
素材不可达等运行期失败	200	查询得 `data.status: FAILURE`	`content[...].image_url: media not found (HTTP 404)`

fail_to_fetch_task 的特殊之处：其 message 字段里内嵌了上游返回的原始错误 JSON（含上游内部错误码与 request_id），需要对 message 做二次 JSON 解析才能拿到具体原因：

{
  "code": "fail_to_fetch_task",
  "message": "{\"type\":\"error\",\"error\":{\"type\":\"bad_request_error\",\"message\":\"invalid params, ratio=\\\"5:5\\\" invalid, allowed: adaptive, 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 (2013)\",\"http_code\":\"400\"},\"request_id\":\"...\"}",
  "data": null
}

8. 计费与用量

计费按 token 计，实际用量在查询响应的透传层 data.data.task.usage 返回。参考量级：

任务	参考用量
768P / 5 秒	约 162745 tokens
2K / 5 秒	约 260390 tokens
Context-IR	约 6114 tokens

视频任务的 usage 含 total_seconds / output_seconds / input_seconds / input_image_count；Context-IR 的 usage 只有 total_tokens / prompt_tokens / completion_tokens。

9. 最佳实践

客户端解析建议

提示词建议

文生视频：详细描述场景、动作、镜头运动、光影效果，建议 50-200 字

图生视频：重点描述从图片到视频的动作变化，而非重复描述图片内容

视频再生成：保持原 prompt 或微调细节描述，主要用于分辨率升级

Context-IR：简短输入即可（10-50 字），系统会自动扩写为结构化描述

素材输入建议

优先使用公网 URL（支持 HTTPS），避免 Base64 大文件导致请求体超限（64 MB）

素材 URL 必须可被上游公网访问；不可达的 URL 在提交阶段不会报错，会在异步执行阶段变成 FAILURE

参考图/视频/音频数量越多，生成时间越长，建议按需精选

首帧/尾帧模式与参考图模式不可混用

异步轮询建议

提交任务后立即返回任务 ID，客户端需轮询查询接口获取结果

建议轮询间隔：前 30 秒每 3 秒一次，之后每 10 秒一次

超时时间建议：5 分钟（复杂任务可能需要更长时间）

结果地址 result_url 为限时地址，成功后请尽快转存，或使用 GET /v1/videos/{task_id}/content 由平台代理拉流（返回 Content-Type: video/mp4 字节流）

10. 完整示例：从提交到获取结果

11. 技术支持

如有问题，请联系技术支持团队或查阅完整 API 文档。

概述#

1. 提交任务与响应结构#

基础文生视频#

图生视频 (Image-to-Video)#

多模态参考生成 (Reference Video/Audio)#

2. 视频再生成 (Regeneration)#

方式一：按任务 ID（推荐）#

方式二：按源视频地址#

3. Context-IR (智能扩写)#

4. 查询任务状态#

查询响应 data 字段#

透传层 data.data.task 字段#

status 取值与两层状态对照#

5. 请求参数说明#

公共参数#

metadata 参数#

6. 三种响应信封#

7. 错误处理#

8. 计费与用量#

9. 最佳实践#

客户端解析建议#

提示词建议#

素材输入建议#

异步轮询建议#

10. 完整示例：从提交到获取结果#

11. 技术支持#

概述