Call the Hailuo 3 Max API With an API Key
How to call the Hailuo 3 Max API with an API key: the request, polling and download, the Max-only limits, what sets the cost of one video, and Max vs Hailuo 3.
By OceanToken Team

Editor's note: Hailuo 3 Max sounds like the top tier of Hailuo 3. MiniMax positions it the other way: it is the fast-generation variant, with lower resolutions than standard Hailuo 3. That one fact changes how you should use it. Treat Max as your drafting and iteration model, and save standard Hailuo 3 for the render you deliver.
Short answer: To call the Hailuo 3 Max API with an API key, send POST https://api.oceantoken.ai/v1/videos with "model": "minimax/hailuo-3-max", a prompt, a duration of 5 to 15 seconds and a resolution of 480p or 768p, then poll and download. It is billed per second of video; see the current rate on /hailuo-api.
01 · What Hailuo 3 Max is, and how it differs from Hailuo 3
MiniMax's video generation API reference describes MiniMax-H3 as the high-quality creation model and MiniMax-H3-Max as the fast generation variant. The limits follow from that positioning.
Hailuo 3 Max (minimax/hailuo-3-max) |
Hailuo 3 (minimax/hailuo-3) |
|
|---|---|---|
| Positioning (MiniMax) | Fast generation | High-quality creation |
| Resolution | 480p, 768p | 2K |
| Clip length | 5 to 15 s | 5 to 15 s |
| Aspect ratio | 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, adaptive | Same list |
| First and last frame | Up to 2 frames | Up to 2 frames |
| References | Up to 9 images, 3 videos, 3 audio | Up to 9 images, 3 videos, 3 audio |
generate_audio listed |
No | Yes |
The OceanToken columns come from each model's API reference, checked November 13, 2026. Two rows need a comment. MiniMax lists 768P as well as 2K for standard H3, but the OceanToken Hailuo 3 reference lists only 2K, so on this platform the choice is effectively "Max for 480p and 768p, Hailuo 3 for 2K." And MiniMax's H3 launch post describes native stereo sound for H3; the Max reference does not list a sound switch, so if your clip needs generated sound, start on Hailuo 3.
02 · Call Hailuo 3 Max with your API key
Create a key in the console, export it as OCEANTOKEN_API_KEY, and send one request. This is the shortest version that runs:
curl https://api.oceantoken.ai/v1/videos \
-H "Authorization: Bearer $OCEANTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: teaser-draft-001" \
-d '{"model": "minimax/hailuo-3-max", "prompt": "A paper lantern drifts up over a night market, slow tilt up", "duration": 6, "resolution": "768p", "aspect_ratio": "16:9"}'
The response carries an id and status: "queued". Poll GET https://api.oceantoken.ai/v1/videos/{id} every 10 to 20 seconds while the status is queued or in_progress. When it reads completed, download the MP4 from GET /v1/videos/{id}/content or the content_url field, and do it within 24 hours, when the link expires. If it reads failed, the error.code tells you why. Our Hailuo async flow in Python has a complete polling loop with retries, so we will not repeat it here.
The Idempotency-Key header is worth the extra line. If your create call times out and you retry with the same key, you get the existing job back instead of a second, separately charged one.

03 · Hailuo 3 Max parameters
| Parameter | Values | What it does |
|---|---|---|
model |
minimax/hailuo-3-max |
Required |
prompt |
Text | Required; describes the clip |
duration |
5 to 15, default 5 | Seconds; seconds is also accepted |
resolution |
480p, 768p |
Lower is faster and cheaper |
aspect_ratio |
21:9, 16:9, 4:3, 1:1, 3:4, 9:16, adaptive |
adaptive follows the first frame |
frame_images |
Up to 2 | First frame, last frame, or both |
input_references |
Up to 9 images, 3 videos, 3 audio | Reference media by URL |
Three behaviors catch people out. First, 4 seconds is not a valid Max duration even though standard H3 accepts it at MiniMax; ask for 4 and the API returns 400 invalid_request before any job starts.
Second, MiniMax's own API offers a prompt_expansion_mode setting for Max, but the OceanToken reference does not list it, and fields a model does not take are removed before the request reaches it (they show up in the x-oceantoken-dropped-params response header). MiniMax's docs say an omitted setting means balanced expansion, so here you cannot switch expansion off or to quality. Write the prompt you want and expect it may still be expanded.
Third, MiniMax states that frame inputs and reference inputs cannot be mixed in one request, so pick frame_images or input_references, not both.
If you are not sure what a model accepts today, GET https://api.oceantoken.ai/oceantoken/video/model-spec?model=minimax/hailuo-3-max returns its durations, resolutions, aspect ratios and input limits.
04 · What one Hailuo 3 Max video costs
Hailuo 3 Max is listed per second of video on the Hailuo price page, and the model page adds that billing is per video token, so aspect ratio and frame rate change the count; its per-second figures assume 16:9 at 24 fps. For the numbers, see the current rate on /hailuo-api.
So the cost of one video comes down to the settings you send:
| Setting | Effect on the charge for one video |
|---|---|
duration |
The main driver: more seconds, more cost |
resolution |
480p costs less than 768p |
aspect_ratio |
Changes the token count behind the per-second figure |
| Failed job | Not charged; the hold is released |
| Insufficient balance | The create call is refused with a 400 and no job starts |
The video guide describes the mechanics: the estimated cost is held against your balance when the job is created, the actual cost is charged when it finishes, and each job's charge appears on the console's Logs page. A request with an unsupported value is rejected before anything runs, so a typo costs nothing. For the failures that do happen, our Hailuo failure modes guide maps each error code to a fix.
05 · When to use Max, and when Hailuo 3

| Your job | Use | Why |
|---|---|---|
| Testing prompts, camera moves, first frames | minimax/hailuo-3-max at 480p |
Fast variant, lowest resolution |
| Social clip where 768p is enough | minimax/hailuo-3-max at 768p |
Max's top resolution; fine when 768p is the delivery size |
| Final hero render | minimax/hailuo-3 |
2K on this platform |
| Clip that needs generated sound | minimax/hailuo-3 |
Only Hailuo 3 lists generate_audio |
| Transition between two fixed frames | Either, drafted on Max | Both take first and last frames |
A simple loop works well: iterate on Max at 480p until the motion and framing are right, then send the same prompt and frames to Hailuo 3 for the 2K version. The models are related but not identical, so expect the final render to differ in detail; lock composition with a first frame if it has to match. If you are weighing Max against another family entirely, the Seedance 2.5 vs Hailuo 3 Max comparison lays out both.
How to test this on your workload
We have not run these prompts for this article. Before you commit Max to a pipeline, check it on your own jobs:
- Take five real prompts and run each on Max at 480p and at 768p, same duration.
- Note time from create to
completed, and the charge on the Logs page for each job. - Send the best two to Hailuo 3 and compare whether the 2K render keeps the framing you approved.
- Confirm whether Max clips come back with or without sound, since its reference lists no sound switch.
- Try one request with a first frame and one with references, and check the dropped-params header on both.
Our take: Use Hailuo 3 Max as a drafting model, not a premium tier. Its job is to make iteration quick at 480p and 768p; the 2K delivery render and any clip that needs generated sound belong on standard Hailuo 3. Write complete prompts: you cannot choose MiniMax's expansion mode here, so its default applies.
Running it on OceanToken
On OceanToken, Hailuo 3 Max and Hailuo 3 share one key, one base URL (https://api.oceantoken.ai/v1) and one video endpoint, so moving a prompt from draft to final is a change from minimax/hailuo-3-max to minimax/hailuo-3. The API is OpenAI-compatible, usage comes out of one prepaid balance with no subscription, and failed video jobs are not charged. See the current rate on /hailuo-api and the Hailuo 3 model page.
FAQ
Is Hailuo 3 Max better than Hailuo 3? No, it is faster. MiniMax positions Max as the fast generation variant; on this platform it outputs 480p or 768p, while Hailuo 3 outputs 2K.
How is Hailuo 3 Max billed? Per second of video, counted in video tokens, so duration, resolution and aspect ratio set the charge. The rate is on /hailuo-api.
What durations does Hailuo 3 Max accept? Whole seconds from 5 to 15. A 4-second request is rejected before it runs.
Am I charged if a Hailuo 3 Max job fails? No. A failed job is not charged and its hold is released.
Can I use a first frame and reference images together? MiniMax says frame and reference inputs cannot be mixed in one request, so use one or the other.
Sources
- OceanToken docs: minimax/hailuo-3-max (checked 2026-11-13)
- OceanToken docs: minimax/hailuo-3 (checked 2026-11-13)
- OceanToken docs: Video guide (checked 2026-11-13)
- OceanToken: Hailuo 3 Max model page (checked 2026-11-13)
- OceanToken: Hailuo API pricing (checked 2026-11-13)
- MiniMax API docs: Create video generation task (checked 2026-11-13)
- MiniMax: MiniMax H3 launch post (checked 2026-11-13)
Get your OceanToken API key
- Create an OceanToken account and an API key.
- Copy the snippet below, paste your key, and run it.
- Check the current rate on /hailuo-api.
curl https://api.oceantoken.ai/v1/videos \
-H "Authorization: Bearer $OCEANTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "minimax/hailuo-3-max", "prompt": "A paper lantern drifts up over a night market, slow tilt up", "duration": 6, "resolution": "480p", "aspect_ratio": "16:9"}'
More from the blog
A Unified API for Chat, Image and Video
Building on a unified API for chat, image and video: sync vs async calls, billing units, retries, timeouts and storage, with three calls and a launch checklist.
Kimi K3 API International Access Guide
Use the Kimi K3 API internationally: sign up with email, pay by card, create one key and call moonshotai/kimi-k3 with an OpenAI SDK. Steps, code and checks.
Call Tencent Hy3 With the OpenAI SDK
Call Tencent Hy3 with the OpenAI SDK outside China: base URL, model id, streaming, tool calls, reasoning_effort values, Hy3 vs Hy3 preview, and token billing.