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

# 创建 MiniMax H3 视频任务

> 通过多模态输入创建 768P 或 2K 的 MiniMax H3 异步视频任务。

视频生成接口通过多模态 `content` 数组接收文本、图片、视频和音频，支持文生视频、图生视频、首尾帧生视频和多模态参考生视频。

```
POST /v1/videos/generations
```

<Note>
  本接口为异步接口。创建成功后返回平台任务 `id`，通过 [查询 MiniMax H3 视频任务](/guides/minimax-h3-query-task) 获取任务状态和生成结果。
</Note>

## 请求示例

<CodeGroup>
  ```json 文生视频（t2va） theme={null}
  {
    "model": "minimax-h3",
    "content": [
      {
        "type": "text",
        "text": "史诗级太空歌剧院线预告：女舰长独自站在巨大观景窗前，最后一支舰队正在集结并跃迁离去，强光爆闪、舰桥震动，她被留在原地。"
      }
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "16:9"
  }
  ```

  ```json 图生视频（i2va） theme={null}
  {
    "model": "minimax-h3",
    "content": [
      {
        "type": "text",
        "text": "Pull focus to the people in the background and add more steam to the ramen bowl."
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/h3-first-frame.png"
        },
        "role": "first_frame"
      }
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "adaptive"
  }
  ```

  ```json 多模态参考生视频（r2va） theme={null}
  {
    "model": "minimax-h3",
    "content": [
      {
        "type": "text",
        "text": "角色说话：Follow the wind, live free. Leave worries behind, enjoy the moment，音色参考音频1"
      },
      {
        "type": "video_url",
        "video_url": {
          "url": "https://example.com/h3-reference-video.mp4"
        },
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": {
          "url": "https://example.com/h3-reference-audio.mp3"
        },
        "role": "reference_audio"
      }
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "adaptive"
  }
  ```
</CodeGroup>

## 请求参数

| 参数               | 类型        | 必填 | 说明                                                    |
| ---------------- | --------- | -- | ----------------------------------------------------- |
| `model`          | string    | 是  | 固定使用 `minimax-h3`。                                    |
| `content`        | object\[] | 是  | 多模态输入数组，必须且只能包含一项非空 `text`。                           |
| `resolution`     | string    | 是  | 支持 `768P`、`2K`。                                       |
| `duration`       | integer   | 是  | 生成视频时长，支持 4–15 秒的整数。                                  |
| `ratio`          | string    | 是  | 支持 `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。 |
| `aigc_watermark` | boolean   | 否  | 是否添加“AI生成”水印，默认关闭。                                    |

## content 输入要求

每次请求必须包含且只能包含一个非空 `text` 项。支持以下输入组合：

1. **文生视频**：仅包含一个 `text`；`ratio` 必填且不能为 `adaptive`。
2. **图生视频 - 首帧**：`text` + 一张 `role=first_frame` 的图片；图片未设置 `role` 时按首帧处理。
3. **图生视频 - 尾帧**：`text` + 一张 `role=last_frame` 的图片。
4. **图生视频 - 首尾帧**：`text` + 一张首帧图片 + 一张尾帧图片。
5. **多模态参考生视频**：`text` + `reference_image`、`reference_video`、`reference_audio` 的组合。

<Warning>
  首帧或尾帧输入不能与多模态参考输入混用。`reference_audio` 必须同时搭配至少一张参考图片或一个参考视频。
</Warning>

图生视频的宽高比由输入图片决定，传 `adaptive`。多模态参考生视频可传 `adaptive` 或支持的固定比例。

## 素材限制

请求体总大小不能超过 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；音频 AAC/MP3 |
| 单文件大小   | 不超过 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 秒 |

多模态参考图片、视频和音频合计不能超过 12 个。

<Note>
  如果音频使用 Base64 Data URI，请使用 `data:audio/mp3;base64,...` 或 `data:audio/wav;base64,...`。沙箱实测 `data:audio/mpeg;base64,...` 会被 MiniMax 上游识别为 `.mpeg` 并拒绝；公网 `.mp3` 或 `.wav` 地址不受此限制。
</Note>

## 创建响应

HTTP 状态码：`202 Accepted`

```json theme={null}
{
  "id": "vidtask_c22b8c06d0524a64a85ef3632fd7015e",
  "object": "video.generation.task",
  "created": 1785987048,
  "model": "minimax-h3",
  "status": "queued",
  "expires_at": 1786159848
}
```

## 失败状态

| HTTP 状态码 | 错误类型                    | 场景                     |
| -------- | ----------------------- | ---------------------- |
| `400`    | `invalid_request_error` | 参数缺失、输入组合不合法或素材不符合限制。  |
| `401`    | `authentication_error`  | API Key 缺失或无效。         |
| `402`    | `insufficient_balance`  | 当前账户余额不足。              |
| `403`    | `model_not_visible`     | 模型不可见或当前 API Key 没有权限。 |
| `429`    | `quota_exceeded`        | API Key 额度已用尽或请求受到限流。  |
| `500`    | `internal_error`        | 平台内部错误，任务未成功创建。        |