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

# MiniMax-H3-Max Video Generation

>  - MiniMax Video Generation V2 fast model with asynchronous task submission
- Supports text-to-video, first/last-frame control, and multimodal reference generation
- Supports 480P / 768P / 1080P, durations of 5–15 seconds, with audio
- Supports reference images, videos, and audio; 2K and middle frames are not supported 

> [!NOTE]
>
> **Model selection:** Use `MiniMax-H3-Max` for fast text-to-video, first/last-frame control, or multimodal reference generation at 480P, 768P, or 1080P. For 2K or middle frames, use [MiniMax-H3](https://gccai.heqingsong.uk/en/api-reference/videos/minimax-h3/generation.md).

```bash cURL theme={null}
curl --request POST \
  --url https://gccai.heqingsong.uk/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MiniMax-H3-Max",
    "prompt": "A detective in a trench coat turns around on a neon-lit street in the rain. The camera slowly pushes in as reflections shimmer on the pavement.",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://gccai.heqingsong.uk/v1/videos/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "model": "MiniMax-H3-Max",
        "prompt": "A detective turns around on a neon-lit street in the rain.",
        "duration": 5,
        "resolution": "768P",
        "aspect_ratio": "16:9",
    },
)

print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://gccai.heqingsong.uk/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "MiniMax-H3-Max",
    prompt: "A detective turns around on a neon-lit street in the rain.",
    duration: 5,
    resolution: "768P",
    aspect_ratio: "16:9",
  }),
});

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

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "Authentication failed. Check your API key.",
    "type": "authentication_error"
  }
}
```

```json 402 theme={null}
{
  "error": {
    "code": 402,
    "message": "Insufficient account balance",
    "type": "payment_required"
  }
}
```

## Authentication

**Authorization** `string` *required*

All endpoints require Bearer Token authentication. Get your key from the [API Key page](https://gccai.heqingsong.uk/keys).

```
Authorization: Bearer YOUR_API_KEY
```

## Choose the right model

| Capability | `MiniMax-H3` | `MiniMax-H3-Max` |
| - | - | - |
| Resolution | `2K` / `768P`; default `2K` | `480P` / `768P` / `1080P`; default `768P` |
| Duration | 4–15 seconds | 5–15 seconds |
| Text-to-video | Supported | Supported |
| First / last frames | Supported | Supported |
| Middle frames | Supported | Not supported |
| Multimodal references | Images, video, and audio | Images, video, and audio |
| Input image charge | First 5 images are free | First 2 images are free; additional images are charged individually |
| Reference video charge | Based on input duration, at the same rate as output video of the same resolution | Based on input duration, at a separate rate |
| AIGC watermark | Supported | Supported at 480P / 768P; not supported at 1080P |

> [!WARNING]
>
> `MiniMax-H3-Max` does not support 2K and its output cannot be used as the source for [Regeneration](https://gccai.heqingsong.uk/en/api-reference/videos/minimax-h3/regeneration.md). Use `MiniMax-H3` when you need either capability.

## Generation modes

The request fields determine the mode automatically; do not send a `mode` field.

| Mode | Trigger | Behavior |
| - | - | - |
| Text-to-video (T2V) | Only `prompt` and common fields | Generates from text |
| Image-to-video (I2V) | `first_frame_image` / `last_frame_image`, or equivalent roles in `image_with_roles` | Controls the first frame, last frame, or both |
| Multimodal references (R2V) | `image_urls` / `video_urls` / `audio_urls`, or `reference_image` in `image_with_roles` | Generates using reference images, videos, and audio; also supported at 1080P |

> [!WARNING]
>
> First/last-frame fields cannot be combined with reference media. Reference audio must accompany at least one reference image or video. Invalid combinations return HTTP 400 synchronously; no task is created or charged.

## Request parameters

**model** `string` *required*

Fixed value: `MiniMax-H3-Max`

Model IDs are case-insensitive; `minimax-h3-max` is also accepted.

**prompt** `string` *required*

A non-empty description of the video. Required in every mode.

Maximum: `7000` characters.

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

Video duration in seconds.

* Integer from `5` to `15`
* Default: `5`
* 4 seconds is not supported

**resolution** `string` (default: 768P)

Output resolution: `480P`, `768P` (default), or `1080P`.

At `1080P`, omit both `watermark` and its alias `aigc_watermark`, even when the value is `false`.

> [!WARNING]
>
> `2K`, `1440P`, and `2048P` are not supported. Invalid values return HTTP 400 and are not silently downgraded.

**aspect\_ratio** `string`

Output aspect ratio. The aliases `size` and `ratio` are also accepted.

Text-to-video values: `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`.

* T2V without this field, or with `adaptive`: falls back to `16:9`
* I2V: determined by the input image; this field is ignored
* Multimodal references: optional; defaults to `adaptive`, or specify an explicit ratio

**first\_frame\_image** `string`

Public image URL used as the video's first frame.

**last\_frame\_image** `string`

Public image URL used as the video's last frame. It can be used alone or together with `first_frame_image`.

**image\_with\_roles** `object[]`

Role-based image array that can replace `first_frame_image`, `last_frame_image`, or `image_urls`.

**image\_with\_roles item**

**url** `string` *required*

Public image URL

**role** `string`

Supported roles:

* `first_frame`; aliases include `first` and `start`
* `last_frame`; aliases include `last`, `end_frame`, and `tail`
* `reference_image`: reference image; alias `reference`; an empty role is treated as a reference image

Up to one first frame and one last frame. Reference images in this array and `image_urls` together must not exceed `9`. Frame roles cannot be mixed with reference-image roles.

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

Public reference-image URL array. Together with reference images in `image_with_roles`, at most `9` images. All images are treated as references, never automatically as first/last frames. For first-frame control, use `first_frame_image` or the `first_frame` role.

**video\_urls** `string[]`

Public reference-video URL array; a single video can also use `video_url` (string). At most `3` clips, each `2`–`15` seconds, with a combined reference-video duration of at most `15` seconds.

Reference-video duration is read at submission for billing. If it cannot be read, HTTP 400 is returned synchronously; no task is created or charged.

**audio\_urls** `string[]`

Public reference-audio URL array; a single clip can also use `audio_url` (string). At most `3` clips, each `2`–`15` seconds, with a combined reference-audio duration of at most `15` seconds. Must accompany at least one reference image or video; audio alone is not supported.

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

Whether to add an AIGC watermark. Alias: `aigc_watermark`.

Watermarks are only supported at `480P` / `768P`. At `1080P`, omit both `watermark` and its alias `aigc_watermark`, even when the value is `false`.

**webhook** `string`

Receives a notification when the task reaches a successful or failed terminal state.

> [!NOTE]
>
> Use `webhook`, not MiniMax's `callback_url`. The gateway reserves `callback_url` for internal polling acceleration.

## Parameter constraints

The following invalid parameters or combinations return HTTP 400 before task creation and billing:

| Parameter / value | Reason |
| - | - |
| First/last frames combined with reference media | I2V and R2V are mutually exclusive |
| More than `9` reference images, or more than `3` reference videos or audio clips | Exceeds the media count limit |
| Reference audio alone | Requires a reference image or video |
| `resolution: "2K"` | Only `480P`, `768P`, and `1080P` are supported |
| `duration: 4` or a value above `15` | Only 5–15 seconds are supported |

Each reference video and audio clip must be 2–15 seconds. Video and audio totals are calculated separately, each at most 15 seconds. Trim overlong media before submission; it is not valid input.

> [!WARNING]
>
> At `1080P`, omit both `watermark` and its alias `aigc_watermark`, even when the value is `false`.

> [!TIP]
>
> For 2K, middle frames, or a 4-second video, use [MiniMax-H3](https://gccai.heqingsong.uk/en/api-reference/videos/minimax-h3/generation.md) and adjust the parameters accordingly.

## Input media limits

The total request body must not exceed 64 MB. Use public URLs for images, videos, and audio; do not use Base64.

### Images

| Item | Limit |
| - | - |
| Formats | JPG / JPEG / PNG / WEBP / HEIC / HEIF |
| Per file | ≤ 30 MB |
| Width and height | 256–5760 px |
| Aspect ratio (width / height) | 0.4–2.5 |
| Count | Up to 1 first frame, 1 last frame, and 9 reference images; frame images and reference images cannot be mixed |

### Reference videos

| Item | Limit |
| - | - |
| Formats | MP4 / MOV, H.264 / H.265 |
| Per file | ≤ 50 MB |
| Count | ≤ 3 |
| Per-clip duration | 2–15 s |
| Total duration | ≤ 15 s |
| Width and height | 256–5760 px |
| Aspect ratio (width / height) | 0.4–2.5 |
| Frame rate | 23.976–60 fps |

### Reference audio

| Item | Limit |
| - | - |
| Formats | WAV / MP3 |
| Per file | ≤ 15 MB |
| Count | ≤ 3 |
| Per-clip duration | 2–15 s |
| Total duration | ≤ 15 s |

Reference audio must accompany a reference image or video. Video and audio duration totals are calculated separately; each must not exceed 15 seconds.

Media that does not meet these requirements may fail during generation; failed tasks are refunded automatically.

## Examples

### First-frame image-to-video

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "prompt": "The camera slowly pushes in as steam rises and people move in the background.",
  "first_frame_image": "https://cdn.example.com/ramen.png",
  "duration": 5,
  "resolution": "480P"
}
```

### First-and-last-frame image-to-video

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "prompt": "The scene gradually transitions from morning to sunset.",
  "first_frame_image": "https://cdn.example.com/morning.png",
  "last_frame_image": "https://cdn.example.com/sunset.png",
  "duration": 8,
  "resolution": "768P"
}
```

### 1080P text-to-video

At `1080P`, omit both `watermark` and its alias `aigc_watermark`, even when the value is `false`.

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "prompt": "Sunset on the coast, waves gently washing the beach, a slow camera push-in, cinematic texture.",
  "duration": 5,
  "resolution": "1080P",
  "aspect_ratio": "16:9"
}
```

### Multimodal reference generation

Each reference video and audio clip must be 2–15 seconds. Video and audio totals are calculated separately, each at most 15 seconds. Trim overlong media before submission; it is not valid input.

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "prompt": "The character from the reference image runs through the scene from the reference video, following the rhythm of the reference audio.",
  "image_urls": [
    "https://cdn.example.com/role.png"
  ],
  "video_urls": [
    "https://cdn.example.com/scene.mp4"
  ],
  "audio_urls": [
    "https://cdn.example.com/beat.mp3"
  ],
  "duration": 6,
  "resolution": "1080P",
  "aspect_ratio": "16:9"
}
```

## Query a task

Submission returns a `task_id`. Poll [Task Status](https://gccai.heqingsong.uk/en/api-reference/tasks/status.md) every 5–10 seconds; use a client timeout of 15 minutes.

```bash theme={null}
curl https://gccai.heqingsong.uk/v1/tasks/task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ \
  --header 'Authorization: Bearer <token>'
```

| `status` | Meaning |
| - | - |
| `pending` | Submitted or queued |
| `processing` | Generating |
| `completed` | Video URL is in `result.videos[0].url` |
| `failed` | Check `error.message`; the task is refunded automatically |

> [!NOTE]
>
> Generated video URLs typically expire after about 24 hours. Download and store the result promptly.

## Pricing

Total cost includes generated video, additional input images, and reference video:

```text theme={null}
Total cost = generation rate per second × output duration
           + additional image rate × max(0, input image count − 2)
           + reference video rate per second × total reference video duration
```

First frames, last frames, and reference images are counted together. The first 2 images are free; additional images are charged individually. Total reference-video duration must not exceed 15 seconds.

| Item | Rate |
| - | - |
| 1080P video | Subject to model pricing |
| 768P video | Subject to model pricing |
| 480P video | Subject to model pricing |
| Input images | First 2 images are free; additional images are charged individually; Subject to model pricing |
| Reference videos | Charged per input second, subject to model pricing; varies with output resolution and is separate from the generation rate |
| Reference audio | **Free** |

| Example | Cost |
| - | - |
| 768P / 5s | 768P generation rate × 5 |
| 768P / 10s | 768P generation rate × 10 |
| 480P / 10s | 480P generation rate × 10 |
| 480P / 15s | 480P generation rate × 15 |
| 768P / 5s + Images × 3 | 768P generation rate × 5 + additional image rate × 1 |
| 480P / 10s + Reference videos (12s) | 480P generation rate × 10 + 480P reference video rate × 12 |
| 1080P / 5s + Images × 2 + Reference audio | 1080P generation rate × 5 |

All rates are subject to model pricing. In the 1080P example with 2 reference images and reference audio, the images and audio are free.

The estimated amount is reserved at submission. Failed tasks receive a full automatic refund; the task response's `cost` field is authoritative.

## Errors

| Scenario | Result |
| - | - |
| Empty or over-7000-character `prompt` | 400; no task |
| `duration` outside 5–15 | 400; no task |
| Unsupported `resolution` | 400; no task |
| First/last frames combined with reference media / Reference audio alone | 400; no task |
| More than `9` reference images, or more than `3` reference videos or audio clips | 400; no task |
| Cannot read reference-video duration | 400; no task |
| Invalid image role, or more than one image for a first/last-frame role | 400; no task |
| Insufficient balance | 402 |
| Content safety rejection | 422 |
| Rate limit | 429; retry with backoff |

Generation failures return `status = failed` with details in `error.message` and are refunded automatically.

## Response

**code** `integer`

Response status code; 200 on success

**data** `array`

Submission result containing the initial task status and task ID

**Array item**

**status** `string`

Initially `submitted`

**task\_id** `string`

Unique task identifier used to query progress and results


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