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

# MiniMax Hailuo 3 Max API

> Generate AI videos with MiniMax Hailuo 3 Max at 480p or 768p. Text-to-video, first and last keyframes, dedicated reference-to-video endpoints, seed control and prompt expansion, with durations from 5 to 15 seconds.

<Card title="MiniMax Hailuo 3 Max integration" icon="video">
  MiniMax Hailuo 3 Max is fal's optimised Hailuo 3 build, adding seed control, prompt expansion and a safety checker, with reference-guided generation on its own endpoints.
</Card>

MiniMax Hailuo 3 Max is an AI video generation API that produces videos from a text `prompt`, from a first-frame `image` (optionally with a last-frame `image_end`), or from reference assets. Durations run from `5` to `15` seconds.

Unlike [Hailuo 3](/api-reference/video/minimax-h3/overview), reference-guided generation does **not** share the standard endpoints: it lives on the dedicated `-r2v-` endpoints, which the provider prices differently. Resolution is selected at generation time — **480p** or **768p** — and each endpoint has its own list and status endpoints.

### Key capabilities

* **Two endpoint families**: Standard generation (text and keyframes) and reference-to-video (`-r2v-`)
* **Seed control**: Provide a `seed` from `0` to `4294967295` to reproduce a result; `-1` selects a random seed
* **Prompt expansion**: `prompt_expansion_mode` picks the expander that rewrites your prompt before generation
* **Safety checker**: `enable_safety_checker` is on by default
* **First-to-last-frame transitions**: Provide both `image` and `image_end` to generate a transition
* **References on the r2v endpoints**: Up to **9** images, **3** videos and **3** audios, at most **12** files in total
* **Durations**: Any integer from `5` to `15` seconds (default `5`)
* **Async processing**: Webhook notification or polling for task completion

### Use cases

* **Reproducible iteration**: Fix the `seed` and vary one parameter at a time to compare results fairly
* **Prompt-light workflows**: Let `prompt_expansion_mode` enrich a short prompt instead of writing a long one
* **Character and style transfer**: Use the r2v endpoints with reference images to carry a subject across shots
* **Motion reuse**: Give a reference video on an r2v endpoint and describe the new scene
* **Fast previews**: Generate at 480p to iterate, then re-run the same seed at 768p

### Generation modes

| Mode | Endpoint family | Required input | Optional input |
| - | - | - | - |
| **Text-to-Video** | `minimax-h3-max-*` | `prompt` | `aspect_ratio`, `duration`, `seed`, `prompt_expansion_mode`, `enable_safety_checker` |
| **Image-to-Video** | `minimax-h3-max-*` | `prompt` + `image` | `image_end`, `duration`, `seed`, `prompt_expansion_mode`, `enable_safety_checker` |
| **Reference-to-Video** | `minimax-h3-max-r2v-*` | `prompt` + at least one of `reference_images` / `reference_videos` | `reference_audios`, `aspect_ratio`, `duration`, `seed`, `prompt_expansion_mode`, `enable_safety_checker` |

<Warning>
  **On the r2v endpoints, reference videos are billed.** Their combined duration is added to the output duration, capped at 15 seconds. A 5-second generation with one 10-second reference video is billed as 15 seconds, not 5. Reference images and reference audios add nothing to the price.
</Warning>

## API Operations

<div className="my-11">
  <Columns cols={2}>
    <Card title="POST /v1/ai/video/minimax-h3-max-480p" icon="video" href="/api-reference/video/minimax-h3-max/generate-480p">
      Generate a 480p video from text or keyframes
    </Card>

    <Card title="POST /v1/ai/video/minimax-h3-max-768p" icon="video" href="/api-reference/video/minimax-h3-max/generate-768p">
      Generate a 768p video from text or keyframes
    </Card>

    <Card title="POST /v1/ai/video/minimax-h3-max-r2v-480p" icon="images" href="/api-reference/video/minimax-h3-max/generate-r2v-480p">
      Generate a 480p video from references
    </Card>

    <Card title="POST /v1/ai/video/minimax-h3-max-r2v-768p" icon="images" href="/api-reference/video/minimax-h3-max/generate-r2v-768p">
      Generate a 768p video from references
    </Card>

    <Card title="GET /v1/ai/video/minimax-h3-max-480p/{task-id}" icon="magnifying-glass" href="/api-reference/video/minimax-h3-max/task-by-id-480p">
      Get a 480p task by ID
    </Card>

    <Card title="GET /v1/ai/video/minimax-h3-max-r2v-768p/{task-id}" icon="magnifying-glass" href="/api-reference/video/minimax-h3-max/task-by-id-r2v-768p">
      Get a 768p r2v task by ID
    </Card>
  </Columns>
</div>

### Endpoint structure

Each generate endpoint has its own list and status endpoints. A task created on one endpoint is only visible on that endpoint's pair.

| Operation | Endpoint |
| - | - |
| **Generate 480p** | `POST /v1/ai/video/minimax-h3-max-480p` |
| **Generate 768p** | `POST /v1/ai/video/minimax-h3-max-768p` |
| **Generate 480p from references** | `POST /v1/ai/video/minimax-h3-max-r2v-480p` |
| **Generate 768p from references** | `POST /v1/ai/video/minimax-h3-max-r2v-768p` |
| **List tasks** | `GET /v1/ai/video/minimax-h3-max-480p` (and the matching `-768p`, `-r2v-480p`, `-r2v-768p`) |
| **Get task** | `GET /v1/ai/video/minimax-h3-max-480p/{task-id}` (and the matching `-768p`, `-r2v-480p`, `-r2v-768p`) |

### Parameters — standard endpoints

Used by `minimax-h3-max-480p` and `minimax-h3-max-768p`.

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `prompt` | `string` | Yes | - | Text description of the video. Up to 50000 characters |
| `image` | `string` | No | - | First-frame image, as a public URL or Base64 string. Its aspect ratio determines the output aspect ratio |
| `image_end` | `string` | No | - | Last-frame image, as a public URL or Base64 string. Requires `image` |
| `duration` | `integer` | No | `5` | Video length in seconds: any integer from `5` to `15` |
| `aspect_ratio` | `string` | No | `widescreen_16_9` | Output ratio: `film_horizontal_21_9`, `widescreen_16_9`, `classic_4_3`, `square_1_1`, `traditional_3_4`, `social_story_9_16`. Only applies to text-only generations |
| `prompt_expansion_mode` | `string` | No | `balanced` | Prompt expander: `disabled`, `fast`, `balanced`, `quality` |
| `enable_safety_checker` | `boolean` | No | `true` | Enables the provider's content safety filtering |
| `seed` | `integer` | No | `-1` | Random seed for reproducible results (`0` to `4294967295`). Use `-1` for a random seed |
| `webhook_url` | `string` | No | - | URL for async status notifications when the task completes |

### Parameters — reference-to-video endpoints

Used by `minimax-h3-max-r2v-480p` and `minimax-h3-max-r2v-768p`. These endpoints take no `image` or `image_end`.

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `prompt` | `string` | Yes | - | Text description of the video. Cite references as `@Image1`, `@Video1`, `@Audio1`, matching their 1-indexed array order. Up to 50000 characters |
| `reference_images` | `array` | No | - | Up to **9** reference images (URL or Base64). Cite as `@Image1`…`@Image9` |
| `reference_videos` | `array` | No | - | Up to **3** reference videos (public HTTPS URL or a `upl_vid_...` upload file ID). Cite as `@Video1`…`@Video3`. 2–15 s each, combined duration at most 15 s. **Billed** |
| `reference_audios` | `array` | No | - | Up to **3** reference audios (public HTTPS URL). Cite as `@Audio1`…`@Audio3`. 2–15 s each, combined duration at most 15 s. Requires at least one reference image or reference video alongside it |
| `duration` | `integer` | No | `5` | Video length in seconds: any integer from `5` to `15` |
| `aspect_ratio` | `string` | No | `adaptive` | Output ratio: `adaptive`, `film_horizontal_21_9`, `widescreen_16_9`, `classic_4_3`, `square_1_1`, `traditional_3_4`, `social_story_9_16` |
| `prompt_expansion_mode` | `string` | No | `balanced` | Prompt expander: `disabled`, `fast`, `balanced`, `quality` |
| `enable_safety_checker` | `boolean` | No | `true` | Enables the provider's content safety filtering |
| `seed` | `integer` | No | `-1` | Random seed for reproducible results (`0` to `4294967295`). Use `-1` for a random seed |
| `webhook_url` | `string` | No | - | URL for async status notifications when the task completes |

At least one `reference_images` or `reference_videos` entry is required, and the three reference arrays must add up to at most **12** files in total.

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="What is MiniMax Hailuo 3 Max and how does it work?">
    Hailuo 3 Max is fal's optimised build of MiniMax Hailuo 3. You submit a text `prompt` — optionally with keyframes, or with references on the `-r2v-` endpoints — and receive a task ID immediately. Poll the GET status endpoint or supply a `webhook_url` to be notified when the task completes, then download the MP4 from the returned URL.
  </Accordion>

  <Accordion title="Why are there separate r2v endpoints?">
    The provider treats reference-guided generation as a different model with its own pricing, so it gets its own endpoints rather than extra fields on the standard ones. Use `minimax-h3-max-r2v-480p` or `minimax-h3-max-r2v-768p` when you want to steer generation with reference images, videos or audios; use the standard endpoints for text-to-video and keyframe image-to-video.
  </Accordion>

  <Accordion title="What is the difference between Hailuo 3 Max and Hailuo 3?">
    [Hailuo 3](/api-reference/video/minimax-h3/overview) is served by MiniMax directly: it accepts references and keyframes on the same endpoints, runs at 768p and 2K, and goes down to `4`-second clips. Hailuo 3 Max is fal's build: it adds `seed`, `prompt_expansion_mode` and `enable_safety_checker`, runs at 480p and 768p, starts at `5` seconds, and splits reference generation onto the `-r2v-` endpoints.
  </Accordion>

  <Accordion title="Why does Hailuo 3 Max accept 50,000 characters when Hailuo 3 accepts 7,000?">
    Because they are served by different providers, and each enforces its own limit. Hailuo 3 Max goes through fal, which accepts up to 50,000 characters. [Hailuo 3](/api-reference/video/minimax-h3/overview) goes to MiniMax directly, which rejects anything past 7,000 with `content[0].text too long (2013)`. Neither cap is set by this API.

    In practice the ceiling is well above the useful range either way: a prompt of a few hundred words is what the model actually follows, and `prompt_expansion_mode` is there to enrich a short prompt rather than to reward a long one.
  </Accordion>

  <Accordion title="What does prompt_expansion_mode do?">
    It picks which prompt expander runs before generation. `disabled` sends your prompt verbatim; `fast`, `balanced` (the default) and `quality` trade latency for richer rewriting. Use `disabled` when your prompt is already precise and you do not want it reinterpreted.
  </Accordion>

  <Accordion title="Can I reproduce the same video?">
    Yes. Provide a fixed `seed` (from `0` to `4294967295`) together with the same prompt and parameters. Use `-1` (the default) for a random seed on each request. Note that a non-`disabled` `prompt_expansion_mode` rewrites the prompt before generation, so pin that too when you need strict reproducibility.
  </Accordion>

  <Accordion title="How are reference videos billed on the r2v endpoints?">
    The combined duration of your `reference_videos` is added to the output duration, capped at 15 seconds, and the total is what you are charged. A 5-second generation with one 10-second reference video is billed as 15 seconds. Reference images and reference audios are free.
  </Accordion>

  <Accordion title="Can I check a task on a different endpoint than the one that created it?">
    No. Each endpoint has its own list and status endpoints, and a task is only visible on the pair that matches the endpoint it was created with. A task created on `minimax-h3-max-r2v-768p` is read from `GET /v1/ai/video/minimax-h3-max-r2v-768p/{task-id}`.
  </Accordion>

  <Accordion title="How long does generation take and how do I get the result?">
    Poll the GET task endpoint or provide a `webhook_url` to be notified on completion. The result MP4 is delivered via a signed URL that stays valid for **30 minutes** — download it promptly, or re-request the task before the link expires.
  </Accordion>

  <Accordion title="What are the rate limits for Hailuo 3 Max?">
    Rate limits depend on your subscription tier. See the [Rate Limits](/ratelimits) page for current limits by plan.
  </Accordion>

  <Accordion title="How much does Hailuo 3 Max cost?">
    Pricing varies by resolution and billed duration, and on the r2v endpoints reference videos add their combined duration to that total. See the [Pricing](/pricing) page for current rates and credit costs.
  </Accordion>
</AccordionGroup>

## Best practices

* **Pick the right family**: Standard endpoints for text and keyframes, `-r2v-` endpoints for references — sending references to a standard endpoint will not work
* **Iterate at 480p**: Fix the `seed`, settle the prompt at 480p, then re-run the same seed at 768p for the final take
* **Pin the expander when comparing**: Set `prompt_expansion_mode` to `disabled` while A/B-testing prompts, so you are comparing your words and not the expander's
* **Keep reference videos short**: On r2v endpoints their duration is added to your bill, so trim them to the segment you need
* **Cite every reference**: A reference the prompt never mentions still counts toward the 12-file total, and video references still cost
* **Production integration**: Use webhooks instead of polling for scalable applications
* **Result retrieval**: Download the output promptly — the delivery URL is valid for 30 minutes

## Related APIs

* **[MiniMax Hailuo 3](/api-reference/video/minimax-h3/overview)**: MiniMax's own build, at 768p and 2K, with mixed references on the same endpoints
* **[MiniMax Hailuo 2.3](/api-reference/image-to-video/minimax-hailuo-2-3-768p/post-minimax-hailuo-2-3-768p)**: The previous Hailuo generation, at 768p and 1080p
* **[Seedance 2.0 Pro](/api-reference/video/seedance-2-pro/overview)**: Alternative high-quality video model with native audio


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