# MiniMax-H3-Fast 视频生成 API 对接文档

## 概述

MiniMax-H3-Fast 是 MiniMax-H3 的极速版本，在保持同样多模态能力的前提下大幅缩短生成耗时，适合快速预览、批量生成等对时效敏感的场景。支持文生视频（T2V）、图生视频（I2V）和视频参考/续写（V2V），可融合图片、视频、音频等多种参考素材生成视频。生成模式由输入素材自动判定，无需显式声明。

**特性**：
- ⚡ **极速生成**：相比标准版 MiniMax-H3 生成速度显著更快
- 🎬 **多模态输入**：文本、参考图（≤9 张）、参考视频（≤3 个）、参考音频（≤3 个）灵活组合
- 🖼️ **首尾帧控制**：支持传入首帧 / 尾帧图片，精确约束视频起止画面
- 🧠 **模式自动判定**：根据输入素材自动选择 T2V / I2V / V2V，无需手动指定
- 📐 **480P 单档**：仅支持 480P 分辨率

> 说明：本模型**仅支持 480P** 分辨率，`resolution` 传入其他值将回退为 `480p`。如需 768p / 2K 等更高分辨率，请使用 MiniMax-H3。

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

---

## 认证方式

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

```
Authorization: Bearer {YOUR_AUTH_TOKEN}
```

---

## 素材组合规则

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

- **首尾帧**（`firstFrameImage` / `lastFrameImage`）与**参考素材**（`imageUrls` / `videoUrls` / `audioUrls`）**不能混用**，二选一。
- **参考音频**（`audioUrls`）**不能单独提交**，必须配合参考图 / 参考视频或首尾帧一起使用。
- `prompt` **必填**，最长 7000 字符。
- **纯文生视频**（不传任何参考素材与首尾帧）时，`aspectRatio` **必须传入具体值**，不能省略。
- 素材上限：参考图 ≤ 9 张、参考视频 ≤ 3 个、参考音频 ≤ 3 个（超出部分会被自动截断）。

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

---

## 支持的使用场景

### 场景1：文生视频（T2V）

纯文本描述生成视频。纯文生视频必须显式指定 `aspectRatio`。

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

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

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

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/minimax-h3-fast" \
  -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": "480p",
    "duration": 5
  }'
```

### 场景3：首尾帧生视频

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

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/minimax-h3-fast" \
  -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": "480p",
    "duration": 5
  }'
```

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

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

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

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/minimax-h3-fast" \
  -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": "480p",
    "duration": 5
  }'
```

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

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

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/minimax-h3-fast" \
  -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": "480p",
    "duration": 8
  }'
```

---

## 查询任务状态

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

---

## 接口详情

### 1. 创建 MiniMax-H3-Fast 任务

**POST** `/api/v2/open/aigc/minimax-h3-fast`

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

**Content-Type**: `application/json`

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| prompt | string | 是 | 提示词，最长 7000 字符 |
| 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 | 否 | 输出分辨率：仅支持 `480p`。传入其他值将回退为 `480p` |
| 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 | 创建时间 |

#### 响应示例

**成功**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260903150000_abc12345",
    "status": "processing",
    "createdAt": "2026-09-03 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 | 更新时间 |

#### 响应示例

**处理中**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260903150000_abc12345",
    "status": "processing",
    "createdAt": "2026-09-03 15:00:00",
    "updatedAt": "2026-09-03 15:00:05"
  }
}
```

**成功**
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "taskId": "task_20260903150000_abc12345",
    "status": "success",
    "result": [
      "https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/2026/09/03/output.mp4"
    ],
    "createdAt": "2026-09-03 15:00:00",
    "updatedAt": "2026-09-03 15:01:10"
  }
}
```

---

### 3. 批量查询任务状态

**POST** `/api/v2/open/aigc/batch`

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

#### 请求参数

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

#### 请求示例

```json
{
  "taskIds": ["task_20260903150000_abc12345", "task_20260903150200_def67890"]
}
```

---

## 回调通知

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

### 回调请求

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

**Body**
```json
{
  "event": "task.completed",
  "taskId": "task_20260903150000_abc12345",
  "status": "success",
  "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/output.mp4"],
  "errorMsg": "",
  "timestamp": "2026-09-03T15:01:10+08:00",
  "signature": "a1b2c3d4e5f6..."
}
```

---

## 参数取值范围

### 分辨率 (resolution)

| 值 | 说明 |
|----|------|
| `480p` | 唯一支持档位（默认） |

> 本模型仅支持 480P；传入其他值将回退为 `480p`。需要更高分辨率请使用 MiniMax-H3。

### 宽高比 (aspectRatio)

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

> 纯文生视频时必须传入具体值；传入参考图 / 首尾帧时输出画幅可能按素材自适应。

### 时长 (duration)

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

---

## 计费说明

- 视频生成**按时长（秒）计费**。本模型仅 480P 一档，每秒单价固定。
- **参考图**（`imageUrls`）前 5 张免费，超出部分按张额外计费。
- 下单时按 15 秒上限预冻结额度，任务完成后按实际请求时长结算并退回差额（只退不追）；任务失败则全额解冻。
- 具体单价请以控制台「定价」页面展示为准。

---

## 错误码

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

---

## 最佳实践

### 1. 轮询策略

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

### 2. 处理时间参考

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

### 3. Prompt 建议

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

---

## 常见问题

### Q1: Fast 与标准版 MiniMax-H3 有什么区别？

**A**: 请求参数、响应结构、查询与回调方式完全一致。区别在于 Fast 生成速度更快、仅支持 480P 分辨率；标准版支持更高分辨率。

### Q2: 如何选择 T2V / I2V / V2V？

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

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

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

### Q4: 只传音频可以吗？

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

### Q5: 参考图最多几张？

**A**: 最多 9 张，超出部分会被自动截断。参考视频、参考音频各最多 3 个。其中前 5 张参考图免费，超出部分按张额外计费。

### Q6: 支持 768p / 2K 吗？

**A**: 不支持。本模型仅提供 `480p` 一档，传入其他值会回退为 `480p`。需要更高分辨率请改用 MiniMax-H3。

### Q7: 纯文生视频可以不传 aspectRatio 吗？

**A**: 不可以。纯文生视频（不含任何参考素材与首尾帧）必须显式传入具体的 `aspectRatio` 值。

---

## 技术支持

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