MiniMax 生视频 - AI 接口对接文档中心

1. 概述

本接口用于异步创建 MiniMax-H3 视频任务，并查询任务状态和生成结果，支持文生视频、图生视频（首帧、尾帧、首尾帧）、多模态参考生视频、2K 视频再生成及 H3-Context-IR 提示词增强。

baseUrl：https://token.soar.qjclouds.cn/laserEr/00000000/v1
completionsPath：/video/generations/{apiType}
标准地址：POST {baseUrl}{completionsPath}
创建任务：POST {baseUrl}/video/generations/{apiType}
查询任务：POST {baseUrl}/video/resource-actions/QueryVideo

2. 接入前置条件

项	说明
`api_key`	访问密钥（控制台生成），用于 Bearer 鉴权。
`model`	已在平台开通的 MiniMax-H3 模型编码。

2.1 模型与能力

能力	apiType	模型
文生视频	`TextToVideo`	`MiniMax/MiniMax-H3`
图生视频	`ImageToVideo`	`MiniMax/MiniMax-H3`
多模态参考生视频	`ReferenceToVideo`	`MiniMax/MiniMax-H3`
视频再生成	`VideoRegeneration`	`MiniMax/MiniMax-H3-Regeneration`
提示词增强	`H3ContextIR`	`MiniMax/MiniMax-H3-Context-IR`
查询任务	`QueryVideo`	创建任务时使用的模型编码

3. 鉴权

HTTP

Authorization: Bearer <api_key>
Content-Type: application/json
Accept: application/json

4. 创建视频任务

请求地址：POST {baseUrl}/video/generations/{apiType}
模型：MiniMax/MiniMax-H3
接口返回 task_id，需要通过查询接口轮询结果。

4.1 请求参数

字段	类型	必填	说明
`model`	string	是	固定为 `MiniMax/MiniMax-H3`。
`content`	array<object>	是	多模态输入数组。每个元素由 `type` 区分数据类型，由 `role` 标注素材用途；必须包含一个非空的文本元素。
`resolution`	enum	是	视频分辨率：`768P` 或 `2K`。
`duration`	integer	是	视频时长，取值为 4～15 秒的整数。
`ratio`	enum	条件必填	`adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`；默认 `adaptive`，文生视频必须传具体比例。
`callback_url`	string	否	任务状态变更的回调通知地址。
`aigc_watermark`	boolean	否	是否添加 AIGC 标识水印，默认 `false`。

4.2 content 元素字段

必填规则：content 中必须包含一个且仅需一个非空的 text 提示词元素；缺失或内容为空会返回参数错误。

元素 type	元素字段	类型	必填	说明
`text`	`type`	string	是	固定为 `text`。
`text`	`text`	string	是	视频内容、动作、镜头、对白等提示词，不能为空。
`image_url`	`type`	string	是	固定为 `image_url`。
`image_url`	`image_url.url`	string	是	可公开访问的图片 URL，或 `mm_file://{file_id}`。
`image_url`	`role`	enum	否	`first_frame`（首帧，省略 role 时默认）、`last_frame`（尾帧）或 `reference_image`（参考图）。
`video_url`	`type`	string	是	固定为 `video_url`。
`video_url`	`video_url.url`	string	是	可公开访问的视频 URL，或 `mm_file://{file_id}`。
`video_url`	`role`	enum	是	创建任务时为 `reference_video`；视频再生成的源视频为 `base_video`。
`audio_url`	`type`	string	是	固定为 `audio_url`。
`audio_url`	`audio_url.url`	string	是	可公开访问的音频 URL，或 `mm_file://{file_id}`。
`audio_url`	`role`	string	是	固定为 `reference_audio`，用于音色或配音参考。

4.3 content 支持的输入组合

场景	apiType	content 组合
文生视频	`TextToVideo`	一个非空 `text` 元素。
首帧图生视频	`ImageToVideo`	`text` + 1 张 `image_url`，role 为 `first_frame` 或省略。
尾帧图生视频	`ImageToVideo`	`text` + 1 张 `image_url`，role 为 `last_frame`。
首尾帧图生视频	`ImageToVideo`	`text` + 2 张 `image_url`，role 分别为 `first_frame`、`last_frame`。
多模态参考生视频	`ReferenceToVideo`	`text` + `reference_image` / `reference_video` / `reference_audio` 中的一种或多种素材。

互斥规则：first_frame / last_frame 与 reference_image / reference_video / reference_audio 不能出现在同一个创建请求中。

4.4 输入媒体限制

请求体总大小不能超过 64 MB；较大的素材应使用公网 URL，避免使用 Base64。

媒体	格式	大小	数量与其他限制
图片	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	最多 3 个；单段 2～15 秒，总时长 ≤ 15 秒；宽高 256～5760 px，宽高比 0.4～2.5，帧率 23.976～60。
音频	WAV、MP3	单文件 ≤ 15 MB	最多 3 个；单段 2～15 秒，总时长 ≤ 15 秒。

4.5 ratio 规则

场景	规则
文生视频	`ratio` 必填，且不能为 `adaptive`。
图生视频	宽高比由输入图片决定，恒为 `adaptive`；传入其他值会被忽略。
多模态参考生视频	可选，默认 `adaptive`，也可显式指定具体比例。

4.6 文生视频请求示例

JSON

{
  "model": "MiniMax/MiniMax-H3",
  "content": [{
    "type": "text",
    "text": "史诗级太空歌剧院线预告，最后一支舰队正在集结并跃迁离去。"
  }],
  "resolution": "2K",
  "duration": 5,
  "ratio": "16:9"
}

4.7 首尾帧图生视频请求示例

JSON

{
  "model": "MiniMax/MiniMax-H3",
  "content": [
    {"type": "text", "text": "镜头缓慢推进，人物转身看向窗外。"},
    {"type": "image_url", "image_url": {"url": "https://your-cdn.example.com/first.png"}, "role": "first_frame"},
    {"type": "image_url", "image_url": {"url": "https://your-cdn.example.com/last.png"}, "role": "last_frame"}
  ],
  "resolution": "2K",
  "duration": 5,
  "ratio": "adaptive"
}

4.8 多模态参考请求示例

JSON

{
  "model": "MiniMax/MiniMax-H3",
  "content": [
    {"type": "text", "text": "保持参考视频的运镜和参考音频的音色。"},
    {"type": "video_url", "video_url": {"url": "https://your-cdn.example.com/reference.mp4"}, "role": "reference_video"},
    {"type": "audio_url", "audio_url": {"url": "https://your-cdn.example.com/reference.mp3"}, "role": "reference_audio"}
  ],
  "resolution": "2K",
  "duration": 5,
  "ratio": "adaptive"
}

4.9 创建响应

JSON

{
  "task_id": "424010985738629"
}

5. 视频再生成

apiType：VideoRegeneration。仅支持将符合 MiniMax-H3 768P 输出规格的视频再生成至 2K，不支持任意视频的通用处理。

5.1 请求参数

字段	类型	必填	说明
`model`	string	是	固定为 `MiniMax/MiniMax-H3-Regeneration`。
`source_task_id`	string	二选一	原视频生成任务 ID；任务须属于当前账号、成功完成且创建时间不超过 7 天。
`content`	array<object>	二选一	按源视频再生成时使用；必须包含非空 `text` 和有且仅有一个 role 为 `base_video` 的 `video_url`。
`resolution`	string	是	固定为 `2K`。
`callback_url`	string	否	任务状态变更回调 URL。
`aigc_watermark`	boolean	否	是否添加 AIGC 水印，默认 `false`。

互斥规则：source_task_id 与 content 中的 base_video 二选一，不能同时传入。按源视频再生成时不传 duration 和 ratio，时长及比例沿用源视频。

5.2 按任务 ID 再生成

JSON

{
  "model": "MiniMax/MiniMax-H3-Regeneration",
  "source_task_id": "424010985738629",
  "resolution": "2K"
}

5.3 按源视频再生成

JSON

{
  "model": "MiniMax/MiniMax-H3-Regeneration",
  "content": [
    {"type": "text", "text": "增强画面细节并保持原有镜头运动。"},
    {"type": "video_url", "video_url": {"url": "https://your-cdn.example.com/h3-768p.mp4"}, "role": "base_video"}
  ],
  "resolution": "2K"
}

6. 查询视频任务

apiType：QueryVideo
请求地址：POST {baseUrl}/video/resource-actions/QueryVideo
任务结果可在创建后的 7 天内查询。

6.1 请求参数

字段	类型	必填	说明
`model`	string	是	创建任务时使用的模型编码。
`taskId`	string	是	创建任务返回的 `task_id`。

JSON

{
  "model": "MiniMax/MiniMax-H3",
  "taskId": "424010985738629"
}

6.2 响应字段

字段	类型	说明
`task.id`	string	任务 ID。
`task.model`	string	任务实际使用的模型。
`task.status`	string	`queued`、`running`、`succeeded`、`failed` 或 `cancelled`。
`task.created_at`	integer	任务创建时间，Unix 时间戳（秒）。
`task.updated_at`	integer	最后更新时间，Unix 时间戳（秒）。
`task.content.url`	string	视频任务成功后的下载地址。
`task.content.prompt`	string	H3-Context-IR 返回的增强提示词。
`task.resolution`	string	生成视频的分辨率。
`task.duration`	integer	生成视频的时长，单位秒。
`task.ratio`	string	生成视频的宽高比。
`task.task_type`	string	`generation`、`regeneration` 或 `h3_context_ir`。
`task.modality`	string	输出模态：`video` 或 `text`。
`task.usage`	object	输入、输出时长，图片数及 Token 用量统计。

6.3 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	输入 Prompt Token 数。
`completion_tokens`	integer	生成 Token 数。

6.4 视频任务成功响应示例

JSON

{
  "task": {
    "id": "424010985738629",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1785125529,
    "updated_at": 1785125946,
    "content": {
      "url": "https://your-cdn.example.com/h3-output.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"
  }
}

7. H3-Context-IR 提示词增强

apiType：H3ContextIR。该能力深度理解文本、图片、视频和音频上下文，只生成结构化视频提示词，不生成视频。

7.1 请求参数

字段	类型	必填	说明
`model`	string	是	固定为 `MiniMax/MiniMax-H3-Context-IR`。
`content`	array<object>	是	字段结构、role、输入组合、媒体限制及互斥规则与“4.2 content 元素字段”完全一致。
`duration`	integer	是	目标视频时长，取值为 4～15 秒的整数。
`ratio`	enum	条件必填	目标视频宽高比，规则同创建视频任务。
`callback_url`	string	否	任务状态变更回调通知地址。

7.2 请求示例

JSON

{
  "model": "MiniMax/MiniMax-H3-Context-IR",
  "content": [
    {"type": "text", "text": "根据参考素材生成完整的分镜提示词。"},
    {"type": "image_url", "image_url": {"url": "https://your-cdn.example.com/reference.png"}, "role": "reference_image"}
  ],
  "duration": 5,
  "ratio": "adaptive"
}

7.3 H3-Context-IR 成功响应示例

创建接口先返回 task_id。查询任务成功后，从 task.content.prompt 读取增强提示词；此类任务的 task_type 为 h3_context_ir，modality 为 text。

JSON

{
  "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"
  }
}

8. 错误响应

HTTP 状态码	错误类型	错误码	说明
400	`bad_request_error`	2013	参数无效，常见于 content 缺少非空 text 或再生成缺少 base_video。
401	`authorized_error`	1004	认证失败。
402	`insufficient_balance_error`	1008	余额不足。
422	`unprocessable_entity_error`	1026	视频描述包含敏感内容。
429	`rate_limit_error`	1002	速率限制，请稍后重试。
500	`server_error`	1000	服务内部错误。