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

# MiniMax-H3 视频生成

> 使用 `POST /v1/videos` 创建 MiniMax-H3 异步视频生成任务。

# MiniMax-H3 视频生成

OpenAI 兼容格式入口。接口使用 JSON 请求体，支持文生视频、图生视频与多模态参考生视频。若需统一视频格式，请见 [创建视频](./unified-generation)。

## 方法与路径

```http theme={null}
POST /v1/videos
```

<RequestExample>
  ```bash 文生视频 (t2va) theme={null}
  curl -X POST https://zx1.deepwl.net/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "MiniMax-H3",
      "prompt": "一个男孩在海边打篮球",
      "duration": 5,
      "size": "2K",
      "metadata": {
        "ratio": "16:9"
      }
    }'
  ```

  ```bash 图生视频 (i2va) theme={null}
  curl -X POST https://zx1.deepwl.net/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "MiniMax-H3",
      "prompt": "镜头缓缓推进，海浪拍打礁石溅起水花",
      "duration": 5,
      "size": "2K",
      "image": "https://cdn.example.com/first-frame.jpg",
      "metadata": {
        "ratio": "adaptive"
      }
    }'
  ```

  ```bash 多模态参考生视频 (r2va) theme={null}
  curl -X POST https://zx1.deepwl.net/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "MiniMax-H3",
      "prompt": "沿用参考视频的运动节奏与参考音频的情绪重新生成",
      "duration": 5,
      "size": "2K",
      "metadata": {
        "ratio": "adaptive",
        "reference_video": "https://cdn.example.com/reference.mp4",
        "reference_audio": "https://cdn.example.com/bgm.wav"
      }
    }'
  ```
</RequestExample>

## 生成场景

| 场景       | 传参                                                   | 宽高比                      |
| -------- | ---------------------------------------------------- | ------------------------ |
| 文生视频     | 仅 `prompt`                                           | 默认 `16:9`，不可为 `adaptive` |
| 图生视频     | `image` 或 `images`                                   | 强制 `adaptive`            |
| 多模态参考生视频 | `metadata.reference_video(s)` / `reference_audio(s)` | 默认 `adaptive`            |

<Warning>
  图生视频与多模态参考生视频互斥。请求体总大小不得超过 64 MB，大文件请使用公网 URL，不要使用 Base64。
</Warning>

## Body

<ParamField body="model" type="string" required>
  模型名称，当前仅支持 `MiniMax-H3`。
</ParamField>

<ParamField body="prompt" type="string" required>
  非空提示词，最多 7000 个字符。
</ParamField>

<ParamField body="duration" type="integer" default="5">
  生成时长，范围 4～15 秒。超出范围时服务端会自动钳制到边界值。
</ParamField>

<ParamField body="size" type="string" default="2K">
  输出分辨率，可选 `768P`、`2K`。大小写不敏感，无法识别的值回落为 `2K`。
</ParamField>

<ParamField body="image" type="string">
  单张输入图片，作为首帧。与 `images` 同时传入时优先使用本字段。

  支持公网 URL、`mm_file://{file_id}` 与 Data URL。格式支持 JPG、JPEG、PNG、WEBP、HEIC、HEIF；单文件不超过 30 MB；宽高范围为 256～5760 px；长宽比范围为 0.4～2.5。
</ParamField>

<ParamField body="images" type="array<string>">
  多张输入图片。1 张作为首帧，2 张作为首帧和尾帧，3 张及以上全部作为参考图；参考图最多 9 张。
</ParamField>

<ParamField body="metadata.ratio" type="string">
  可选 `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。文生视频默认 `16:9`；图生视频强制 `adaptive`；多模态参考生视频默认 `adaptive`。
</ParamField>

<ParamField body="metadata.reference_video" type="string">
  单个参考视频地址。支持 MP4、MOV，编码为 H.264/H.265；单文件不超过 50 MB，时长 2～15 秒。
</ParamField>

<ParamField body="metadata.reference_videos" type="array<string>">
  多个参考视频地址，最多 3 个、总时长不超过 15 秒。与 `reference_video` 同时传入时优先使用本字段。
</ParamField>

<ParamField body="metadata.reference_audio" type="string">
  单个参考音频地址。支持 WAV、MP3；单文件不超过 15 MB，时长 2～15 秒。
</ParamField>

<ParamField body="metadata.reference_audios" type="array<string>">
  多个参考音频地址，最多 3 个、总时长不超过 15 秒。与 `reference_audio` 同时传入时优先使用本字段。
</ParamField>

<ParamField body="metadata.aigc_watermark" type="boolean" default="false">
  是否添加 AIGC 标识水印。
</ParamField>

## 响应示例

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "task_a1b2xxxxx5f6",
    "task_id": "task_a1b2xxxxx5f6",
    "object": "video",
    "model": "MiniMax-H3",
    "status": "queued",
    "progress": 0,
    "created_at": 1785125529
  }
  ```

  ```json 400 theme={null}
  {
    "code": "invalid_request",
    "message": "prompt is required",
    "data": null
  }
  ```

  ```json 422 theme={null}
  {
    "code": "unprocessable_entity_error",
    "message": "video description contains sensitive content (1026)",
    "data": null
  }
  ```
</ResponseExample>

## Response

<ResponseField name="id" type="string">
  任务 ID，后续查询请使用此字段。
</ResponseField>

<ResponseField name="task_id" type="string">
  兼容旧接口的任务 ID，值与 `id` 相同；新接入请使用 `id`。
</ResponseField>

<ResponseField name="object" type="string">
  对象类型，固定为 `video`。
</ResponseField>

<ResponseField name="model" type="string">
  任务使用的模型名称。
</ResponseField>

<ResponseField name="status" type="string">
  任务状态：`queued`、`in_progress`、`completed` 或 `failed`。
</ResponseField>

<ResponseField name="progress" type="integer">
  任务进度百分比，范围 0～100。
</ResponseField>

<ResponseField name="created_at" type="integer">
  任务创建时间，Unix 时间戳（秒）。
</ResponseField>

## 错误码

| HTTP 状态码 | 说明          |
| -------- | ----------- |
| `400`    | 请求参数错误      |
| `401`    | 令牌缺失、无效或已过期 |
| `402`    | 额度不足        |
| `422`    | 输入涉及敏感内容    |
| `429`    | 触发限流，请稍后重试  |
| `500`    | 服务端错误       |

## 相关接口

* [MiniMax-H3 视频概览](./overview)
* [2K 再生成](./remix)
* [任务查询](./query)
* [创建视频（统一格式）](./unified-generation)