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

# MiniMax Hailuo H3 Video Generation

> Generate 2K or 768p videos with MiniMax Hailuo H3 using text, first/last frames, or multimodal references

> [!NOTE]
>
> **Note for users in mainland China:** Please use `https://toapis.cn` as the API endpoint (Base URL). Replace `https://toapis.com` with `https://toapis.cn` in the examples in this document.

* Supports three models: `MiniMax-H3`, `MiniMax-H3-Max`, and `MiniMax-H3-Max-Turbo`
* `MiniMax-H3` and `MiniMax-H3-Max` support text-to-video, first/last-frame generation, and combined image, video, and audio references
* `MiniMax-H3-Max-Turbo` supports only text-to-video and first/last-frame generation, without reference media
* `MiniMax-H3` keeps `2K` / `768p` and `4-15` seconds; Max / Max-Turbo support `480P` / `768P` and `5-15` seconds
* Async API that returns a unified `generation.task`

> [!WARNING]
>
> `MiniMax-H3-Max-Turbo` does not support `reference_image`, `reference_video`, or `reference_audio`. Sending reference media returns `MiniMax-H3-Max-Turbo does not support reference media`. Use `MiniMax-H3` or `MiniMax-H3-Max` for reference videos.

> [!WARNING]
>
> Prefer publicly accessible media URLs. First/last-frame mode and multimodal reference mode are mutually exclusive. Reference audio cannot be used alone and requires at least one reference image or video.

## Authentication

**Authorization** `string` *required*

All endpoints require Bearer Token authentication.

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

## Request Parameters

**model** `string` *required* (default: MiniMax-H3)

Video generation model name: `MiniMax-H3`, `MiniMax-H3-Max`, or `MiniMax-H3-Max-Turbo`. Multimodal references are supported only by `MiniMax-H3` and `MiniMax-H3-Max`; Turbo supports only text-to-video and first/last-frame generation.

**prompt** `string` *required*

Video description, up to `7000` characters. Describe the subject, action, scene, camera movement, style, and sound requirements.

**duration** `integer` (default: 5)

`MiniMax-H3` accepts `4` through `15`; Max / Max-Turbo accept integer values from `5` through `15`.

**resolution** `string` (default: 2K)

`MiniMax-H3` accepts `2K` and `768p`; Max / Max-Turbo accept `480P` and `768P`.

**aspect\_ratio** `string` (default: 16:9)

Output aspect ratio.

Options: `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, or `adaptive`.

* Text-to-video: defaults to `16:9`; `adaptive` is not allowed
* First/last-frame mode: always adapts to the input image and ignores a specific ratio
* Multimodal reference mode (`MiniMax-H3` and `MiniMax-H3-Max` only): defaults to `adaptive`, or accepts a specific ratio

**image\_urls** `string[]`

Image URL array for compatibility. New integrations should use `image_with_roles` to declare each image's purpose explicitly.

* 1 image: treated as `first_frame`
* 2 images: treated as `first_frame` and `last_frame` in order
* 3-9 images: treated as `reference_image`, supported only by `MiniMax-H3` and `MiniMax-H3-Max`; not supported by Turbo

> [!WARNING]
>
> Do not send `image_urls` and `image_with_roles` together because image roles may become ambiguous.

**image\_with\_roles** `array`

Images with explicit roles.

**Show image fields**

**url** `string` *required*

Image URL. Supports JPG, JPEG, PNG, WebP, HEIC, and HEIF. Each file must be no larger than `30 MB`, both dimensions must be `256-5760 px`, and the aspect ratio must be `0.4-2.5`.

**role** `string` *required*

Image role:

* `first_frame` - first frame, at most 1 image
* `last_frame` - last frame, at most 1 image
* `reference_image` - reference image, at most 9 images, supported only by `MiniMax-H3` and `MiniMax-H3-Max`; not supported by Turbo

**video\_with\_roles** `array`

Reference videos for multimodal reference mode, up to `3` videos. Supported only by `MiniMax-H3` and `MiniMax-H3-Max`, not by Turbo.

**Show video fields**

**url** `string` *required*

Public video URL. Supports MP4 and MOV with H.264/AVC or H.265/HEVC video. Each file must be no larger than `50 MB` and `2-15` seconds long; all reference videos combined must not exceed `15` seconds.

**role** `string` *required*

Must be `reference_video`.

> [!NOTE]
>
> ToAPIs reads the actual reference-video duration for billing. Do not submit a client-calculated duration field.

**audio\_with\_roles** `array`

Reference audio for multimodal reference mode, up to `3` audio files. Supported only by `MiniMax-H3` and `MiniMax-H3-Max`, not by Turbo.

**Show audio fields**

**url** `string` *required*

Public audio URL. Supports WAV and MP3. Each file must be no larger than `15 MB` and `2-15` seconds long; all reference audio combined must not exceed `15` seconds.

**role** `string` *required*

Must be `reference_audio`.

> [!WARNING]
>
> Reference audio cannot be used alone. Include at least one `reference_image` or `reference_video`.

**watermark** `boolean` (default: false)

Whether to add an AIGC watermark to the generated video.

**client\_business\_id** `string`

Your business identifier, such as an order or transaction ID. You can query the task using this value through the same status endpoint.

**callback\_url** `string`

ToAPIs task-completion callback URL. Configure the Token URL and signing secret first; see [Task Webhooks](https://docs.toapis.com/docs/en/api-reference/webhooks/task-webhooks.md).

## Input Modes

| Mode | Supported models | Input | `aspect_ratio` |
| - | - | - | - |
| Text-to-video | All three models | `prompt` | Specific ratio, defaults to `16:9` |
| First-frame video | All three models | `prompt` + one `first_frame` | Automatically uses `adaptive` |
| First/last-frame video | All three models | `prompt` + `first_frame` + `last_frame` | Automatically uses `adaptive` |
| Multimodal reference | `MiniMax-H3` and `MiniMax-H3-Max` only | `prompt` + reference images/videos/audio | Defaults to `adaptive`; a specific ratio is allowed |

Multimodal reference limits (`MiniMax-H3` and `MiniMax-H3-Max` only):

* Up to `9` reference images
* Up to `3` reference videos
* Up to `3` reference audio files
* Up to `12` media files total
* First/last-frame roles cannot be mixed with reference roles

## Request Examples

The reference-media examples use `MiniMax-H3`. You cannot use them by simply changing `model` to `MiniMax-H3-Max-Turbo`. To use `MiniMax-H3-Max`, set `resolution` to `480P` or `768P` and `duration` to `5-15` seconds.

### Text-to-video

```json theme={null}
{
  "model": "MiniMax-H3",
  "prompt": "An epic space-opera trailer: a captain watches the last fleet jump away through a vast observation window, cinematic lighting",
  "duration": 5,
  "resolution": "2K",
  "aspect_ratio": "16:9"
}
```

### First and last frames

```json theme={null}
{
  "model": "MiniMax-H3",
  "prompt": "A girl naturally grows from childhood into a young adult, with a steady camera move and consistent identity",
  "duration": 5,
  "resolution": "768p",
  "image_with_roles": [
    {"url": "https://example.com/start.jpg", "role": "first_frame"},
    {"url": "https://example.com/end.jpg", "role": "last_frame"}
  ]
}
```

### Multiple reference images

```json theme={null}
{
  "model": "MiniMax-H3",
  "prompt": "Keep the person from image 1 and the outfit from image 2 as the character walks through a rainy night street",
  "duration": 6,
  "resolution": "2K",
  "aspect_ratio": "9:16",
  "image_with_roles": [
    {"url": "https://example.com/person.png", "role": "reference_image"},
    {"url": "https://example.com/outfit.png", "role": "reference_image"}
  ]
}
```

### Combined video and audio references

```json theme={null}
{
  "model": "MiniMax-H3",
  "prompt": "Follow the action and camera rhythm of video 1, then deliver the dialogue using the voice from audio 1",
  "duration": 5,
  "resolution": "2K",
  "aspect_ratio": "adaptive",
  "video_with_roles": [
    {"url": "https://example.com/motion.mp4", "role": "reference_video"}
  ],
  "audio_with_roles": [
    {"url": "https://example.com/voice.mp3", "role": "reference_audio"}
  ]
}
```

## Response

**id** `string`

ToAPIs task ID used to query task status.

**object** `string`

Object type, always `generation.task`.

**model** `string`

Model used for this request, always `MiniMax-H3`.

**status** `string`

Task status: `queued`, `in_progress`, `completed`, or `failed`.

**progress** `integer`

Task progress percentage from `0` to `100`.

**created\_at** `integer`

Task creation time as a Unix timestamp in seconds.

> [!NOTE]
>
> After submission, poll [Get Video Task Status](https://docs.toapis.com/docs/en/api-reference/tasks/video-status.md). When completed, the video URL is available at `result.data[0].url`.

```bash cURL (Text-to-video) theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MiniMax-H3",
    "prompt": "An astronaut stands at the edge of the moon looking toward Earth as the camera slowly pushes in",
    "duration": 5,
    "resolution": "2K",
    "aspect_ratio": "16:9"
  }'
```

```bash cURL (First and last frames) theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MiniMax-H3",
    "prompt": "A girl naturally grows from childhood into a young adult while her identity remains consistent",
    "duration": 5,
    "resolution": "768p",
    "image_with_roles": [
      {"url": "https://example.com/start.jpg", "role": "first_frame"},
      {"url": "https://example.com/end.jpg", "role": "last_frame"}
    ]
  }'
```

```bash cURL (Multiple reference images) theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MiniMax-H3",
    "prompt": "Keep the person from image 1 and the outfit from image 2 as the character walks through a rainy night street",
    "duration": 6,
    "resolution": "2K",
    "aspect_ratio": "9:16",
    "image_with_roles": [
      {"url": "https://example.com/person.png", "role": "reference_image"},
      {"url": "https://example.com/outfit.png", "role": "reference_image"}
    ]
  }'
```

```bash cURL (Image, video, and audio references) theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MiniMax-H3",
    "prompt": "Keep the person from image 1, follow the motion and camera rhythm of video 1, and use the voice from audio 1",
    "duration": 5,
    "resolution": "2K",
    "aspect_ratio": "adaptive",
    "image_with_roles": [
      {"url": "https://example.com/person.png", "role": "reference_image"}
    ],
    "video_with_roles": [
      {"url": "https://example.com/motion.mp4", "role": "reference_video"}
    ],
    "audio_with_roles": [
      {"url": "https://example.com/voice.mp3", "role": "reference_audio"}
    ]
  }'
```

```python Python (Multimodal references) theme={null}
import requests

response = requests.post(
    "https://toapis.com/v1/videos/generations",
    headers={
        "Authorization": "Bearer your-ToAPIs-key",
        "Content-Type": "application/json",
    },
    json={
        "model": "MiniMax-H3",
        "prompt": "Keep the person from image 1, follow the motion and camera rhythm of video 1, and use the voice from audio 1",
        "duration": 5,
        "resolution": "2K",
        "aspect_ratio": "adaptive",
        "image_with_roles": [
            {"url": "https://example.com/person.png", "role": "reference_image"}
        ],
        "video_with_roles": [
            {"url": "https://example.com/motion.mp4", "role": "reference_video"}
        ],
        "audio_with_roles": [
            {"url": "https://example.com/voice.mp3", "role": "reference_audio"}
        ],
    },
)

print(response.json())
```

```javascript JavaScript (Multimodal references) theme={null}
const response = await fetch("https://toapis.com/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer your-ToAPIs-key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "MiniMax-H3",
    prompt: "Keep the person from image 1, follow the motion and camera rhythm of video 1, and use the voice from audio 1",
    duration: 5,
    resolution: "2K",
    aspect_ratio: "adaptive",
    image_with_roles: [
      {url: "https://example.com/person.png", role: "reference_image"}
    ],
    video_with_roles: [
      {url: "https://example.com/motion.mp4", role: "reference_video"}
    ],
    audio_with_roles: [
      {url: "https://example.com/voice.mp3", role: "reference_audio"}
    ]
  })
});

console.log(await response.json());
```

```json 200 theme={null}
{
  "id": "vid_01KZ3H3EXAMPLE00000000000",
  "object": "generation.task",
  "model": "MiniMax-H3",
  "status": "queued",
  "progress": 0,
  "created_at": 1785729000
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.