MiniMax-H3-Max 视频生成 API 文档

概述

MiniMax-H3-Max 是高质量视频生成接口，支持文生视频（T2V）与图生视频（I2V，首帧 / 尾帧）。生成模式由输入素材自动判定，无需显式声明。

特性：
- 🎬 文生视频：纯文本描述直接生成视频
- 🖼️ 首尾帧控制：支持传入首帧 / 尾帧图片，精确约束视频起止画面
- 🧠 模式自动判定：根据输入素材自动选择 T2V / I2V
- 📐 双分辨率：支持 768p（默认）与 480p
- ⏱️ 长时长：单次可生成 5 ~ 15 秒视频

说明：本模型不支持参考图、中间帧、参考视频与参考音频，也不支持 2K 分辨率。如需上述能力请使用 MiniMax-H3。

Base URL: https://api.apiverse.ai（国内专线）

认证方式

所有接口均需要在请求头中携带 Token 进行认证：

Authorization: Bearer {YOUR_AUTH_TOKEN}

素材组合规则

MiniMax-H3-Max 根据输入素材自动判定生成模式：

输入素材	判定模式
仅 `prompt`	文生视频（T2V）
含 `firstFrameImage` 和/或 `lastFrameImage`	图生视频（I2V）

prompt、firstFrameImage 至少提供一项，prompt 最长 7000 字符。
首帧、尾帧可只传其一，也可同时传入。
本接口不接受参考图、参考视频、参考音频参数。

支持的使用场景

场景1：文生视频（T2V）

纯文本描述生成视频。

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/minimax-h3-max" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "写实风格，晴朗的蓝天之下，一大片白色的雏菊花田，镜头逐渐拉近，最终定格在一朵雏菊花的特写上，花瓣上有几颗晶莹的露珠",
    "aspectRatio": "16:9",
    "resolution": "768p",
    "duration": 5
  }'

场景2：首帧生视频（I2V）

传入首帧图片，模型以该画面为起点生成视频。

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/minimax-h3-max" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "画面中的女孩温柔地看向镜头，镜头缓缓拉出，头发被风吹动",
    "firstFrameImage": "https://example.com/girl.png",
    "resolution": "768p",
    "duration": 8
  }'

场景3：首尾帧生视频

同时传入首帧与尾帧图片，精确约束视频的起止画面。

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/minimax-h3-max" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "镜头从清晨的城市街道缓缓推进到日落时分的同一街道",
    "firstFrameImage": "https://example.com/morning.png",
    "lastFrameImage": "https://example.com/sunset.png",
    "resolution": "768p",
    "duration": 10
  }'

提示：传入首尾帧时，输出画幅由图片自适应决定，aspectRatio 不再生效。

查询任务状态

curl -X GET "https://api.apiverse.ai/api/v2/open/aigc/{taskId}" \
  -H "Authorization: Bearer your_auth_token_here"

接口详情

1. 创建 MiniMax-H3-Max 任务

POST /api/v2/open/aigc/minimax-h3-max

创建一个 MiniMax-H3-Max 视频生成任务。生成模式（T2V / I2V）由输入素材自动判定。

Content-Type: application/json

请求参数

参数	类型	必填	说明
prompt	string	否	提示词，最长 7000 字符。与 `firstFrameImage` 至少提供一项
firstFrameImage	string	否	首帧图片 URL（触发图生视频）
lastFrameImage	string	否	尾帧图片 URL（触发图生视频）
aspectRatio	string	否	宽高比：`21:9` / `16:9`(默认) / `4:3` / `1:1` / `3:4` / `9:16`。传入首尾帧时按图片自适应，本参数不生效
resolution	string	否	输出分辨率：`768p`(默认) / `480p`。不支持 2K
duration	int	否	视频时长（秒），范围 5~15，默认 5。越界回退默认值
watermark	bool	否	是否添加水印
taskNickname	string	否	任务昵称，便于业务侧标识
callbackUrl	string	否	任务完成后的回调通知 URL

响应参数

参数	类型	说明
code	int	状态码，0 表示成功
msg	string	状态信息
data.taskId	string	任务 ID，用于查询任务状态
data.status	string	任务状态，创建时固定为 `processing`
data.createdAt	string	创建时间

响应示例

成功

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260831150000_abc12345",
    "status": "processing",
    "createdAt": "2026-08-31 15:00:00"
  }
}

2. 查询任务状态

GET /api/v2/open/aigc/{taskId}

查询单个任务的执行状态。

路径参数

参数	类型	必填	说明
taskId	string	是	任务 ID

响应参数

参数	类型	说明
code	int	状态码，0 表示成功
msg	string	状态信息
data.taskId	string	任务 ID
data.status	string	任务状态：`processing` / `success` / `failed`
data.result	string[]	生成的视频 URL 列表（成功时返回）
data.errorMsg	string	错误信息（失败时返回）
data.createdAt	string	创建时间
data.updatedAt	string	更新时间

响应示例

处理中

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260831150000_abc12345",
    "status": "processing",
    "createdAt": "2026-08-31 15:00:00",
    "updatedAt": "2026-08-31 15:00:05"
  }
}

成功

{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260831150000_abc12345",
    "status": "success",
    "result": [
      "https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/2026/08/31/output.mp4"
    ],
    "createdAt": "2026-08-31 15:00:00",
    "updatedAt": "2026-08-31 15:02:30"
  }
}

3. 批量查询任务状态

POST /api/v2/open/aigc/batch

批量查询多个任务的执行状态（最多 100 个）。

请求参数

参数	类型	必填	说明
taskIds	string[]	是	任务 ID 列表，最多 100 个

请求示例

{
  "taskIds": ["task_20260831150000_abc12345", "task_20260831150200_def67890"]
}

回调通知

当任务完成（成功或失败）时，如果创建任务时提供了 callbackUrl，系统会向该 URL 发送 POST 请求。

回调请求

Headers

Content-Type: application/json
X-Funcloud-Event: task.completed
X-Funcloud-Signature: {签名}

Body

{
  "event": "task.completed",
  "taskId": "task_20260831150000_abc12345",
  "status": "success",
  "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/output.mp4"],
  "errorMsg": "",
  "timestamp": "2026-08-31T15:02:30+08:00",
  "signature": "a1b2c3d4e5f6..."
}

参数取值范围

分辨率 (resolution)

值	说明
`768p`	默认，推荐
`480p`	低清，成本更低

本模型不支持 2K；传入其他值将回退为默认 768p。

宽高比 (aspectRatio)

值	说明
`21:9`	超宽屏
`16:9`	横屏（默认）
`4:3`	标准横屏
`1:1`	方形
`3:4`	标准竖屏
`9:16`	竖屏

传入首帧 / 尾帧时输出画幅按图片自适应，本参数不生效。

时长 (duration)

范围：5 ~ 15 秒
默认：5 秒
传入越界值将回退为默认 5 秒

计费说明

按视频时长（秒）计费，分辨率越高单价越高（480p < 768p）。首尾帧不额外计费。

下单时按 15 秒上限预冻结额度，任务完成后按实际请求时长结算并退回差额（只退不追）；任务失败则全额解冻。

错误码

code	说明
0	成功
10002	参数缺失或格式错误
10005	API Key 无效或缺失
10006	余额不足
30003	任务不存在
90003	服务器内部错误

最佳实践

1. 轮询策略

建议的轮询间隔：
- 前 30 秒：每 3 秒查询一次
- 30 秒 ~ 2 分钟：每 5 秒查询一次
- 2 分钟后：每 10 秒查询一次

2. 处理时间参考

纯文本生视频：通常 1 ~ 3 分钟
首尾帧生视频：通常 1 ~ 3 分钟
时长越长、分辨率越高，处理时间越长

3. Prompt 建议

提示词最长 7000 字符
提示词 = 主体 + 运动，背景 + 运动，镜头 + 运动
用简洁准确的自然语言描述想要的效果
可以指定镜头运动（推进、拉远、环绕等）
结果不符合预期时，建议将抽象描述换成具象描述再重试

常见问题

Q1: 如何选择 T2V / I2V？

A: 无需显式声明。只传 prompt 为文生视频；传入 firstFrameImage 和/或 lastFrameImage 为图生视频。

Q2: 可以传参考图 / 参考视频 / 参考音频吗？

A: 不可以。本模型仅支持首帧、尾帧图片。需要参考图、参考视频或参考音频请改用 MiniMax-H3。

Q3: 支持 2K 分辨率吗？

A: 不支持。本模型仅提供 480p 与 768p 两档，传入其他值会回退为 768p。

Q4: 只传尾帧可以吗？

A: 可以。首帧、尾帧可只传其一，也可同时传入。

Q5: 时长可以超过 15 秒吗？

A: 不可以。范围为 5 ~ 15 秒，越界会回退为默认 5 秒。

技术支持

如有疑问，请联系我们的技术支持团队。