Hailuo API: MiniMax H3 Python Guide and 3 Video Modes Tested

The Hailuo API is MiniMax's video API, and its current model is MiniMax H3 (MiniMax-H3), the generation after Hailuo 01 and 02. Every call is asynchronous: create a task, poll it, download the MP4. On October 26, 2026, our 5-second 768P clips took 35 to 42 seconds in all three modes, and each came with sound.

Short answer

• Model: MiniMax-H3 on MiniMax's API, announced July 31, 2026 (release notes); minimax-h3 on OmniaKey, one id for all three task types (video docs).
• Set: resolution (required) "768P" or "2K", duration 4 to 15 whole seconds, aspect_ratio (video docs).
• Cost: $0.08 a second at 768P, $0.40 for 5 seconds, $0.13 at 2K, MiniMax's list price (pricing, checked October 26, 2026); OmniaKey's rate is on the model page.
• Time and sound: 35 to 42 seconds per clip, each with stereo sound; the V2 create reference lists no switch to turn the sound off (create reference).

Is there an official Hailuo API?

Yes. MiniMax runs it at platform.minimax.io, and the current model there is MiniMax H3, id MiniMax-H3 (models page, checked October 26, 2026).

MiniMax's announcement presents H3 as the generation after Hailuo 01 and Hailuo 02 (announcement). The older models are still in the API as MiniMax-Hailuo-2.3 and MiniMax-Hailuo-02 (V1 reference).

The name changes from page to page. MiniMax's docs say "MiniMax H3", the API's model description says "Hailuo-03" (create reference), and the Hailuo AI app, where the announcement sends people to try it, says "Hailuo 3.0" (app). "Hailuo 3" is not an official name.

You create a key under Account > API Keys, and billing is pay-as-you-go (API FAQ). MiniMax's video packages cover older models, not H3 (pricing).

MiniMax lists four H3 variants (create reference):

On MiniMax's own API, a call takes three steps (video guide):

• POST https://api.minimax.io/v2/video_generation returns a task_id (create reference).
• Poll GET /v2/query/video_generation/{task_id} until succeeded, then download content.url (query reference).
• Only tasks from the last 7 days can be queried, and MiniMax does not publish how long the download URL lasts (query reference).

V1 (Hailuo 2.3 and 02) takes the task ID as a ?task_id= query parameter instead of a path segment, so keep the two flows apart (V1 reference).

OmniaKey sells API access to MiniMax H3, so we ran these examples through it. The flow is the same: POST https://api.omniakey.com/v1/media/tasks with an Idempotency-Key header returns 202 and an id, and you poll GET /v1/media/tasks/{id} (media overview). The same flow runs Grok Imagine Video in our Grok Imagine Video API guide. Every price below is MiniMax's own list price.

Which parameters can you set?

• resolution is required; 1080P and 4K fail with 400 model_price_error (video docs), and V2 has no 1080P for H3 (create reference). We ran all three modes at 768P and did not test 2K.
• duration is 4 to 15 whole seconds (video docs); MiniMax-H3-Max starts at 5 and rejects 4 (create reference).
• aspect_ratio takes adaptive, 16:9, 9:16, 1:1, 4:3, 3:4 or 21:9 (video docs). On MiniMax's API, text to video needs a fixed ratio and image to video follows the shape of the image (create reference). We left the ratio out of our image-to-video run, and the clip kept the still's shape, 1376×768.
• input.media[] takes first_frame and an optional last_frame for image to video, or reference_image, reference_video and reference_audio for reference to video. The two kinds cannot be mixed, and an audio reference needs an image or video reference with it (video docs). Each entry is a type and a url, either a public HTTPS link or a data URI. OmniaKey caps the whole request at 1 MiB, Base64 included (media overview), so the script sends 1024-pixel JPEGs.
• The prompt is input.prompt (video docs), up to 7,000 characters (video guide). Describe the sound you want there too.

How do you call the Hailuo API from Python?

You need Python 3 and requests, with your key in an environment variable.

pip install requests
export OMNIAKEY_API_KEY="your-key"
python hailuo_h3.py t2v   # or i2v (needs bicycle.jpg) or r2v (needs robot.jpg)

The only argument is t2v, i2v or r2v; the runs that need an image read bicycle.jpg or robot.jpg from the same folder.

Here is the script we ran, unchanged:

import base64
import os
import sys
import time
import uuid

import requests

API = "https://api.omniakey.com/v1/media/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['OMNIAKEY_API_KEY']}"}

DRUMMER = (
    "A street drummer plays a fast rhythm on upturned plastic buckets on a rainy city sidewalk "
    "at night. Neon signs reflect in the puddles and a few people with umbrellas walk past "
    "behind him. The camera slowly pushes in from a medium shot to a close-up of his hands and "
    "drumsticks. Realistic, handheld documentary look, with the sound of rain and drumming."
)
BICYCLE = (
    "A gentle breeze moves the daisies in the basket and a few petals drift down to the "
    "cobblestones. The camera slowly pushes in toward the basket. The bicycle and the wall "
    "stay exactly as they are."
)
ROBOT = (
    "The small orange robot from the reference image waters potted plants on a sunny "
    "apartment balcony with a red watering can. Medium shot, slow sideways camera move, "
    "city rooftops in the background."
)


def data_uri(path):
    # A local JPEG sent inline. The whole request must stay under 1 MiB, so keep it small.
    with open(path, "rb") as f:
        return "data:image/jpeg;base64," + base64.b64encode(f.read()).decode()


def make_video(operation, prompt, parameters, media, out):
    task_input = {"prompt": prompt}
    if media:
        task_input["media"] = media

    # 1. Create the task. Reuse the same Idempotency-Key only when retrying this exact request.
    resp = requests.post(
        API,
        headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
        json={
            "model": "minimax-h3",
            "type": "video",
            "operation": operation,
            "input": task_input,
            "parameters": parameters,
        },
        timeout=60,
    )
    resp.raise_for_status()
    task = resp.json()
    print(operation, "task:", task["id"])

    # 2. Poll the same task. Slow is not failed: never resubmit, keep polling this id.
    deadline = time.time() + 15 * 60
    while task["status"] in ("queued", "processing"):
        if time.time() > deadline:
            raise SystemExit(f"still {task['status']}: poll {task['id']} again later")
        time.sleep(5)
        task = requests.get(f"{API}/{task['id']}", headers=HEADERS, timeout=30).json()
    if task["status"] != "succeeded":
        raise SystemExit(f"{operation} ended {task['status']}: {task.get('error')}")

    # 3. Download the clip now: the signed URL lasts about an hour.
    asset = task["assets"][0]
    with open(out, "wb") as f:
        f.write(requests.get(asset["url"], timeout=120).content)
    print("saved", out, asset["byte_size"], "bytes")


mode = sys.argv[1] if len(sys.argv) > 1 else "t2v"
if mode == "t2v":
    make_video(
        "text_to_video", DRUMMER,
        {"resolution": "768P", "duration": 5, "aspect_ratio": "16:9"},
        None, "drummer.mp4",
    )
elif mode == "i2v":
    make_video(
        "image_to_video", BICYCLE,
        {"resolution": "768P", "duration": 5},
        [{"type": "first_frame", "url": data_uri("bicycle.jpg")}], "bicycle.mp4",
    )
elif mode == "r2v":
    make_video(
        "reference_to_video", ROBOT,
        {"resolution": "768P", "duration": 5, "aspect_ratio": "16:9"},
        [{"type": "reference_image", "url": data_uri("robot.jpg")}], "robot.mp4",
    )

Its output on October 27, 2026:

$ python hailuo_h3.py t2v
text_to_video task: task_V5TXAJG7n3ny42imJNqgTXRL4L8PGStd
saved drummer.mp4 4612510 bytes
$ python hailuo_h3.py i2v
image_to_video task: task_c4m3wHmF79Cmq7ZhDrTnCyt8SmIaW1ls
saved bicycle.mp4 4705286 bytes
$ python hailuo_h3.py r2v
reference_to_video task: task_dqx1TYA7u0znN5PFTl9tbfdWgtbBUbKd
saved robot.mp4 5630121 bytes

Each run took 47 to 60 seconds from start to saved file.

Keep the task ID. A slow task has not failed, so poll the same ID again instead of resubmitting (media overview). The signed download URL lasts about an hour and the task record 24 hours, so save the file at once or poll again for a fresh URL. The download itself needs no API key.

What came back from the three modes

The three clips came from three tasks on October 26, 2026, with the script's exact request bodies.

Every clip was an MP4, H.264, 24 fps, 5.17 seconds, with stereo AAC audio at 32 kHz; usage said output_seconds: 5.

Text to video: the street drummer

The prompt is DRUMMER in the script.

What we saw:

• A wet city sidewalk at night, with red and blue neon reflected on the pavement, parked cars, and a drummer in a black hooded jacket bent over upturned blue buckets. The hood hides the face the whole time.
• The camera moves in from a wide view to a close-up of the hands, the moving sticks and the bucket tops, while a person with an umbrella walks past behind.
• The letters on the neon signs are not real words. The drum hits get stronger toward the end, but the rain is not distinct in the sound.

What to change: if you need a face, add "hood down, face visible"; if the rain must be heard, give it a sound sentence of its own.

Image to video: the first frame stays

The first frame is a still we made with Nano Banana 2.1; the prompt is BICYCLE and describes only the motion.

What we saw:

• The first frame matches the still: the same red bicycle, yellow plaster wall, shutters, potted plants and cobblestones.
• The camera pushes in until the basket of white daisies fills the frame, and the bicycle and the wall keep their shape the whole way.
• We did not see petals falling in the frames we checked. The sound is a slow solo piano melody, though the prompt never mentioned sound or music.

What to change: describe only the motion and the sound, since the still already sets the look, and make the still in the shape you want the clip to have.

Reference to video: one image keeps the character

The reference is one image of a small orange robot made with Nano Banana 2.1; the prompt is ROBOT.

What we saw:

• The same robot: orange rounded body, round blue glass eyes, a short antenna with a ball on top and a round disc on the side of the head, now on a sunny balcony with pots of flowers and herbs.
• It pours from a red watering can, the stream of water shows from about 1 second, and the camera drifts slightly to the side.
• The sound is running and splashing water that starts just before the stream appears, with no music.

What to change: the character needed no fix. To keep it the same across several clips, reuse the same reference image each time.

Sound: describe it, or H3 picks it

When the prompt said nothing about sound, H3 chose it: water for the robot, which fits the watering, and piano for the bicycle. Describe the sound you need in the prompt. The V2 create reference lists no switch to turn sound off (create reference), so for a silent clip, strip the track afterwards:

ffmpeg -i drummer.mp4 -an -c copy drummer-silent.mp4

That writes a copy with only the H.264 video, still 5.17 seconds long and not re-encoded.

What errors will you hit?

Errors come from OmniaKey's task API and, on a direct call, from MiniMax's.

• 400 missing_idempotency_key: No Idempotency-Key header. Add one.
• 409 idempotency_key_reused: Same key, new body. New key per task.
• 400 model_price_error: 1080P or 4K. Use 768P or 2K.
• 400 invalid_request: Bad body or parameter. Check the parameters.
• 403 model_not_allowed: Key lacks this model. Check key access.
• 503 no_available_channel: Model unavailable right now. Retry later.
• provider_submit_uncertain: Rejected at submission. Use input.prompt, check media.
• Task failed: Generation failed. Read error.

A failed or canceled task is refunded (media overview). On MiniMax's own API (error codes, checked October 26, 2026):

• MiniMax sends the matching HTTP status with each code, for example 401 with 1004 and 400 with 2013 (create reference).
• H3 on V2 allows 300 requests a minute and 30 tasks running at once (rate limits).

How much does the Hailuo API cost?

MiniMax bills H3 per second of output video, by variant and resolution (pricing page, checked October 26, 2026):

At those prices: 5 seconds at 768P is $0.40, 10 seconds at 2K is $1.30, and 15 seconds at 2K is $1.95.

• The first 5 input images per task are free (2 on Max), each extra image costs $0.04 on H3, and audio input is free. Input video is billed per second, and on Max an input second ($0.143 at 768P) costs more than an output second. For the same variant and resolution, all three task types cost the same.
• H3 is pay-as-you-go only, and MiniMax's video packages do not cover it. The per-second figures in the Hailuo AI app's plans are app credits, not API prices (app).
• MiniMax's China platform has its own price list in yuan, so do not convert one into the other (China pricing, checked October 26, 2026).
• On OmniaKey, a video task is charged per output second when it is created, and a failed or canceled task is refunded (media overview).

OmniaKey's current rate is on the MiniMax H3 model page; the request shape is in the video API docs.

Common questions

Is the Hailuo API free?

Not on MiniMax's own API: its pricing, quickstart and FAQ pages show no free trial or credit for H3 (checked October 26, 2026). The only free parts are the first 5 input images per task and audio input (pricing), and Hailuo AI app credits do not work as API credits.

What is the difference between Hailuo 2.3 and MiniMax H3?

Hailuo 2.3 runs on V1: 6 or 10 seconds, up to 1080P, billed per video, with MiniMax's list price at $0.28 for 6 seconds at 768P (pricing, V1 reference). H3 runs on V2: 4 to 15 seconds, 768P or 2K, billed per second, with stereo sound (create reference, models page). MiniMax still lists both (model FAQ).

What is MiniMax H3 Max?

It is a joint release from MiniMax and fal.ai, post-trained by fal.ai on H3 for speed (video guide). It makes 480P or 768P clips of 5 to 15 seconds, and extra.prompt_expansion_mode takes disabled, balanced (the default) or quality (create reference). MiniMax's pages disagree on whether it takes references: the video guide and the model FAQ list only text and image to video, while the create reference and the pricing page also list reference to video.

Can you run MiniMax H3 yourself?

Yes, outside some regions. The weights are on Hugging Face (MiniMaxAI/MiniMax-H3) and GitHub (MiniMax-AI/MiniMax-H3) under the MiniMax H3 Community License Agreement, a custom license (Hugging Face, GitHub). In the license revision reviewed on August 26, 2026, the US, EU, UK and South Korea are Excluded Territories that need a separate license (local deploy guide).

Update log

October 27, 2026: first version, with clips made on October 26, 2026.