> ## 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.

# 创建视频（官方格式）

> 使用 `POST /v1/video/generations` 提交 MiniMax-H3 多模态视频生成任务。

# 创建视频（官方格式）

提交 MiniMax-H3 视频生成任务，支持文生视频、首帧/首尾帧、参考图/视频/音频等模式。

## 方法与路径

```http theme={null}
POST /v1/video/generations
```

## 请求示例

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

  ```bash 图生视频 (i2va) theme={null}
  curl -X POST https://zx1.deepwl.net/v1/video/generations \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "MiniMax-H3",
      "content": [
        {
          "type": "text",
          "text": "一个男孩在海边打篮球"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/first-frame.jpg"
          },
          "role": "first_frame"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/last-frame.jpg"
          },
          "role": "last_frame"
        }
      ],
      "metadata": {
        "duration": 5,
        "resolution": "2K",
        "ratio": "adaptive",
        "aigc_watermark": false
      }
    }'
  ```

  ```bash 多模态参考生视频 (r2va) theme={null}
  curl -X POST https://zx1.deepwl.net/v1/video/generations \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "MiniMax-H3",
      "content": [
        {
          "type": "text",
          "text": "一个男孩在海边打篮球"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/reference.png"
          },
          "role": "reference_image"
        },
        {
          "type": "video_url",
          "video_url": {
            "url": "https://example.com/reference.mp4"
          },
          "role": "reference_video"
        },
        {
          "type": "audio_url",
          "audio_url": {
            "url": "https://example.com/bgm.wav"
          },
          "role": "reference_audio"
        }
      ],
      "metadata": {
        "duration": 5,
        "resolution": "2K",
        "ratio": "adaptive",
        "aigc_watermark": false
      }
    }'
  ```
</RequestExample>

## 响应示例

<ResponseExample>
  ```json 200 theme={null}
  {
    "task_id": "424010985738629"
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "InvalidParameter",
      "message": "content must contain a non-empty text item (2013)",
      "type": "new_api_error"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "Unauthorized",
      "message": "Invalid API key provided",
      "type": "new_api_error"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "Forbidden",
      "message": "access denied",
      "type": "new_api_error"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "UnprocessableEntity",
      "message": "video description contains sensitive content (1026)",
      "type": "new_api_error"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RateLimitExceeded",
      "message": "当前请求频率过高，请稍后再试",
      "type": "new_api_error"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "InternalError",
      "message": "internal server error",
      "type": "new_api_error"
    }
  }
  ```
</ResponseExample>

提交后使用 [查询任务（官方格式）](./official-query) 轮询 `task_id`。

## 认证

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Body

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

<ParamField body="content" type="array<object>" required>
  多模态输入数组，顺序影响角色分配。
</ParamField>

<ParamField body="content[].type" type="string" required>
  内容类型：`text`、`image_url`、`video_url`、`audio_url`。
</ParamField>

<ParamField body="content[].text" type="string">
  当 `type=text` 时必填，提示词文本。
</ParamField>

<ParamField body="content[].image_url" type="object">
  当 `type=image_url` 时使用，须包含 `url`。
</ParamField>

<ParamField body="content[].image_url.url" type="string" required>
  图片公网 URL。支持 JPG、JPEG、PNG、WEBP、HEIC、HEIF；单文件不超过 30 MB；宽高范围为 256～5760 px；长宽比范围为 0.4～2.5。首帧 ≤ 1 张、尾帧 ≤ 1 张、参考图 ≤ 9 张。
</ParamField>

<ParamField body="content[].video_url" type="object">
  当 `type=video_url` 时使用，须包含 `url`。
</ParamField>

<ParamField body="content[].video_url.url" type="string" required>
  参考视频公网 URL。支持 MP4、MOV，编码为 H.264/AVC、H.265/HEVC；单文件不超过 50 MB；个数 ≤ 3；单段 2～15 秒、总时长不超过 15 秒；宽高范围为 256～5760 px；长宽比范围为 0.4～2.5；帧率范围为 23.976～60。
</ParamField>

<ParamField body="content[].audio_url" type="object">
  当 `type=audio_url` 时使用，须包含 `url`。
</ParamField>

<ParamField body="content[].audio_url.url" type="string" required>
  参考音频公网 URL。支持 WAV、MP3；单文件不超过 15 MB；个数 ≤ 3；单段 2～15 秒、总时长不超过 15 秒。
</ParamField>

<ParamField body="content[].role" type="string">
  媒体角色：

  * `first_frame`：首帧（图片）
  * `last_frame`：尾帧（图片）
  * `reference_image`：参考图
  * `reference_video`：参考视频
  * `reference_audio`：参考音频
</ParamField>

<ParamField body="metadata" type="object">
  视频生成参数，均为可选。
</ParamField>

<ParamField body="metadata.duration" type="integer">
  视频时长（秒）。合法范围 `[4, 15]`，默认 `5`。
</ParamField>

<ParamField body="metadata.resolution" type="string">
  分辨率：`768P`、`2K`，默认 `2K`。
</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.aigc_watermark" type="boolean">
  是否在生成视频中添加 AIGC 标识水印，默认 `false`。
</ParamField>

## content 混用规则

违反以下规则可能返回 `400`：

* `reference_image` / `reference_video` / `reference_audio` 不能与 `first_frame` / `last_frame` 同时出现
* 每次请求必须包含一个非空 `text` 项（prompt 必填）
* 请求体总大小不得超过 64 MB，大文件请使用公网 URL，不要使用 Base64

## 生成模式对照

| 模式              | 请求示例              | content 要点                                                         |
| --------------- | ----------------- | ------------------------------------------------------------------ |
| 文生视频 (t2va)     | [文生视频](#请求示例)     | 仅 `text`                                                           |
| 图生视频 (i2va)     | [图生视频](#请求示例)     | `text` + `first_frame` + `last_frame`                              |
| 多模态参考生视频 (r2va) | [多模态参考生视频](#请求示例) | `text` + `reference_image` + `reference_video` + `reference_audio` |

## Response

<ResponseField name="task_id" type="string">
  任务 ID，用于 [查询任务（官方格式）](./official-query)。
</ResponseField>

## 相关接口

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