How to use minimax-h3 via the hiapi API: curl, Python, and a working request

MiniMax H3 is hiapi's native-2K video model, and it does more than plain text-to-video: the same model ID also does first/last-frame control and multimodal reference-to-video, switched purely by which input fields you send. This guide covers the minimal working request, a complete Python script, and the production details — callbacks, mode constraints, and the exact errors you'll hit.

What you're building, and what you need

Goal: send a prompt to POST /v1/tasks, poll until the task finishes, and download a 4-15 second 2K MP4 from data.output[0].url.

You need one thing:

1. A hiapi API key — create one in the dashboard. Send it as a Bearer token on every request.

Everything else — model routing, task polling, output storage — goes through the same unified async task API that every hiapi model uses, so this flow transfers directly if you swap in a different model id.

The minimal working request (curl)

Create the task:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "input": {
      "prompt": "A paper kite drifting gently above a green field under soft daylight, stable camera, no text."
    }
  }'

Three things worth knowing before you send it:

• model is the bare id minimax-h3 — no vendor prefix, no version suffix.
• input.prompt is the only required field. Leave everything else out and you get the defaults: 5 seconds, native 2K resolution, 16:9 aspect ratio, no watermark.
• input.duration is an integer number of seconds from 4 to 15. Send 99 and the API answers invalid input: duration: maximum: got 99, want 15.

The create response is a small envelope; the field you need is data.taskId. Poll it:

curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer sk-<your-key>"

Read data.status. "success" and "fail" are the only terminal states — anything else means keep polling. On success, the clip lives at data.output[0].url.

Output URLs are signed and carry an expireAt. Download the MP4 to your own storage as soon as the task succeeds; don't hotlink the temp URL or store it for later.

The same flow in Python

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {KEY}"}

payload = {
    "model": "minimax-h3",
    "input": {
        "prompt": "A paper kite drifting gently above a green field under soft daylight, stable camera, no text.",
        "duration": 6,
    },
}

resp = requests.post(API, json=payload, headers=HEADERS, timeout=60)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task created:", task_id)

deadline = time.time() + 600  # video tasks can take a few minutes
while time.time() < deadline:
    task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    status = task.get("status")
    if status == "success":
        video_url = task["output"][0]["url"]  # signed URL with expireAt
        clip = requests.get(video_url, timeout=120).content
        with open("minimax-h3-clip.mp4", "wb") as f:
            f.write(clip)
        print("saved minimax-h3-clip.mp4")
        break
    if status == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')}: {err.get('message')}")
    time.sleep(5)
else:
    raise TimeoutError("task did not finish within 10 minutes")

Three modes, one model ID

minimax-h3 picks its mode from which input fields you populate — don't mix fields from different modes in one request:

First/last-frame example:

{
  "model": "minimax-h3",
  "input": {
    "prompt": "The camera slowly pushes forward as morning light transitions naturally into golden sunset.",
    "duration": 6,
    "first_frame_image": "https://example.com/first-frame.jpg",
    "last_frame_image": "https://example.com/last-frame.jpg"
  }
}

Multimodal reference example:

{
  "model": "minimax-h3",
  "input": {
    "prompt": "Keep the reference subject consistent and follow the camera rhythm of the reference clip for a polished product showcase.",
    "duration": 8,
    "image_urls": ["https://example.com/product.jpg"],
    "video_urls": ["https://example.com/camera-motion.mp4"],
    "audio_urls": ["https://example.com/rhythm.mp3"]
  }
}

All three modes take public HTTPS URLs, not file uploads — host any local files on a CDN or object storage first.

Production notes: callbacks, idempotency, and real errors

Callbacks instead of polling. For anything beyond ad hoc scripts, add a top-level callback object to the create request instead of polling:

{
  "model": "minimax-h3",
  "input": { "prompt": "A paper kite drifting gently above a green field under soft daylight." },
  "callback": { "url": "https://your-server.example.com/hooks/hiapi", "when": "final" }
}

callback.when only supports "final" — you get one call when the task reaches a terminal state, covering both success and failure. Treat delivery as at-least-once: key your handler on taskId and make it idempotent, and keep a slow polling loop as a fallback in case a callback is missed.

Errors you'll actually see:

Retries are cheap before create, careful after. A 400/503 at create time means no task exists yet — retry freely. Once you have a taskId, poll or wait for the callback instead of blind-resubmitting, or you can end up paying for duplicate generations.

Related pages

• minimax-h3 model page — parameters, pricing, and playground
• Unified Async API introduction — the task create/poll flow every model shares
• Authentication — API key setup and header format
• Pricing — current per-generation video pricing
• Hailuo 2.3 text-to-video via the same API — a second native text-to-video recipe if you want to compare models

FAQ

How long can the generated video be? duration accepts integers from 4 to 15 seconds, defaulting to 5. Values outside that range are rejected at create time with a 400 that names the limit.

What resolution does minimax-h3 generate at? Native 2K only — it's currently the sole supported value for input.resolution.

Can I control the first and last frame of the clip? Yes. Set first_frame_image for the opening frame, and optionally last_frame_image for the closing frame — but last_frame_image requires first_frame_image to be set too.

Can I combine frame control with reference images? No. Frame-control fields (first_frame_image, last_frame_image) and reference-media fields (image_urls, video_urls, audio_urls) are separate modes — mixing them isn't supported.

Do I have to poll, or can I get pushed a result? Both work. Polling GET /v1/tasks/<taskId> is simplest for scripts; for production, add callback: {"url": ..., "when": "final"} and receive one POST when the task reaches a terminal state.

How long is the output URL valid? It's a signed URL with an expireAt timestamp. Download the file immediately after status turns "success" and store it yourself.

What does it cost? Video models are priced per generation depending on duration and settings — see the current numbers on the pricing page.