Skip to contentOceanToken

6 min read

Hailuo API Python: Create, Poll, Download

Run the Hailuo API in Python: create a task, poll its status, fetch the file before the 1-hour link expires, and handle MiniMax error codes and callbacks.

By OceanToken Team

Hailuo API Python: Create, Poll, Download

Editor's note: A video API that looks flaky is often a polling or download bug, not a model bug. Hailuo is a job queue: you submit, you wait, you collect. Treat it that way from day one. Store the id, poll gently, download once into your own bucket, and only then tell your user the clip is ready. MiniMax's download links expire in an hour, so "later" is not a plan.

Short answer: With the Hailuo API in Python, you create a task, get a task_id, poll the query endpoint until the status is Success or Fail, then exchange the file_id for a download URL that is valid for one hour. On OceanToken, the OpenAI SDK's videos.create_and_poll and videos.download_content wrap the same steps.

The native MiniMax flow in three calls

MiniMax's API reference splits the work across three endpoints on https://api.minimax.io. Each step hands you the id the next one needs.

Step Call You get back
Create POST /v1/video_generation task_id
Poll GET /v1/query/video_generation?task_id=... status, and file_id on success
Download GET /v1/files/retrieve?file_id=... download_url, valid for 1 hour

The query endpoint returns one of five statuses: Preparing, Queueing, Processing, Success or Fail. On success it also returns the file_id and the video's width and height.

One version note before you copy a model name. On 2026-11-06 the create endpoint's model list had MiniMax-Hailuo-2.3, MiniMax-Hailuo-02 and two older T2V models, but no H3. For Hailuo 2.3, a 6-second clip comes in 768P or 1080P, a 10-second clip in 768P only, and the prompt can be up to 2,000 characters. If you need H3, the Hailuo 3 model page lists minimax/hailuo-3 with native 768p and 2K output and text, image, video and audio inputs.

Hailuo API in plain Python: create, poll, download

This version uses requests against MiniMax directly. It follows the documented fields; we have not run it against a live MiniMax account, so test it with one clip first.

import os, time, requests

BASE = "https://api.minimax.io/v1"
H = {"Authorization": f"Bearer {os.environ['MINIMAX_API_KEY']}"}

def create(prompt):
    r = requests.post(f"{BASE}/video_generation", headers=H, json={
        "model": "MiniMax-Hailuo-2.3", "prompt": prompt, "duration": 6, "resolution": "768P"})
    body = r.json()
    if body["base_resp"]["status_code"] != 0:
        raise RuntimeError(body["base_resp"])
    return body["task_id"]

def wait(task_id, timeout=900):
    t0, delay = time.time(), 10
    while time.time() - t0 < timeout:
        q = requests.get(f"{BASE}/query/video_generation", headers=H,
                         params={"task_id": task_id}).json()
        if q["status"] == "Success":
            return q["file_id"]
        if q["status"] == "Fail":
            raise RuntimeError(q["base_resp"])
        time.sleep(delay)
        delay = min(delay * 1.5, 30)
    raise TimeoutError(task_id)

def download(file_id, path):
    f = requests.get(f"{BASE}/files/retrieve", headers=H,
                     params={"file_id": int(file_id)}).json()
    url = f["file"]["download_url"]
    with open(path, "wb") as out:
        out.write(requests.get(url).content)

The 10-second start and 30-second ceiling are our choice, not MiniMax's. The query page does not give a polling interval, and most clips take long enough that polling every second only wastes your rate limit.

Three pitfalls in the MiniMax docs

The status casing changes. The query endpoint uses Success and Fail. If you pass a callback_url when creating the task, MiniMax's callback updates use lowercase processing, success and failed. A worker that handles both paths needs to normalize the string, or it will wait forever on a job that already finished.

The file_id type changes too. MiniMax's OpenAPI spec types file_id as a string in the query response and as an integer in the retrieve call. That is why the code above casts it with int().

The link expires in an hour. The download page says download_url is "valid for 1 hour." Download the file and copy it to your own storage in the same job. If a user comes back the next day, serve your copy, not MiniMax's link.

Callbacks have one more rule. MiniMax first sends a POST with a challenge field, and your server must echo it back within 3 seconds before any status updates arrive. If your webhook sits behind a slow cold start, that check can fail.

Error codes to handle in the worker

MiniMax returns errors in base_resp.status_code. These are the ones its reference lists for the create, query and retrieve calls, and what we would do with each.

Code Meaning What to do
1002 Rate limit Back off and retry later
1004 / 2049 Auth failed / invalid key Stop and alert; retrying will not help
1008 Insufficient balance Stop the queue and top up
1026 Sensitive input Do not auto-retry; ask the user to change the prompt
1027 Sensitive output Retry once at most, then show a clear message
2013 Invalid parameters Fix the request; check duration and resolution pairs

The same flow with the OpenAI SDK

If you would rather not manage three endpoints, an OpenAI-compatible route can wrap create, poll and download in the SDK's video helpers. The example below follows the one on /hailuo-api; the base URL and model ids are under "Running it on OceanToken" below.

Diagram: Hailuo async job in a web app

from openai import OpenAI

client = OpenAI(base_url="https://api.oceantoken.ai/v1", api_key="YOUR_OCEANTOKEN_KEY")

video = client.videos.create_and_poll(
    model="minimax/hailuo-3",
    prompt="Medium close-up, slow dolly in. A barista pours latte art, steam rising, warm cafe light.",
)
if video.status == "completed":
    client.videos.download_content(video.id).write_to_file("latte.mp4")
else:
    print("not completed:", video.status, video)

create_and_poll blocks until the job ends, which is fine in a script and wrong in a web request. In an app, create the job, save video.id with the user and prompt, and let a worker poll with client.videos.retrieve(video.id). The video guide  for this route lists the statuses as queued, in_progress, then completed or failed, and suggests polling every 10 to 20 seconds; how long a clip takes depends on its length and the queue. Its content_url appears only after completion and is valid for 24 hours, longer than MiniMax's one-hour link, but still copy the file to your own storage. Check the Hailuo 3 model page for supported resolutions and inputs before you build on a spec.

Our take: Use create_and_poll in scripts and a queue plus worker in apps. Whichever route you pick, add an idempotency key of your own so a double click does not start two paid jobs, and copy every MP4 to your storage the moment it exists.

How to test this on your workload

  1. Submit one short prompt and log every status you see, with timestamps.
  2. Note the time from create to Success for 6-second and 10-second clips.
  3. Force a failure (an invalid resolution for the duration) and confirm your worker stops instead of looping.
  4. Wait more than an hour, then try the old download link, so you know what your app sees when it expires.
  5. Run ten jobs at once and check whether you hit code 1002.

Running it on OceanToken

OceanToken's base URL is https://api.oceantoken.ai/v1, and the model ids are minimax/hailuo-3, minimax/hailuo-3-max and minimax/hailuo-2.3 (listed on /hailuo-api on 2026-11-06). See the current rate on /hailuo-api.

The advantages the page states are practical ones for a video worker. One API key and one prepaid balance cover every leading model, so the same worker can call Seedance or Wan by changing the model id. The API is OpenAI-compatible, so you change the base URL and key and keep your code. Billing is prepaid with no subscription, and each API key can have its own spending limit, which lets you give staging and production separate caps.

FAQ

Is H3 on MiniMax's own API? On 2026-11-06 the create endpoint's model list showed Hailuo 2.3 and 02, not H3. OceanToken lists minimax/hailuo-3.

How often should I poll? MiniMax does not say. Start at 10 seconds and back off to 30.

How long is the download link valid? One hour, per MiniMax's download docs. Copy the file right away.

Can I get a webhook instead of polling? On MiniMax, yes: pass callback_url and echo the challenge within 3 seconds.

Why does my worker never see Success? If it reads callbacks, the status is lowercase success. Normalize before comparing.

Sources

  1. MiniMax: Create video generation task (text to video)  (checked 2026-11-06)
  2. MiniMax: Query video generation task  (checked 2026-11-06)
  3. MiniMax: Download the video file  (checked 2026-11-06)
  4. MiniMax: Retrieve file  (checked 2026-11-06)
  5. OceanToken Hailuo API page (checked 2026-11-06)
  6. OceanToken docs: Video guide  (checked 2026-11-06)

Get your OceanToken API key

  1. Create an OceanToken account and an API key.
  2. Copy the snippet below, paste your key, and run it.
  3. 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", "prompt": "A slow dolly-in on a ceramic mug on a sunlit desk"}'

Get API Key 

  • Hailuo
  • AI video
  1. 7 min read

    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.

    • AI video
    • LLM API
    • Tutorial
  2. 7 min read

    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.

    • Kimi
    • LLM API
    • Tutorial
  3. 6 min read

    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.

    • Hunyuan
    • LLM API
    • Tutorial