Skip to main content

MiniMax Hailuo 3 Max integration

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.
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, 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

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.

​
API Operations

POST /v1/ai/video/minimax-h3-max-480p

Generate a 480p video from text or keyframes

POST /v1/ai/video/minimax-h3-max-768p

Generate a 768p video from text or keyframes

POST /v1/ai/video/minimax-h3-max-r2v-480p

Generate a 480p video from references

POST /v1/ai/video/minimax-h3-max-r2v-768p

Generate a 768p video from references

GET /v1/ai/video/minimax-h3-max-480p/{task-id}

Get a 480p task by ID

GET /v1/ai/video/minimax-h3-max-r2v-768p/{task-id}

Get a 768p r2v task by ID

​
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.

​
Parameters — standard endpoints

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

​
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. 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

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.
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.
Hailuo 3 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.
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 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.
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.
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.
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.
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}.
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.
Rate limits depend on your subscription tier. See the Rate Limits page for current limits by plan.
Pricing varies by resolution and billed duration, and on the r2v endpoints reference videos add their combined duration to that total. See the Pricing page for current rates and credit costs.

​
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