> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MiniMax-H3-Max 视频生成

>  - MiniMax 视频生成 V2 极速版，异步返回任务 ID
- 支持文生视频、首尾帧控制和多模态参考生视频
- 支持 480P / 768P / 1080P，时长 5 ~ 15 秒，输出带音轨
- 支持参考图、参考视频和参考音频，不支持 2K 或中间帧 

> [!NOTE]
>
> **模型选择：** `MiniMax-H3-Max` 适合优先生成速度的文生视频、首尾帧控制和多模态参考场景。支持 480P、768P 和 1080P。需要 2K 或中间帧时，请使用 [MiniMax-H3](https://docs.apimart.ai/cn/api-reference/videos/minimax-h3/generation.md)。

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MiniMax-H3-Max",
    "prompt": "雨夜霓虹街头，穿风衣的侦探回头，镜头缓缓推近，水面倒影闪烁。",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }'
```

```python Python theme={null}
import requests

url = "https://api.apimart.ai/v1/videos/generations"

payload = {
    "model": "MiniMax-H3-Max",
    "prompt": "雨夜霓虹街头，穿风衣的侦探回头，镜头缓缓推近，水面倒影闪烁。",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9",
}

headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

```javascript JavaScript theme={null}
const url = "https://api.apimart.ai/v1/videos/generations";

const payload = {
  model: "MiniMax-H3-Max",
  prompt: "雨夜霓虹街头，穿风衣的侦探回头，镜头缓缓推近，水面倒影闪烁。",
  duration: 5,
  resolution: "768P",
  aspect_ratio: "16:9",
};

fetch(url, {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
})
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error("Error:", error));
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "message": "请求参数无效",
    "type": "invalid_request_error"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "身份验证失败，请检查您的 API 密钥",
    "type": "authentication_error"
  }
}
```

```json 402 theme={null}
{
  "error": {
    "code": 402,
    "message": "账户余额不足，请充值后再试",
    "type": "payment_required"
  }
}
```

```json 422 theme={null}
{
  "error": {
    "code": 422,
    "message": "内容安全审核未通过",
    "type": "invalid_request_error"
  }
}
```

```json 429 theme={null}
{
  "error": {
    "code": 429,
    "message": "请求过于频繁，请稍后再试",
    "type": "rate_limit_error"
  }
}
```

```json 500 theme={null}
{
  "error": {
    "code": 500,
    "message": "服务器内部错误，请稍后重试",
    "type": "server_error"
  }
}
```

## 认证

**Authorization** `string` *required*

所有接口均使用 Bearer Token 认证。访问 [API Key 管理页面](https://apimart.ai/keys) 获取密钥。

```
Authorization: Bearer YOUR_API_KEY
```

## 选择模型

| 能力 | `MiniMax-H3` | `MiniMax-H3-Max` |
| - | - | - |
| 分辨率 | `2K` / `768P`，默认 `2K` | `480P` / `768P` / `1080P`，默认 `768P` |
| 时长 | 4 \~ 15 秒 | 5 \~ 15 秒 |
| 文生视频 | 支持 | 支持 |
| 首帧 / 尾帧 / 首尾帧 | 支持 | 支持 |
| 中间帧 | 支持 | 不支持 |
| 多模态参考 | 参考图、视频、音频 | 参考图、视频、音频 |
| 输入图片费用 | 5 张以内免费 | 2 张以内免费，超出按张收费 |
| 参考视频费用 | 按输入时长，与同档输出视频单价一致 | 按输入时长，采用独立单价 |
| AIGC 水印 | 支持 | 480P / 768P 支持；1080P 不支持 |

> [!WARNING]
>
> `MiniMax-H3-Max` 不支持 2K，也不能作为 [Regeneration](https://docs.apimart.ai/cn/api-reference/videos/minimax-h3/regeneration.md) 的源任务。需要这些能力时请使用 `MiniMax-H3`。

## 生成模式

MiniMax-H3-Max 根据请求字段自动识别生成模式，无需传递 `mode`：

| 模式 | 触发条件 | 说明 |
| - | - | - |
| 文生视频（T2V） | 只传 `prompt` 及通用字段 | 纯文本驱动生成 |
| 图生视频（I2V） | 传 `first_frame_image` / `last_frame_image`，或在 `image_with_roles` 中指定首尾帧 | 支持首帧、尾帧或首尾帧控制 |
| 多模态参考（R2V） | 传 `image_urls` / `video_urls` / `audio_urls`，或在 `image_with_roles` 中指定 `reference_image` | 参考图、参考视频和参考音频驱动生成，1080P 同样支持 |

> [!WARNING]
>
> 首尾帧字段与参考素材字段不能混用。参考音频不能单独使用，必须至少搭配一张参考图或一段参考视频。违反组合限制会同步返回 400，不创建任务、不扣费。

## 请求参数

**model** `string` *required*

固定值：`MiniMax-H3-Max`

模型 ID 大小写不敏感，`minimax-h3-max` 也可使用。

**prompt** `string` *required*

视频内容描述，任何场景都必填且不能为空。

* 上限：`7000` 个字符
* 按字符数计算，中文一个字计一个字符

**duration** `integer` (default: 5)

视频时长（秒）。

* 取值：`5` \~ `15` 的整数
* 默认：`5`
* 不支持 `4` 秒

**resolution** `string` (default: 768P)

输出分辨率。

* `768P`（默认）
* `480P`
* `1080P`

选择 `1080P` 时，必须省略 `watermark` 和兼容字段 `aigc_watermark`，即使值为 `false` 也不要传。

> [!WARNING]
>
> 不支持 `2K`、`1440P` 或 `2048P`，传入后会同步返回 400，不会自动降级。

**aspect\_ratio** `string`

输出宽高比。也可使用 `size` 或 `ratio` 传递。

文生视频可选：`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。

* 文生视频不传或传 `adaptive`：自动回落为 `16:9`
* 图生视频：宽高比由输入图片决定，此参数会被忽略
* 多模态参考生视频：可选，默认 `adaptive`，也可指定具体比例

**first\_frame\_image** `string`

首帧图片的公网 URL。传入后以该图片作为视频起始画面。

**last\_frame\_image** `string`

尾帧图片的公网 URL。可以单独使用，也可与 `first_frame_image` 组合实现首尾帧控制。

**image\_with\_roles** `object[]`

带角色的图片数组，可替代 `first_frame_image` / `last_frame_image` / `image_urls`。

**image\_with\_roles 元素**

**url** `string` *required*

图片的公网 URL

**role** `string`

图片角色，可选值：

* `first_frame`：首帧，也接受 `first` / `start`
* `last_frame`：尾帧，也接受 `last` / `end_frame` / `tail`
* `reference_image`：参考图，也接受 `reference`；留空时按参考图处理

首帧和尾帧各最多一张。此数组中的参考图与 `image_urls` 合计最多 `9` 张；首尾帧角色不能与参考图角色混用。

**image\_urls** `string[]`

参考图片的公网 URL 数组，与 `image_with_roles` 中的参考图合计最多 `9` 张。

数组中的图片一律作为参考图，不会按图片数量自动识别为首帧或首尾帧。首帧控制请使用 `first_frame_image` 或明确指定 `first_frame` 角色。

**video\_urls** `string[]`

参考视频的公网 URL 数组。单段视频也可使用 `video_url`（string）传递。

* 最多 `3` 段
* 每段时长 `2` \~ `15` 秒
* 所有参考视频总时长不得超过 `15` 秒

提交时会读取参考视频时长用于计费。无法读取时长时会同步返回 400，不创建任务、不扣费。

**audio\_urls** `string[]`

参考音频的公网 URL 数组。单段音频也可使用 `audio_url`（string）传递。

* 最多 `3` 段
* 每段时长 `2` \~ `15` 秒
* 所有参考音频总时长不得超过 `15` 秒
* 必须至少搭配一张参考图或一段参考视频，不能只传参考音频

**watermark** `boolean` (default: false)

是否添加 AIGC 水印。兼容字段名：`aigc_watermark`。

仅适用于 `480P` / `768P`。选择 `1080P` 时必须省略此字段及其兼容字段，不要传 `true` 或 `false`。

**webhook** `string`

任务成功或失败时，本服务向该地址推送终态通知。

> [!NOTE]
>
> 请使用 `webhook`，不要传 MiniMax 官方的 `callback_url`。`callback_url` 由本服务内部使用，不接受用户传入。

## 参数约束

以下参数或取值会同步返回 400，不创建任务、不扣费：

| 参数 / 取值 | 原因 |
| - | - |
| 首尾帧与参考素材混用 | 图生视频与多模态参考模式互斥 |
| 参考图超过 `9` 张、参考视频或参考音频超过 `3` 段 | 超过素材数量上限 |
| 只传参考音频 | 必须搭配参考图或参考视频 |
| `resolution: "2K"` | 仅支持 `480P`、`768P` 和 `1080P` |
| `duration: 4` 或大于 `15` | 仅支持 5 \~ 15 秒 |

参考视频和参考音频均须满足单段 2 \~ 15 秒、各自总时长不超过 15 秒的限制。不能将超时素材当作有效输入；请先裁剪后再提交。

> [!WARNING]
>
> 选择 `1080P` 时，不能传 `watermark` 或 `aigc_watermark`。请直接省略水印参数，而不是将其设为 `false`。

> [!TIP]
>
> 需要 2K、中间帧或 4 秒视频时，将 `model` 改为 `MiniMax-H3`，并按 [MiniMax-H3 视频生成文档](https://docs.apimart.ai/cn/api-reference/videos/minimax-h3/generation.md) 调整参数。

## 输入媒体限制

请求体总大小不得超过 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 |
| 单文件大小 | ≤ 50 MB |
| 数量 | 最多 3 段 |
| 单段时长 | 2 \~ 15 秒 |
| 总时长 | 所有参考视频合计不超过 15 秒 |
| 宽高 | 256 \~ 5760 px |
| 宽高比（宽 / 高） | 0.4 \~ 2.5 |
| 帧率 | 23.976 \~ 60 fps |

### 参考音频

| 项目 | 限制 |
| - | - |
| 格式 | WAV / MP3 |
| 单文件大小 | ≤ 15 MB |
| 数量 | 最多 3 段 |
| 单段时长 | 2 \~ 15 秒 |
| 总时长 | 所有参考音频合计不超过 15 秒 |

参考音频必须搭配参考图或参考视频。视频总时长和音频总时长分别计算，各自不得超过 15 秒。

不符合输入媒体要求时，任务可能在生成阶段失败并自动退款。

## 请求示例

### 文生视频

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "prompt": "一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜",
  "duration": 6,
  "resolution": "768P",
  "aspect_ratio": "16:9"
}
```

### 首帧图生视频

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "prompt": "镜头缓慢推近，蒸汽升腾，背景人物走动",
  "first_frame_image": "https://cdn.example.com/ramen.png",
  "duration": 5,
  "resolution": "480P"
}
```

### 首尾帧图生视频

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "prompt": "镜头从清晨缓慢过渡到日落",
  "first_frame_image": "https://cdn.example.com/morning.png",
  "last_frame_image": "https://cdn.example.com/sunset.png",
  "duration": 8,
  "resolution": "768P"
}
```

### 使用 image\_with\_roles

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "prompt": "镜头从清晨缓慢过渡到日落",
  "image_with_roles": [
    {
      "url": "https://cdn.example.com/morning.png",
      "role": "first_frame"
    },
    {
      "url": "https://cdn.example.com/sunset.png",
      "role": "last_frame"
    }
  ],
  "duration": 8
}
```

### 1080P 文生视频

选择 1080P 时，请省略 `watermark` 和 `aigc_watermark`。

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "prompt": "海边日落，海浪轻拍沙滩，镜头缓缓推进，电影质感",
  "duration": 5,
  "resolution": "1080P",
  "aspect_ratio": "16:9"
}
```

### 多模态参考生视频

以下参考视频和参考音频均须为 2 \~ 15 秒的有效素材。传多段时，视频和音频各自的总时长不得超过 15 秒。

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "prompt": "参考图里的角色在参考视频的场景中奔跑，配合参考音频的节奏",
  "image_urls": ["https://cdn.example.com/role.png"],
  "video_urls": ["https://cdn.example.com/scene.mp4"],
  "audio_urls": ["https://cdn.example.com/beat.mp3"],
  "duration": 6,
  "resolution": "1080P",
  "aspect_ratio": "16:9"
}
```

## 查询任务

提交成功后返回 `task_id`。使用 [获取任务状态](https://docs.apimart.ai/cn/api-reference/tasks/status.md) 查询生成进度和结果：

```bash theme={null}
curl https://api.apimart.ai/v1/tasks/task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ \
  --header 'Authorization: Bearer <token>'
```

建议每 5 \~ 10 秒轮询一次，客户端超时设置为 15 分钟。

任务成功时：

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ",
    "status": "completed",
    "progress": 100,
    "cost": 0.375,
    "result": {
      "videos": [
        {
          "url": ["https://cdn.example.com/output.mp4"],
          "expires_at": 1785315415
        }
      ]
    }
  }
}
```

| `status` | 含义 |
| - | - |
| `pending` | 已提交或排队中 |
| `processing` | 生成中 |
| `completed` | 成功，视频地址位于 `result.videos[0].url` |
| `failed` | 失败，查看 `error.message`；费用会自动退回 |

> [!NOTE]
>
> 视频 URL 通常约 24 小时有效，请及时下载并转存。

## 计费

总费用包含生成视频费用、超额图片费用和参考视频费用：

```text theme={null}
总费用 = 生成视频每秒单价 × 生成时长
       + 超额图片单价 × max(0, 输入图片张数 − 2)
       + 参考视频每秒单价 × 参考视频总时长
```

首帧、尾帧和参考图合并计算输入图片张数。前 2 张免费，超出后按张收费；参考视频总时长不得超过 15 秒。

| 项目 | 单价 |
| - | - |
| 1080P 视频 | 以模型定价为准 |
| 768P 视频 | 以模型定价为准 |
| 480P 视频 | 以模型定价为准 |
| 输入图片 | 前 2 张免费，超出按张收费，单价以模型定价为准 |
| 参考视频 | 按输入秒数收费，单价以模型定价为准，随输出分辨率变化，与生成视频单价分别计算 |
| 参考音频 | **免费** |

| 示例 | 费用 |
| - | - |
| 768P / 5 秒 | 768P 生成单价 × 5 |
| 768P / 10 秒 | 768P 生成单价 × 10 |
| 480P / 10 秒 | 480P 生成单价 × 10 |
| 480P / 15 秒 | 480P 生成单价 × 15 |
| 768P / 5 秒 + 3 张参考图 | 768P 生成单价 × 5 + 超额图片单价 × 1 |
| 480P / 10 秒 + 共 12 秒参考视频 | 480P 生成单价 × 10 + 480P 参考视频单价 × 12 |
| 1080P / 5 秒 + 2 张参考图 + 参考音频 | 1080P 生成单价 × 5，图片和音频免费 |

上述单价均以模型定价为准。

提交时预扣费用；任务失败会自动全额退款，最终金额以任务查询结果中的 `cost` 为准。

## 错误处理

| 场景 | 状态码 / 处理 |
| - | - |
| `prompt` 为空或超过 7000 字符 | 400，不创建任务 |
| `duration` 不在 5 \~ 15 | 400，不创建任务 |
| `resolution` 不是 `480P` / `768P` / `1080P` | 400，不创建任务 |
| 首尾帧与参考素材混用，或只传参考音频 | 400，不创建任务 |
| 参考图超过 9 张，或参考视频 / 音频超过 3 段 | 400，不创建任务 |
| 无法读取参考视频时长 | 400，不创建任务、不扣费；请检查 URL 和文件是否有效 |
| 图片角色无效或同一首帧 / 尾帧角色超过一张 | 400，不创建任务 |
| 余额不足 | 402 |
| 内容安全审核未通过 | 422 |
| 请求过于频繁 | 429，退避后重试 |

生成阶段失败时，任务状态为 `failed`，`error.message` 会说明原因，预扣费用自动退回。

## Response

**code** `integer`

响应状态码，成功时为 200

**data** `array`

提交时返回任务状态与任务 ID。

**数组元素**

**status** `string`

初始状态为 `submitted`

**task\_id** `string`

任务唯一标识符，用于查询状态和结果


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.