You have a product idea that needs moving video, and you just read that MiniMax H3 can turn text, stills, clips, and even audio into a 2K video. So you open the docs, find the generation endpoint, and ship a button that calls it. Two weeks later you are debugging three silent failure modes at once: a queue of half-finished jobs, a billing report that does not match what users saw, and a polling loop hammering the API every half second because "submitted" looked like "done."

This guide is the map between that first endpoint call and a safe production integration. It is written for developers and technical creators wiring H3 into a product, creative tool, or internal pipeline, and it is based on the official MiniMax video generation documentation, checked on August 2, 2026. After reading it you will be able to design a safe async integration: pick the right mode, keep payloads inside the documented limits, poll without abuse, retrieve finished video, and add the guardrails that keep credits and users intact.

The Pain This Guide Solves

Most API guides jump straight to code and skip the decision layer. With video generation, that is expensive. A bad H3 integration can waste credits on oversized payloads, overload a request with references the model can only partially use, poll too aggressively and burn server budget, or — worst of all — treat a queued job as a finished clip and show users a download link that does not exist yet.

Competitive Difference: What This API Guide Adds

Instead of only listing endpoints, this guide explains how to choose the right generation mode, how to keep payloads small, how to poll safely, and how to decide whether your app should expose H3 directly or wrap it behind a simpler product workflow. The result is a reference you can hand to an engineer at the start of a sprint, not a copy-paste snippet you debug at 2 a.m.

What the MiniMax H3 API Supports

MiniMax's video generation docs describe H3 as an open, general-purpose multimodal video model that understands text, image, video, and audio input in a unified way. That shows up as three supported modes:

The model table lists MiniMax-H3 with 768P and 2K output, 4- to 15-second durations at 24 fps (integer durations only), and common or adaptive aspect ratios. Treat that as the current official envelope — not a guarantee that every product wrapper exposes every option.

Input Limits to Design Around

The most important production detail is not the output spec. It is the request shape. MiniMax docs list these H3 input constraints:

Three things worth reading twice. First, the limits apply per asset, not in aggregate — three 29 MB images are each fine, even if the raw body smells large. Second, the docs recommend URL input for large assets precisely because the 64 MB body cap is easy to hit with video references. Third, a reference video clip cannot exceed 15 seconds of source material, so there is no point letting users upload a 50 MB, 60-second clip and hoping the model will trim it.

Rule of thumb: do not expose all of those limits in your first UI. Start with one prompt and one optional reference. Add mixed references only after you know what role each asset should play.

The Async Workflow

MiniMax's documentation describes video generation as a three-step asynchronous process:

1. Create a generation task and receive a task_id
2. Poll task status with that task_id
3. When the task succeeds, download the video from content.url

This matters because "submitted" is not success. The official example shows the shape of a safe poll loop:

import os
import time
import requests

api_key = os.environ["MINIMAX_API_KEY"]
headers = {"Authorization": f"Bearer {api_key}"}
BASE_URL = "https://api.minimax.io"

def poll_until_done(task_id: str) -> str:
    # Recommended polling interval from the official docs: 10 seconds.
    while True:
        time.sleep(10)
        response = requests.get(
            f"{BASE_URL}/v2/query/video_generation/{task_id}",
            headers=headers,
        )
        response.raise_for_status()
        task = response.json()["task"]
        print(f"Current task status: {task['status']}")
        if task["status"] == "succeeded":
            return task["content"]["url"]
        if task["status"] in ("failed", "cancelled", "expired"):
            raise Exception(f"Task terminal state: {task['status']}")

A few technical details worth internalizing:

• Polling interval. The official example sleeps 10 seconds between checks. Polling faster than that does not finish your job sooner; it just loads the status endpoint. If you want to be extra polite, use exponential backoff up to a 30-second cap.
• Terminal states. failed, cancelled, and expired are final. Do not retry these in a hidden loop — an auto-retry that spends user credits without consent is how support tickets are born.
• Success means a URL. On success, the task response carries content.url directly. There is no separate download step or file_id exchange, so once that URL exists you can stream it to the user or archive it in your own storage.

Minimal Architecture

A robust first implementation can be simple:

If your app already has a queue, use it. Video generation is long-running enough that a synchronous request/response model will feel brittle — a user will not wait 30 seconds for a single HTTP response, and neither should your web server.

Mode Selection Logic

Use this decision tree:

• If the user has no reference assets, use text-to-video.
• If the user has a start frame or an intended ending frame, use first/last-frame image-to-video.
• If the user has multiple assets with different roles, use reference generation.
• If the user uploads audio only, require text, image, or video too, because the docs say audio cannot be the sole prompt.

That last rule is the one most integrations get wrong. It is tempting to let a user drag in a voice track and call it a day. The model cannot consume that alone, so your UI must either reject the combination or prompt for a text description alongside it. Do not let your frontend accept an input shape the backend cannot use.

Production Guardrails

Before you expose H3 to users, add these guardrails:

1. Validate file type, dimension, and size before upload, using the per-asset limits above.
2. Limit reference count in the UI, even if the API allows more — nine images in a first version is a UX failure, not a feature.
3. Store task_id and status separately from the final asset, so a retry never reuses a stale URL.
4. Poll at the documented 10-second interval, and back off if the queue is long.
5. Treat failed, canceled, and expired as terminal states; show a plain-language error, not a spinner.
6. Make retry a new task that the user explicitly triggers — never a hidden loop that spends credits without consent.
7. Warn early when references are too large or unsupported, before any credits are consumed.
8. Keep prompt and asset logs private by default.

A Better First User Flow

Start with a small, opinionated interface:

1. Choose mode: Text, Image, or References
2. Enter one production-style prompt
3. Pick duration and resolution
4. Upload at most one image in the first version
5. Generate
6. Review
7. Rerun with one changed variable

That last step is the silent workhorse of video iteration. Users rarely nail a shot on the first pass, and a single-variable rerun is how they learn what H3 responds to.

Before you build all of that, there is a faster way to test the interaction. Our AI video generator wraps H3 behind exactly this flow — choose a mode, write a prompt, pick resolution and duration, and watch the async pipeline handle pending, success, and failure states. It is a cheap way to validate whether H3's output style fits your product before you invest in a custom API build.

What Not to Promise Yet

Do not promise that H3 is free to self-host today. The official launch post says MiniMax plans to open weights in the coming days, subject to laws and regulations, and that a technical report is coming soon. That is an important direction, but it is not the same as a documented local deployment package with a license you can ship against.

Do not quote H3 pricing from the video package page either. That page explicitly says the existing video packages do not support MiniMax H3 yet. Pricing may be handled differently for H3 as the docs evolve, so verify before you put numbers in your own pricing table.

FAQ

Does MiniMax H3 have an API?

Yes. MiniMax publishes video generation documentation for MiniMax H3, including task creation, polling, and result download examples under a dedicated MiniMax-H3 model name.

Is MiniMax H3 synchronous or asynchronous?

Asynchronous. You submit a generation task, poll status with the returned task_id, and download the output URL only after the task reaches succeeded.

Can I send audio-only input to H3?

No. MiniMax docs say audio references must be accompanied by image or video input and cannot be sent alone.

What is the best first API mode to implement?

Start with text-to-video or image-to-video. Reference generation is more powerful, but it needs more UI guidance because each asset should have a clear role.

Should I use the API or the web app first?

Use the web workflow first if you are still validating prompt style, model fit, and user demand — our AI video generator is a good starting point. Move to the API when you need automation, user accounts, queues, billing, or product-specific controls.

Sources

• MiniMax H3 official launch post — Launch context, multimodal positioning, 2K/audio claims, open-weights and technical-report plans.
• MiniMax video generation docs — H3 modes, input requirements, async workflow, polling, and code examples.
• MiniMax model introduction docs — Model table for output resolution, duration, fps, and supported H3 modes.
• MiniMax video package pricing docs — Current caveat that video packages do not support H3 yet.
• MiniMax API docs home — Official MiniMax developer documentation entry point.
• Hailuo AI official site — Consumer-facing Hailuo product context for creators.
• MiniMax official GitHub page — Official MiniMax GitHub organization context.
• MiniMax Hugging Face organization — Official Hugging Face organization and model release context.
• Kling AI official site — Comparison point for creator studio and video model positioning.
• Google Gemini API video docs — Comparison point for async/multimodal video generation API planning.