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

# Create Video (Official Format)

> Submit a MiniMax-H3 multimodal video generation task with `POST /v1/video/generations`.

# Create Video (Official Format)

Submit a MiniMax-H3 video generation task, supporting text-to-video, first-frame / first-and-last-frame image-to-video, and reference image/video/audio modes.

## Method and Path

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

## Request Example

<RequestExample>
  ```bash Text-to-video (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": "A boy playing basketball by the sea"
        }
      ],
      "metadata": {
        "duration": 5,
        "resolution": "2K",
        "ratio": "16:9",
        "aigc_watermark": false
      }
    }'
  ```

  ```bash Image-to-video (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": "A boy playing basketball by the sea"
        },
        {
          "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 Multimodal reference (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": "A boy playing basketball by the sea"
        },
        {
          "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>

## Response Example

<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": "Too many requests, please retry later",
      "type": "new_api_error"
    }
  }
  ```

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

Poll the `task_id` with [Query Task (Official Format)](./official-query) after submission.

## Authentication

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

## Body

<ParamField body="model" type="string" required>
  Model name. Currently only `MiniMax-H3` is supported.
</ParamField>

<ParamField body="content" type="array<object>" required>
  Multimodal input array; order affects role assignment.
</ParamField>

<ParamField body="content[].type" type="string" required>
  Content type: `text`, `image_url`, `video_url`, `audio_url`.
</ParamField>

<ParamField body="content[].text" type="string">
  Required when `type=text`. The prompt text.
</ParamField>

<ParamField body="content[].image_url" type="object">
  Used when `type=image_url`; must contain `url`.
</ParamField>

<ParamField body="content[].image_url.url" type="string" required>
  Public image URL. Formats: JPG, JPEG, PNG, WEBP, HEIC, HEIF; max 30 MB per file; dimensions 256–5760 px; aspect ratio 0.4–2.5. First frame ≤ 1 image, last frame ≤ 1 image, reference images ≤ 9.
</ParamField>

<ParamField body="content[].video_url" type="object">
  Used when `type=video_url`; must contain `url`.
</ParamField>

<ParamField body="content[].video_url.url" type="string" required>
  Reference video public URL. Formats: MP4, MOV; encoding H.264/AVC, H.265/HEVC; max 50 MB per file; count ≤ 3; each clip 2–15 seconds, total ≤ 15 seconds; dimensions 256–5760 px; aspect ratio 0.4–2.5; frame rate 23.976–60.
</ParamField>

<ParamField body="content[].audio_url" type="object">
  Used when `type=audio_url`; must contain `url`.
</ParamField>

<ParamField body="content[].audio_url.url" type="string" required>
  Reference audio public URL. Formats: WAV, MP3; max 15 MB per file; count ≤ 3; each clip 2–15 seconds, total ≤ 15 seconds.
</ParamField>

<ParamField body="content[].role" type="string">
  Media role:

  * `first_frame`: first frame (image)
  * `last_frame`: last frame (image)
  * `reference_image`: reference image
  * `reference_video`: reference video
  * `reference_audio`: reference audio
</ParamField>

<ParamField body="metadata" type="object">
  Video generation parameters, all optional.
</ParamField>

<ParamField body="metadata.duration" type="integer">
  Video duration (seconds). Valid range `[4, 15]`, default `5`.
</ParamField>

<ParamField body="metadata.resolution" type="string">
  Resolution: `768P`, `2K`, default `2K`.
</ParamField>

<ParamField body="metadata.ratio" type="string">
  Aspect ratio: `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. For text-to-video, defaults to `16:9` and cannot be `adaptive`; for image-to-video, forced to `adaptive`.
</ParamField>

<ParamField body="metadata.aigc_watermark" type="boolean">
  Whether to add an AIGC watermark to the generated video, default `false`.
</ParamField>

## content Mixing Rules

Violating the following rules may return `400`:

* `reference_image` / `reference_video` / `reference_audio` cannot appear together with `first_frame` / `last_frame`
* Every request must include a non-empty `text` item (the prompt is required)
* The total request body must not exceed 64 MB; use public URLs for large files instead of Base64

## Generation Mode Mapping

| Mode                                 | Request example                          | `content` essentials                                               |
| ------------------------------------ | ---------------------------------------- | ------------------------------------------------------------------ |
| Text-to-video (t2va)                 | [Text-to-video](#request-example)        | `text` only                                                        |
| Image-to-video (i2va)                | [Image-to-video](#request-example)       | `text` + `first_frame` + `last_frame`                              |
| Multimodal reference-to-video (r2va) | [Multimodal reference](#request-example) | `text` + `reference_image` + `reference_video` + `reference_audio` |

## Response

<ResponseField name="task_id" type="string">
  Task ID, used for [Query Task (Official Format)](./official-query).
</ResponseField>

## Related Endpoints

* [MiniMax-H3 Video Overview](./overview)
* [Video Generation (OpenAI Format)](./generation)
* [Create Video (Unified Format)](./unified-generation)
* [Official Format Query Task](./official-query)