> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/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
**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](/en/api-reference/videos/minimax-h3/generation).
```bash cURL theme={null}
curl --request POST \
--url https://api.apimart.ai/v1/videos/generations \
--header 'Authorization: Bearer ' \
--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://api.apimart.ai/v1/videos/generations",
headers={
"Authorization": "Bearer ",
"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://api.apimart.ai/v1/videos/generations", {
method: "POST",
headers: {
Authorization: "Bearer ",
"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
All endpoints require Bearer Token authentication. Get your key from the [API Key page](https://apimart.ai/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 |
`MiniMax-H3-Max` does not support 2K and its output cannot be used as the source for [Regeneration](/en/api-reference/videos/minimax-h3/regeneration). 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 |
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
Fixed value: `MiniMax-H3-Max`
Model IDs are case-insensitive; `minimax-h3-max` is also accepted.
A non-empty description of the video. Required in every mode.
Maximum: `7000` characters.
Video duration in seconds.
* Integer from `5` to `15`
* Default: `5`
* 4 seconds is not supported
Output resolution: `480P`, `768P` (default), or `1080P`.
At `1080P`, omit both `watermark` and its alias `aigc_watermark`, even when the value is `false`.
`2K`, `1440P`, and `2048P` are not supported. Invalid values return HTTP 400 and are not silently downgraded.
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
Public image URL used as the video's first frame.
Public image URL used as the video's last frame. It can be used alone or together with `first_frame_image`.
Role-based image array that can replace `first_frame_image`, `last_frame_image`, or `image_urls`.
Public image URL
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.
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.
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.
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.
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`.
Receives a notification when the task reaches a successful or failed terminal state.
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.
At `1080P`, omit both `watermark` and its alias `aigc_watermark`, even when the value is `false`.
For 2K, middle frames, or a 4-second video, use [MiniMax-H3](/en/api-reference/videos/minimax-h3/generation) 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](/en/api-reference/tasks/status) every 5–10 seconds; use a client timeout of 15 minutes.
```bash theme={null}
curl https://api.apimart.ai/v1/tasks/task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ \
--header 'Authorization: Bearer '
```
| `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 |
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
Response status code; 200 on success
Submission result containing the initial task status and task ID
Initially `submitted`
Unique task identifier used to query progress and results
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.