> ## 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 Video Generation

> Create a MiniMax-H3 async video generation task with `POST /v1/videos`.

# MiniMax-H3 Video Generation

OpenAI-compatible entry point. Uses a JSON request body and supports text-to-video, image-to-video, and multimodal reference-to-video. For the unified video format, see [Create Video](./unified-generation).

## Method and Path

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

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

  ```bash Image-to-video (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": "Camera slowly pushes in, waves crashing against rocks and splashing",
      "duration": 5,
      "size": "2K",
      "image": "https://cdn.example.com/first-frame.jpg",
      "metadata": {
        "ratio": "adaptive"
      }
    }'
  ```

  ```bash Multimodal reference (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": "Re-generate following the reference video motion and the reference audio mood",
      "duration": 5,
      "size": "2K",
      "metadata": {
        "ratio": "adaptive",
        "reference_video": "https://cdn.example.com/reference.mp4",
        "reference_audio": "https://cdn.example.com/bgm.wav"
      }
    }'
  ```
</RequestExample>

## Generation Scenarios

| Scenario                      | Parameters                                           | Aspect ratio                               |
| ----------------------------- | ---------------------------------------------------- | ------------------------------------------ |
| Text-to-video                 | `prompt` only                                        | Defaults to `16:9`; `adaptive` not allowed |
| Image-to-video                | `image` or `images`                                  | Forced to `adaptive`                       |
| Multimodal reference-to-video | `metadata.reference_video(s)` / `reference_audio(s)` | Defaults to `adaptive`                     |

<Warning>
  Image-to-video and multimodal reference-to-video are mutually exclusive. The total request body size must not exceed 64 MB; for large files use a public URL instead of Base64.
</Warning>

## Body

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

<ParamField body="prompt" type="string" required>
  Non-empty prompt, up to 7000 characters.
</ParamField>

<ParamField body="duration" type="integer" default="5">
  Duration in seconds, range 4–15. Out-of-range values are clamped to the boundary by the server.
</ParamField>

<ParamField body="size" type="string" default="2K">
  Output resolution: `768P` or `2K`. Case-insensitive; unrecognized values fall back to `2K`.
</ParamField>

<ParamField body="image" type="string">
  A single input image used as the first frame. Takes precedence over `images` when both are present.

  Supports public URLs, `mm_file://{file_id}`, and Data URLs. Formats: JPG, JPEG, PNG, WEBP, HEIC, HEIF; max 30 MB per file; dimensions 256–5760 px; aspect ratio 0.4–2.5.
</ParamField>

<ParamField body="images" type="array<string>">
  Multiple input images. One image is the first frame, two are first and last frame, three or more are all treated as reference images; up to 9 reference images.
</ParamField>

<ParamField body="metadata.ratio" type="string">
  One of `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. Text-to-video defaults to `16:9`; image-to-video is forced to `adaptive`; multimodal reference defaults to `adaptive`.
</ParamField>

<ParamField body="metadata.reference_video" type="string">
  A single reference video URL. Supports MP4, MOV, encoded H.264/H.265; max 50 MB per file; duration 2–15 seconds.
</ParamField>

<ParamField body="metadata.reference_videos" type="array<string>">
  Multiple reference video URLs, up to 3 with total duration ≤ 15 seconds. Takes precedence over `reference_video` when both are present.
</ParamField>

<ParamField body="metadata.reference_audio" type="string">
  A single reference audio URL. Supports WAV, MP3; max 15 MB per file; duration 2–15 seconds.
</ParamField>

<ParamField body="metadata.reference_audios" type="array<string>">
  Multiple reference audio URLs, up to 3 with total duration ≤ 15 seconds. Takes precedence over `reference_audio` when both are present.
</ParamField>

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

## Response Example

<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">
  Task ID. Use this for subsequent queries.
</ResponseField>

<ResponseField name="task_id" type="string">
  Legacy task ID; same value as `id`. New integrations should use `id`.
</ResponseField>

<ResponseField name="object" type="string">
  Object type, always `video`.
</ResponseField>

<ResponseField name="model" type="string">
  Model name used by the task.
</ResponseField>

<ResponseField name="status" type="string">
  Task status: `queued`, `in_progress`, `completed`, or `failed`.
</ResponseField>

<ResponseField name="progress" type="integer">
  Task progress percentage, 0–100.
</ResponseField>

<ResponseField name="created_at" type="integer">
  Task creation time, Unix timestamp (seconds).
</ResponseField>

## Error Codes

| HTTP Status | Description                        |
| ----------- | ---------------------------------- |
| `400`       | Invalid request parameters         |
| `401`       | Token missing, invalid, or expired |
| `402`       | Insufficient quota                 |
| `422`       | Input contains sensitive content   |
| `429`       | Rate limited, retry later          |
| `500`       | Server error                       |

## Related Endpoints

* [MiniMax-H3 Video Overview](./overview)
* [2K Regeneration](./remix)
* [Task Query](./query)
* [Create Video (Unified Format)](./unified-generation)