How to Use the Hailuo AI API: Hailuo 02, 2.3, Pricing, and Production Access (2026)

MiniMax's Hailuo 02 climbed to #2 on the global AI video leaderboards on the strength of one thing most models still fumble: physics. Gravity, fluid dynamics, and complex human motion like gymnastics hold together in ways that read as filmed, not generated, at native 1080p and up to 10 seconds. Then MiniMax shipped Hailuo 2.3 on the same architecture, tuned for human motion and micro-expressions, at the same price. For developers, that raises a practical question, not a benchmark one.

This guide covers everything verified: what Hailuo 02 and 2.3 actually do, which one your pipeline should call, how text-to-video and image-to-video differ, how the async request lifecycle works with real Modellix endpoint examples, how per-video and per-second pricing compares across providers, and how to integrate Hailuo through a single API key. Can you put it into production today, and which version and endpoint should you reach for?

Hailuo Capabilities Explained: Physics Simulation, Native 1080p, and 4 Things That Matter for Production

Hailuo is MiniMax's video generation family. According to MiniMax, Hailuo 02 is a next-generation model that ranked #2 globally on blind-preference video leaderboards. Four things matter once you move past the demo reel.

Physics simulation is the headline. Hailuo 02 models gravity, fluid dynamics, and complex movement (gymnastics, collisions, cloth) more convincingly than most competing models. For product, sports, and character work where motion has to look physically plausible, this is the reason teams pick it.

Native 1080p, not upscaled. Hailuo 02 generates directly at 1080p resolution, up to 10 seconds at 24 to 30 FPS. You are not paying for a 720p render plus a separate upscale pass.

Hailuo 2.3 retunes the same base for humans. Built on the Hailuo 02 architecture, the 2.3 release is tuned for human motion, micro-expressions, and stylized art. It outputs 1080p at 6 seconds or 768p at 10 seconds. Crucially, MiniMax kept it at the same price point as 02.

Both speak the same API. Text-to-video and image-to-video, async submit-and-poll, the same parameter shape. Switching between 02 and 2.3, or between text and image input, is a slug change, not a rewrite.

Generated through Modellix's unified API in a single call: MiniMax Hailuo 02 text-to-video, a cinematic drift over a sea of clouds at sunrise, 1080p, 6 seconds. Cost to generate: roughly $0.30 to $0.70, billed per second. That is the whole price of one API request.

Hailuo 02 vs Hailuo 2.3: Which One Your Pipeline Should Call

Same family, same price, different sweet spots. Pick by what your content is made of.

The honest read: there is no "better" version, only a better fit. Reach for Hailuo 02 when physical plausibility and longer 1080p takes matter most. Reach for Hailuo 2.3 when your shots are built around people, faces, and expression, or a stylized art direction. Because pricing is identical, you can run both on the same prompt and keep whichever output your use case prefers.

Where Hailuo 02 sits in MiniMax's lineup today. MiniMax now documents video generation around its newer MiniMax H3 model and lists Hailuo 02, Hailuo 2.3, and 2.3 Fast under legacy video models. Legacy does not mean removed: the official pay-as-you-go page still prices MiniMax-Hailuo-02, and Modellix serves it alongside the H3 routes. The official API name is MiniMax-Hailuo-02; aggregators wrap it under their own IDs (minimax/hailuo-02-t2v and -i2v on Modellix, fal-ai/minimax/hailuo-02/standard/image-to-video on fal), and those IDs are not interchangeable. Hailuo 02 also supports a first-and-last-frame workflow, exposed on Modellix as minimax/hailuo-02-fl2v.

Text-to-Video vs Image-to-Video: Which Endpoint You Need

Modellix exposes Hailuo as both text-to-video and image-to-video endpoints.

Text-to-video (hailuo-02-t2v) takes a prompt and generates a clip from scratch. Reach for it when you have no source frame: concept exploration, B-roll, fully synthetic scenes, and storyboard-to-motion work.

Image-to-video (hailuo-02-i2v) takes a reference image plus a prompt and animates it. Reach for it when the first frame is fixed: product shots that must stay on-brand, character consistency, or animating an existing still.

A simple rule: if a human would need to see a picture first to know what the output should look like, use image-to-video. If the prompt alone is enough, use text-to-video. Both share the same request schema and async lifecycle, so switching is a one-line change.

Hailuo API Request Lifecycle: Submit, Poll, and Retrieve

This section is for developers moving Hailuo from a manual model test into a backend service, queue, or agent workflow. A no-code Playground test is the fastest way to validate the model; the lifecycle below is for production implementation.

Hailuo video generation is asynchronous. You submit a job, poll for status, then retrieve the result. The pattern is identical across versions and input modes.

Step 1: Submit the Job

Text-to-video:

curl --request POST \
  --url https://api.modellix.ai/api/v1/minimax/hailuo-02-t2v/async \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "Cinematic slow aerial drift over a vast sea of golden clouds at sunrise, gentle drifting motion, warm volumetric light, serene and dreamy",
    "duration": 6,
    "resolution": "1080P",
    "prompt_optimizer": true
  }'

For image-to-video, swap the endpoint and pass a reference image:

curl --request POST \
  --url https://api.modellix.ai/api/v1/minimax/hailuo-02-i2v/async \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "first_frame_image": "https://example.com/product-shot.jpg",
    "prompt": "The camera orbits the product slowly, soft studio lighting",
    "duration": 6,
    "resolution": "1080P"
  }'

The submission response carries a task_id and a polling URL:

{
  "code": 0,
  "message": "success",
  "data": {
    "status": "pending",
    "task_id": "task-abc123",
    "get_result": {
      "method": "GET",
      "url": "https://api.modellix.ai/api/v1/tasks/task-abc123"
    }
  }
}

Two Hailuo-specific notes. Set prompt_optimizer to true (the default) to let the model rewrite a thin prompt into something more directable. And remember the resolution and duration constraint: 10-second jobs run at 768P, while 1080P caps at 6 seconds.

A few more parameters matter. Image-to-video takes the start frame as first_frame_image (a URL or Base64 data URL) and adds 512P to the resolution options; text-to-video starts at 768P. duration accepts 6 or 10, and prompts cap at 2,000 characters. fast_pretreatment speeds up prompt optimization and only takes effect when prompt_optimizer is true. The first-and-last-frame route documents image limits of under 20 MB, a short side above 300 px, and an aspect ratio between 2:5 and 5:2, so preflight reference images before you submit.

Step 2: Poll for Status

Use the get_result.url and sort every response into three buckets:

A workable cadence: first check at 15 seconds, then exponential backoff starting at 5s, capped at 30s, maximum 12 attempts. Add roughly 20% jitter when running concurrent jobs.

Step 3: Retrieve and Validate Results

On a terminal success, the payload carries the output video URL under data.result.resources[]; pick the resource whose type is video. Log at minimum the task_id, your own correlation ID, the input hash, the output URL, the estimated cost, and wall-clock time from submit to terminal state.

Hailuo API Pricing: Per-Video vs Per-Second, and How Providers Compare (2026)

Hailuo pricing has a wrinkle worth understanding before you model costs: providers bill it two different ways. Most resellers charge a flat rate per generated video, while Modellix bills per second of output.

The two billing models are not directly comparable, so do the math for your own clip length, and note that no route wins every cell: in August 2026, fal's list price was lowest for 768P at 6 seconds, while MiniMax direct was lowest for 1080P at 6 seconds. Auth differs by route too (a MiniMax Open Platform key, FAL_KEY on fal, a Bearer key on Modellix), and a key or model ID from one route returns an auth or model-not-found error on another. A 6-second 768p clip lands near $0.27 to $0.32 on either model. Where per-second billing helps is granularity and predictability: you pay for exactly the seconds you generate, and the same metering applies whether you call Hailuo, Wan, Seedance, or Kling.

Modellix's real argument for Hailuo is not being the absolute cheapest. It is access. Hailuo is a MiniMax model, and routing it through the same unified API you already use for other models, with transparent per-job cost logging, removes a separate vendor relationship and a separate billing surface. Current per-model rates are listed at docs.modellix.ai/get-started/pricing.

Single-Endpoint Access: One API Key for Hailuo and Every Major Video Model

Running Hailuo from MiniMax directly, Seedance from one reseller, and Kling from another means managing separate accounts, separate API keys, separate billing dashboards, and separate retry and polling logic for each. The moment you want to compare two models on the same prompt, you are reconciling two different response schemas.

Modellix solves this with a unified AI media API: one endpoint, one API key, one billing dashboard, and consistent async job patterns across every model. Hailuo 02, Hailuo 2.3, Seedance 2.0, Kling, Wan 2.7, and Seedream all share the same submit-poll-retrieve lifecycle. The idempotency and observability setup you build for one model works for all of them.

For international teams specifically, Modellix handles access to MiniMax's models without a separate China-region account, the same way it abstracts other regional providers. No separate MiniMax account required. From a procurement standpoint, Modellix's parent company JG Group is NASDAQ-listed, which matters when a vendor-stability or audit-trail question lands on the integration.

4 Reliability Patterns for Production Video API Pipelines

Past the proof-of-concept stage, these patterns cut operational pain.

Separate your retry buckets. Keep transient failures (5xx, network timeout before acknowledgment) in an auto-retry queue with backoff, and permanent failures (invalid input, content policy, quota) in an alert-and-stop queue. Mixing them is how you build a silent budget-burning loop.

Validate inputs locally before submitting. Confirm required fields and types, run a preflight HEAD request on every reference image URL to check it resolves and meets size limits, and catch resolution and duration contradictions (1080p with 10 seconds) before they cost a render.

Pin the version explicitly. Do not let "Hailuo" mean "whatever is newest." Call hailuo-02 or hailuo-2.3 by name so a model update never silently changes your output style or your costs.

Monitor cost slope, not just cost total. Log estimated cost per job including retries, then roll up P50 and P95 weekly. P95 cost-per-job tells you when a new resolution setting is quietly getting expensive before it shows up on the invoice.

Modellix collection

Shortlist AI Video Models for Production

Compare text, image, and reference-led video workflows across multiple models from one production surface.

Good first tests: Seedance 2.0 / Wan 2.7 / HappyHorse 1.1

Explore the collection

How to Test Hailuo in 30 Seconds

Every method starts with a Modellix account. Sign in with email, Google, or GitHub, add credit, and pay only for what you generate. There is no subscription.

Create your Modellix account →

Method 1: Playground

No code. Open the Hailuo 02 T2V model page, paste a prompt, and review the clip in your browser.

Method 2: API, Through Your Coding Agent

Paste this into Claude Code, Codex, or Cursor. One sentence and one API key are all your agent needs: change the model name and docs link, and the same prompt batch-generates assets with any model on Modellix.

My Modellix API key is mdlx-••••••••••••••••••••••••. Read https://docs.modellix.ai/get-started/index.md and https://docs.modellix.ai/minimax/hailuo-02-t2v.md, then use Hailuo 02 T2V to generate one 5-second 16:9 clip for each prompt in prompts.txt. Poll each task until it finishes and save the MP4 files to ./clips.

Swap the masked key for your own from the Modellix console. Treat it like a password and share it only with agents you trust. The API guide covers the raw request format.

Method 3: Skill

Install the Modellix skill once. After that, your agent finds the right model and request fields by itself.

npx skills add https://github.com/Modellix/modellix-plugin --skill modellix

Use the Modellix skill to generate a 5-second clip with Hailuo 02 T2V, then download it to ./clips.

Setup for each agent host is in the Skill guide.

Method 4: CLI

For scripts and scheduled jobs. One command submits the task, waits, and prints the result URL.

npm install --global modellix-cli
export MODELLIX_API_KEY="your_api_key"

modellix-cli model run --model-slug minimax/hailuo-02-t2v \
  --body '{"prompt":"A dancer leaps across a sunlit stage, dust drifting through the light"}' \
  --wait --timeout 15m --quiet

For batches, put one request per line in a JSONL file and run modellix-cli model batch. See the CLI guide.

Frequently Asked Questions About the Hailuo AI API (2026)

What is the difference between Hailuo 02 and Hailuo 2.3?

Both are MiniMax video models at the same price. Hailuo 02 leads on physics and motion realism with 1080p up to 10 seconds. Hailuo 2.3 is built on the same architecture but tuned for human motion, micro-expressions, and stylized art, outputting 1080p at 6 seconds or 768p at 10 seconds. Use 02 for physical realism and longer takes, 2.3 for people and stylized looks.

How much does the Hailuo API cost?

Pricing depends on the billing model. Resellers charge a flat per-video rate of roughly $0.27 to $0.28 for Hailuo 02 and from about $0.19 for Hailuo 2.3 Fast. MiniMax direct charges $0.28 per 768P 6-second video and $0.49 per 1080P 6-second video, and Modellix bills per second at $0.054 to $0.106 (768p to 1080p, August 2026), so a 6-second clip lands in a similar range. Do the math for your specific clip length.

Is the Hailuo 02 API deprecated?

No. MiniMax classifies Hailuo 02 as a legacy video model now that MiniMax H3 is its headline release, but MiniMax-Hailuo-02 is still listed and priced on the official pay-as-you-go page and served by aggregators. Pin the version by name and verify the live page before planning around it.

Does Hailuo support image-to-video?

Yes. Use the image-to-video endpoint and pass a reference image alongside your prompt. The model animates the still while following the prompt for motion. Text-to-video and image-to-video share the same request schema and async lifecycle.

What resolution and duration does Hailuo support?

Hailuo 02 generates native 1080p up to 10 seconds. On Hailuo 2.3, 1080p is capped at 6 seconds and 10-second jobs run at 768p. Plan your pipeline around the resolution and duration pairing rather than assuming 1080p at every length.

Does Hailuo generate realistic physics?

Yes. Physics simulation is Hailuo 02's signature strength, covering gravity, fluid dynamics, and complex human motion. This is the main reason teams choose it for product, sports, and action content where motion has to look physically plausible.

How do I access Hailuo on Modellix?

Get an API key at modellix.ai/console/api-key. Hailuo is available under the minimax/ namespace, for example https://api.modellix.ai/api/v1/minimax/hailuo-02-t2v/async for text-to-video, with image-to-video and Hailuo 2.3 variants alongside it. No separate MiniMax account required.

How does Modellix pricing compare to going direct to MiniMax?

Modellix bills Hailuo per second with transparent per-model pricing at docs.modellix.ai/get-started/pricing. The value beyond price is operational: one API key, one billing dashboard, and the same async pattern across Hailuo, Seedance, Kling, and Wan, with no separate MiniMax account to manage.