MiniMax-H3 视频生成 API 文档

概述

MiniMax-H3 是新一代多模态视频生成接口，支持文生视频（T2V）、图生视频（I2V）和视频参考/续写（V2V），可融合图片、视频、音频等多种参考素材生成视频。生成模式由输入素材自动判定，无需显式声明。

特性：
- 🎬 多模态输入：文本、参考图（≤9 张）、参考视频（≤3 个）、参考音频（≤3 个）灵活组合
- 🖼️ 首尾帧控制：支持传入首帧 / 尾帧图片，精确约束视频起止画面
- 🧠 模式自动判定：根据输入素材自动选择 T2V / I2V / V2V，无需手动指定
- 📐 多分辨率：支持 2K（默认）与 768p

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

认证方式

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

Authorization: Bearer {YOUR_AUTH_TOKEN}

素材组合规则

MiniMax-H3 根据输入素材自动判定生成模式，请遵循以下组合规则：

首尾帧（firstFrameImage / lastFrameImage）与参考素材（imageUrls / videoUrls / audioUrls）不能混用，二选一。
参考音频（audioUrls）不能单独提交，必须配合参考图 / 参考视频或首尾帧一起使用。
prompt、imageUrls、videoUrls、firstFrameImage 至少提供一项。
素材上限：参考图 ≤ 9 张、参考视频 ≤ 3 个、参考音频 ≤ 3 个（超出部分会被自动截断）。

输入素材	判定模式
仅 `prompt`	文生视频（T2V）
含 `imageUrls` 或首尾帧	图生视频（I2V）
含 `videoUrls`	视频参考 / 续写（V2V）

支持的使用场景

场景1：文生视频（T2V）

纯文本描述生成视频。

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

场景2：图生视频（I2V）— 单图/多图参考

传入一张或多张参考图，模型基于图片内容生成视频。可在提示词中用 "图片1"、"图片2" 引用对应素材（最多 9 张）。

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/minimax-h3" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "图片1中的女孩抱着图片2中的小狐狸，温柔地看向镜头，镜头缓缓拉出，头发被风吹动",
    "imageUrls": [
      "https://example.com/girl.png",
      "https://example.com/fox.png"
    ],
    "aspectRatio": "16:9",
    "resolution": "2k",
    "duration": 5
  }'

场景3：首尾帧生视频

传入首帧和/或尾帧图片，精确约束视频的起止画面。

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/minimax-h3" \
  -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",
    "aspectRatio": "16:9",
    "resolution": "2k",
    "duration": 5
  }'

注意：首尾帧与参考图 / 视频 / 音频不能混用。

场景4：视频参考 / 续写（V2V）

传入参考视频，模型基于视频内容生成（参考、续写、编辑等）。可配合参考图 / 音频。

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/minimax-h3" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "延续视频1的运镜，主角走进画面右侧的咖啡馆",
    "videoUrls": ["https://example.com/input.mp4"],
    "aspectRatio": "16:9",
    "resolution": "2k",
    "duration": 5
  }'

场景5：多模态参考（图片 + 视频 + 音频）

同时参考图片、视频与音频素材生成视频（音频不能单独提交）。

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/minimax-h3" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "以图片1为主体，全程使用视频1的第一视角构图，全程使用音频1作为背景音乐",
    "imageUrls": ["https://example.com/subject.jpg"],
    "videoUrls": ["https://example.com/ref.mp4"],
    "audioUrls": ["https://example.com/bgm.mp3"],
    "aspectRatio": "16:9",
    "resolution": "2k",
    "duration": 8
  }'

查询任务状态

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

接口详情

1. 创建 MiniMax-H3 任务

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

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

Content-Type: application/json

请求参数

参数	类型	必填	说明
prompt	string	否*	提示词，最长 7000 字符。*`prompt` / `imageUrls` / `videoUrls` / `firstFrameImage` 至少提供一项
imageUrls	string[]	否	参考图 URL 列表，最多 9 张（触发图生视频）
videoUrls	string[]	否	参考视频 URL 列表，最多 3 个（触发视频参考/续写）
audioUrls	string[]	否	参考音频 URL 列表，最多 3 个。不能单独提交，需配合参考图/视频或首尾帧
firstFrameImage	string	否	首帧图片 URL（与参考图/视频/音频互斥）
lastFrameImage	string	否	尾帧图片 URL（与参考图/视频/音频互斥）
aspectRatio	string	否	宽高比：`21:9` / `16:9`(默认) / `4:3` / `1:1` / `3:4` / `9:16`
resolution	string	否	输出分辨率：`2k`(默认) / `768p`
duration	int	否	视频时长（秒），范围 4~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_20260813150000_abc12345",
    "status": "processing",
    "createdAt": "2026-08-13 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_20260813150000_abc12345",
    "status": "processing",
    "createdAt": "2026-08-13 15:00:00",
    "updatedAt": "2026-08-13 15:00:05"
  }
}

成功

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

3. 批量查询任务状态

POST /api/v2/open/aigc/batch

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

请求参数

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

请求示例

{
  "taskIds": ["task_20260813150000_abc12345", "task_20260813150200_def67890"]
}

回调通知

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

回调请求

Headers

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

Body

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

参数取值范围

分辨率 (resolution)

值	说明
`2k`	默认，推荐
`768p`	低清

宽高比 (aspectRatio)

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

时长 (duration)

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

错误码

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

最佳实践

1. 轮询策略

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

2. 处理时间参考

纯文本生视频：通常 1 ~ 3 分钟
图片 + 文本生视频：通常 1 ~ 3 分钟
多模态输入（含视频/音频）：通常 2 ~ 4 分钟
时长越长，处理时间越长

3. Prompt 建议

提示词最长 7000 字符
提示词 = 主体 + 运动，背景 + 运动，镜头 + 运动
用简洁准确的自然语言描述想要的效果
可以指定镜头运动（推进、拉远、环绕等）
通过 "图片1"、"图片2"、"视频1"、"音频1" 引用对应位置的参考素材
结果不符合预期时，建议将抽象描述换成具象描述再重试

常见问题

Q1: 如何选择 T2V / I2V / V2V？

A: 无需显式声明，系统根据输入素材自动判定：仅有提示词为文生视频；含参考图或首尾帧为图生视频；含参考视频为视频参考/续写。

Q2: 首尾帧可以和参考图一起用吗？

A: 不可以。首尾帧（firstFrameImage / lastFrameImage）与参考素材（imageUrls / videoUrls / audioUrls）互斥，二选一。

Q3: 只传音频可以吗？

A: 不可以。audioUrls 不能单独提交，必须配合参考图 / 参考视频或首尾帧一起使用。

Q4: 参考图最多几张？

A: 最多 9 张，超出部分会被自动截断。参考视频、参考音频各最多 3 个。

技术支持

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