MiniMax-h3 视频生成 API 对接文档

本文档仅介绍 minimax-h3 模型的视频生成与任务查询。调用方只需要使用平台签发的 API Key 和公开任务 ID，无需了解或配置底层服务信息。

1. 接入信息

1.1 Base URL

https://token.kelly.cloud

请将 {BASE_URL} 替换为实际部署地址，例如 https://api.example.com。

1.2 鉴权

所有接口均使用 Bearer Token 鉴权：

其中 API_KEY 为平台签发的访问令牌。请勿在浏览器前端、日志或公开代码仓库中暴露 API Key。

1.3 Content-Type

创建任务时必须指定：

1.4 接口列表

用途	方法	路径
创建视频生成任务	`POST`	`/v1/video/generations`
查询视频生成任务	`GET`	`/v1/video/generations/{task_id}`

请求统一传入 "ModelName": "minimax-h3"，无需传入 ModelVersion。响应中的 model 同样为 minimax-h3。

2. 创建视频生成任务

创建成功表示任务已进入异步处理队列，不表示视频已经生成完成。调用方应保存响应中的 task_id，随后通过任务查询接口获取进度和结果。

2.1 请求参数

顶层字段

字段	类型	必填	说明
`ModelName`	string	是	固定填写 `minimax-h3`。
`Prompt`	string	是	视频描述提示词，最多 7000 个 Unicode 字符，不能为空。
`FileInfos`	array	否	输入图片、视频或音频素材，规则见下文。
`OutputConfig`	object	是	输出配置。当前计费要求必须提供 `Duration` 和 `Resolution`。
`ExtInfo`	string	否	扩展配置。该字段本身必须是 JSON 字符串，不是 JSON 对象。

调用方不需要传入账号、凭证、子应用或签名相关字段；即使传入也不会用于本次请求。

`OutputConfig`

字段	类型	必填	说明
`Duration`	integer	是	输出时长，单位为秒，必须是 4～15 范围内的整数。
`Resolution`	string	是	支持 `768P`、`1080P`、`2K`、`4K`，区分大小写。
`AspectRatio`	string	否	`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` 或 `adaptive`。`adaptive` 仅适用于存在参考素材的请求。
`StorageMode`	string	否	`Temporary` 或 `Permanent`。
`MediaName`	string	否	生成视频的名称。
`AudioGeneration`	string	否	`Enabled` 或 `Disabled`。
`LogoAdd`	string	否	`Enabled` 或 `Disabled`。

所有枚举值均区分大小写。

`FileInfos` 单项字段

字段	类型	必填	说明
`Type`	string	是	素材来源类型：`File`、`Url` 或 `Base64`。
`Category`	string	是	素材类别：`Image`、`Video` 或 `Audio`。
`FileId`	string	条件必填	`Type=File` 时必填。
`Url`	string	条件必填	`Type=Url` 时必填，必须是服务端可访问的素材地址。
`Base64`	string	条件必填	`Type=Base64` 时必填。
`Usage`	string	否	`FirstFrame`、`LastFrame` 或 `Reference`。图片省略时按 `FirstFrame` 处理；建议始终显式填写。

FileId、Url、Base64 必须且只能填写一个，并且必须与 Type 对应。

素材数量和组合限制：

总素材数最多 12 个。

图片最多 9 张，视频最多 3 个，音频最多 3 个。

FirstFrame 和 LastFrame 各最多一个，且只能用于图片。

视频和音频的 Usage 必须为 Reference。

音频不能作为唯一素材，至少还需要一张图片或一个视频。

首尾帧模式不能与 Reference 参考素材模式混用。

远程素材的格式、编码、文件大小、像素和实际时长可能在异步处理阶段继续校验。

2.2 纯文本生成示例

2.3 首帧生成示例

{
  "ModelName": "minimax-h3",
  "Prompt": "人物抬头望向天空，微风吹动头发，镜头缓慢推进",
  "FileInfos": [
    {
      "Type": "Url",
      "Category": "Image",
      "Url": "https://example.com/first-frame.jpg",
      "Usage": "FirstFrame"
    }
  ],
  "OutputConfig": {
    "Duration": 8,
    "Resolution": "1080P",
    "AspectRatio": "16:9"
  }
}

2.4 首尾帧生成示例

{
  "ModelName": "minimax-h3",
  "Prompt": "从白天自然过渡到夜晚，保持建筑主体一致",
  "FileInfos": [
    {
      "Type": "Url",
      "Category": "Image",
      "Url": "https://example.com/first-frame.jpg",
      "Usage": "FirstFrame"
    },
    {
      "Type": "Url",
      "Category": "Image",
      "Url": "https://example.com/last-frame.jpg",
      "Usage": "LastFrame"
    }
  ],
  "OutputConfig": {
    "Duration": 10,
    "Resolution": "1080P",
    "AspectRatio": "16:9"
  }
}

2.5 多模态参考生成示例

{
  "ModelName": "minimax-h3",
  "Prompt": "延续参考素材中的人物和场景风格，生成自然连贯的后续镜头",
  "FileInfos": [
    {
      "Type": "Url",
      "Category": "Image",
      "Url": "https://example.com/reference-image.jpg",
      "Usage": "Reference"
    },
    {
      "Type": "Url",
      "Category": "Video",
      "Url": "https://example.com/reference-video.mp4",
      "Usage": "Reference"
    }
  ],
  "OutputConfig": {
    "Duration": 10,
    "Resolution": "1080P",
    "AspectRatio": "adaptive"
  }
}

2.6 创建成功响应

HTTP 状态码：200 OK

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "minimax-h3",
  "status": "queued",
  "progress": 0,
  "created_at": 1788912000
}

字段	类型	说明
`id`	string	平台公开任务 ID。
`task_id`	string	与 `id` 相同，用于兼容现有客户端；查询时使用此字段。
`object`	string	固定为 `video`。
`model`	string	本次请求的模型名称。
`status`	string	创建成功时为 `queued`。
`progress`	integer	初始进度为 `0`。
`created_at`	integer	Unix 秒级时间戳。

task_id 是平台生成的公开标识

3. 查询视频生成任务

路径参数：

参数	类型	必填	说明
`task_id`	string	是	创建任务响应返回的公开任务 ID。

请求示例：

任务只能由创建该任务的账号查询。建议每 3～5 秒查询一次，直到任务进入终态，避免高频轮询。

3.1 统一响应外层

{
  "code": "success",
  "message": "",
  "data": {}
}

字段	类型	说明
`code`	string	请求成功时为 `success`。
`message`	string	补充信息，成功时通常为空字符串。
`data`	object	任务详情。

3.2 任务详情字段

字段	类型	说明
`task_id`	string	平台公开任务 ID。
`model`	string	本次任务使用的模型名称。
`created_at`	integer	任务记录创建时间，Unix 秒级时间戳。
`updated_at`	integer	最近更新时间，Unix 秒级时间戳。
`status`	string	任务状态，见状态表。
`progress`	string	处理进度，例如 `0%`、`45%`、`100%`。
`result_url`	string	任务成功后的最终视频地址；未成功时通常为空或不返回。
`fail_reason`	string	任务失败原因；成功时通常为空。
`submit_time`	integer	提交时间，Unix 秒级时间戳。
`start_time`	integer	开始处理时间，Unix 秒级时间戳；尚未开始时可能为 `0`。
`finish_time`	integer	完成时间，Unix 秒级时间戳；尚未完成时可能为 `0`。

任务状态：

`status`	是否终态	说明
`NOT_START`	否	任务已创建，尚未提交处理。
`SUBMITTED`	否	任务已提交。
`QUEUED`	否	任务正在排队。
`IN_PROGRESS`	否	任务正在处理。
`SUCCESS`	是	处理成功，可以读取 `result_url`。
`FAILURE`	是	处理失败，查看 `fail_reason`。
`UNKNOWN`	否	状态暂时无法识别，建议稍后重试查询。

3.3 处理中响应示例

以下示例仅展示主要业务字段；完整响应字段见上表。

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "model": "minimax-h3",
    "status": "IN_PROGRESS",
    "progress": "45%",
    "result_url": "",
    "fail_reason": "",
    "submit_time": 1788912000,
    "start_time": 1788912003,
    "finish_time": 0
  }
}

3.4 成功响应示例

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "model": "minimax-h3",
    "status": "SUCCESS",
    "progress": "100%",
    "result_url": "https://media.example.com/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.mp4",
    "fail_reason": "",
    "submit_time": 1788912000,
    "start_time": 1788912003,
    "finish_time": 1788912065
  }
}

result_url 是平台最终提供的视频访问地址

3.5 失败响应示例

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "model": "minimax-h3",
    "status": "FAILURE",
    "progress": "100%",
    "fail_reason": "生成任务处理失败",
    "submit_time": 1788912000,
    "start_time": 1788912003,
    "finish_time": 1788912010
  }
}

此处 HTTP 请求本身成功，因此外层 code 仍为 success；业务任务是否成功必须以 data.status 为准。

4. 错误响应

参数错误、鉴权失败、余额不足或服务暂不可用时，会返回非 2xx HTTP 状态码和错误对象：

{
  "code": "invalid_request",
  "message": "OutputConfig.Resolution is invalid",
  "data": null
}

HTTP 状态码	常见场景	处理建议
`400`	JSON、字段、素材组合或任务 ID不合法	根据 `code` 和 `message` 修正请求，不要原样重试。
`401`	API Key 缺失或无效	检查 `Authorization` 请求头。
`402`	可用额度不足	补充额度后重新创建任务。
`429`	请求频率过高	使用指数退避后重试。
`503`	当前模型暂时不可用	稍后重试；持续出现时联系平台管理员检查模型可用状态。
`500`、`502`	服务内部错误或临时通信异常	保留请求时间和错误信息，稍后重试。

错误响应中的 message 用于辅助排查，不建议依赖其完整文本编写程序逻辑；程序应优先判断 HTTP 状态码和 code。

5. 推荐调用流程

使用创建接口提交任务。

确认 HTTP 状态码为 200，保存响应中的 task_id。

每 3～5 秒调用一次查询接口。

status=SUCCESS 时读取 result_url。

status=FAILURE 时记录 fail_reason 并结束轮询。

对非终态任务设置合理的整体超时时间；客户端超时不等于服务端任务失败，之后仍可使用同一 task_id 查询。

MiniMax-h3 视频生成 API 对接文档

1. 接入信息#

1.1 Base URL#

1.2 鉴权#

1.3 Content-Type#

1.4 接口列表#

2. 创建视频生成任务#

2.1 请求参数#

顶层字段#

OutputConfig#

FileInfos 单项字段#

2.2 纯文本生成示例#

2.3 首帧生成示例#

2.4 首尾帧生成示例#

2.5 多模态参考生成示例#

2.6 创建成功响应#

3. 查询视频生成任务#

3.1 统一响应外层#

3.2 任务详情字段#

3.3 处理中响应示例#

3.4 成功响应示例#

3.5 失败响应示例#

4. 错误响应#

5. 推荐调用流程#