Blog

Tutorial

How to Call minimax-h3-max-turbo Text-to-Video via the HiAPI API

Nov 12, 2026 12 min read
Cover art: a flat faceted mineral cross-section in deep petrol and teal tones, like a printed gemology plate, on a dark background.
Model
minimax-h3-max-turbo
On this page

What This Endpoint Does and When to Use It

minimax-h3-max-turbo/text-to-video is the text-to-video model endpoint exposed through the HiAPI API. You send a text prompt describing the scene you want, plus a small set of output-shaping parameters, and HiAPI returns a generated video. The model is a good fit when you have a written description and no source footage: marketing clips, social cutaways, storyboard previews, background loops for an app, or batch-generated variants of one creative concept.

A few properties matter before you write code:

  • It is a generation endpoint, not a template. Output is deterministic only in structure (you get a video back), not in content. Treat every job as a fresh render and design your prompts for reuse.
  • It is asynchronous. The call that submits work does not hand back finished video bytes. You get a job handle, then you poll for the result. Any integration that assumes a synchronous response will fail at the first timeout.
  • Output is shaped by request parameters. Duration and resolution change render cost and wall-clock time, so the parameters you choose are also a latency and budget decision.
  • No source media is required. You do not upload footage or images; the prompt and parameters are the entire input surface.

When should you reach for something else? If you already have footage and want to restyle or extend it, this is not the right endpoint. If you need frame-accurate control over camera motion or exact composition, text prompts will feel loose. And if you only need a still image, a text-to-image endpoint is cheaper and faster. Use minimax-h3-max-turbo/text-to-video when the prompt is a good enough specification of the shot.

The rest of this guide walks through authentication, a working curl call, the same call in Python, the job lifecycle, the parameters that matter, the errors you will hit, and the hardening steps before production.

Prerequisites and Authentication

You need three things before your first request:

  1. An API key from your HiAPI account. Treat it as a secret: load it from an environment variable, never commit it, and rotate it if it leaks.
  2. The HiAPI base URL. All calls in this guide go to the same base host; the model is selected by the path segment, not by a different domain per model.
  3. An HTTP client. curl for smoke tests, and any standard library or HTTP client for your service code.

How the key is passed

HiAPI authenticates requests with a bearer token in the Authorization header. The shape is always the same:

export HIAPI_API_KEY="your_api_key_here"
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Two habits save a lot of debugging time:

  • Keep the header spelling exact. Authorization with a capital A, Bearer followed by a single space, then the key. A missing space is the single most common cause of a mysterious 401.
  • Always send Content-Type: application/json. Servers that expect JSON will reject or misparse a body sent without it, and the error you get back is often about a missing field rather than the real cause.

Verify before you build

Do not start with the video endpoint. Make one cheap, fast call to confirm the key and base URL resolve correctly, then move on. If that sanity call fails, nothing downstream will work, and you will be debugging the wrong layer. Keep the key in one place in your codebase, a single small client module, so that a rotation later is a one-line change.

A Working curl Request

The submit call sends a prompt and parameters as a JSON body to the model path. Here is a minimal runnable invocation:

curl -sS -X POST "$HIAPI_BASE_URL/minimax-h3-max-turbo/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A slow aerial push over a foggy pine forest at sunrise, soft volumetric light, cinematic",
    "duration": 5,
    "resolution": "720p"
  }'

What each piece does:

  • -X POST — generation jobs are created with POST.
  • The URL — base host plus the minimax-h3-max-turbo/text-to-video path. Keep the base host in a variable so you can point test and production at the same code path.
  • Authorization — the bearer token described in the previous section.
  • Content-Type — declares the JSON body.
  • prompt — the only required creative input. Write it as a shot description: subject, camera behavior, lighting, and mood. Short noun phrases produce vague results; a sentence or two of concrete visual direction does much better.
  • duration and resolution — output-shaping parameters covered in their own section below.

Use -sS so curl is silent but still prints errors, and pipe the response through a pretty-printer while you are exploring. The response is JSON containing a job identifier; save it, because you need it to poll for the finished video. Do not expect video bytes in this response.

If you want to see exactly what you sent when debugging, add -v for verbose output, but strip it before sharing logs, since verbose output can include headers.

The Same Request in Python

The Python version is the same request with the key loaded from the environment and the response parsed. Here is a small reusable client:

import os
import time
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

MODEL_PATH = "/minimax-h3-max-turbo/text-to-video"


def submit_video(prompt: str, duration: int = 5, resolution: str = "720p") -> dict:
    payload = {"prompt": prompt, "duration": duration, "resolution": resolution}
    resp = requests.post(
        f"{BASE_URL}{MODEL_PATH}",
        headers=HEADERS,
        json=payload,
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()


if __name__ == "__main__":
    job = submit_video(
        "A slow aerial push over a foggy pine forest at sunrise, soft volumetric light, cinematic"
    )
    print(job)

Notes on adapting this:

  • json=payload sets the body and the content type together; do not also serialize manually.
  • timeout=30 bounds the submit call. Submission is fast; the render is not, which is why the timeout is short here and polling handles the waiting.
  • raise_for_status() turns non-2xx responses into exceptions so auth and validation failures surface immediately instead of silently returning an error body you later parse as a job.
  • Return the parsed JSON as a dict, and pull the job identifier out at the call site. That keeps the helper generic while your orchestration code decides what to do with it.

If you are on an async stack, the same shape applies with your HTTP client of choice: build the headers once, POST the payload, check the status, and return the parsed body.

Handling the Async Job Lifecycle

Generation takes time, so the endpoint is split into submit and poll. The lifecycle is always: submit, receive a job identifier, poll the job until it reports a terminal state, then fetch the output.

Submit

Send the POST described earlier and read the job identifier out of the response. Log it immediately, associated with your own request ID, so a failed poll later is traceable back to the original prompt.

Poll with backoff

Do not poll in a tight loop. Start with a short interval, then back off:

def wait_for_job(job_id: str, max_wait: int = 600) -> dict:
    deadline = time.time() + max_wait
    interval = 2.0
    while time.time() < deadline:
        resp = requests.get(
            f"{BASE_URL}{MODEL_PATH}/{job_id}",
            headers=HEADERS,
            timeout=30,
        )
        resp.raise_for_status()
        job = resp.json()
        status = job.get("status")
        if status in ("succeeded", "failed"):
            return job
        time.sleep(interval)
        interval = min(interval * 1.5, 15.0)
    raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")

Three details make this reliable. First, the deadline: always give up eventually and surface a timeout instead of polling forever. Second, the capped backoff: start at a couple of seconds, multiply, and cap the interval so you keep making progress without hammering the API. Third, terminal state handling: treat only success and failure as terminal, and return the job object so the caller can branch.

Fetch the result

Once the job reports success, the response carries the location of the finished video. Download or stream it to your own storage promptly, and record the URL alongside the job ID. Do not assume the link is permanent, and do not fetch the video on every poll iteration. Poll the job status, then fetch once.

Duration and Resolution Parameters

Two request parameters shape the output and, with them, the render time and the cost of the call.

duration

Length of the generated clip. Longer clips take proportionally more render time, which means longer polling windows and a larger window for client timeouts to fire. Practical guidance:

  • Match the duration to the use case. A social cutaway is short; a background loop only needs to be long enough to loop acceptably. Generating longer than you will show is pure waste.
  • Start small while iterating. Tune the prompt at a short duration, then re-render the winning prompt at final length.
  • Remember cost scales with output. Billing is by output length, so duration is a budget lever as much as a creative one.

resolution

Spatial quality of the output. Higher resolutions carry more detail and cost more render time and more money. Guidance:

  • Choose for the delivery surface, not the spec sheet. If the video lands in a feed or a small player, generating above that surface buys nothing.
  • Iterate low, render final high. Preview at a lower resolution while you are still changing the prompt, then re-submit the approved prompt at delivery resolution.
  • Expect longer waits at higher settings. Size your polling deadline against the largest combination you allow, not the smallest.

Keep both values in one config object rather than scattering them through code, so that a change from preview to production is a deliberate, visible edit rather than a forgotten literal.

Debugging Common Errors

Most failures fall into four classes. Match the symptom to the class before changing code.

Authentication failures

A 401 means HiAPI did not accept your credentials. Check, in order: the Authorization header is present and spelled correctly; there is exactly one space after Bearer; the key is current and not from a different project; the environment variable actually loaded (a trailing newline in a pasted key is a classic). Confirm by echoing the length of the variable, not the key itself.

Validation failures

A 4xx that is not 401 usually means the request body is wrong. Content-Type missing or not application/json; prompt absent or empty; duration or resolution outside the allowed set. Read the error message literally; it usually names the offending field. Reproduce with the curl version, where there is no library layer to obscure the body.

Timeouts

There are two distinct timeouts. A submit timeout means the POST itself did not return, which usually points at a network path or a too-aggressive client timeout. A polling timeout means the job never reached a terminal state before your deadline; either the render genuinely needs longer, or your deadline is set against preview settings and not production settings. Fix the second by raising max_wait for large durations and resolutions, not by shortening the poll interval.

Polling mistakes

The subtle ones. Polling without any sleep wastes quota and invites rate limiting; polling with a fixed short interval has the same effect. Polling the wrong job ID, often because you reused a variable across submissions. Treating an intermediate status as an error. And fetching the video URL on every iteration instead of once at success. Log the job ID and each observed status; the sequence tells you instantly which of these you hit.

Production Checklist Before You Ship

Moving from a working script to a service that runs unattended means adding a few layers around the same request.

  • Retries with jitter. Retry transient network errors and 5xx responses with exponential backoff and randomization. Never retry validation errors; they will fail identically and burn quota.
  • Bounded timeouts everywhere. A short timeout on submit, a longer deadline on polling sized to your largest allowed duration and resolution, and a timeout on the video download too.
  • Structured logging. Log your request ID, the job ID, each observed status transition, and the final outcome, without logging the API key or full headers. When something fails at 3 a.m., this log is your only evidence.
  • Idempotency at your layer. Keep a mapping from your own request ID to the job ID so that a client retry does not silently spawn a second render.
  • Cost control. Billing follows output length, so cap the maximum duration and resolution your service will accept, and keep prompt previews at lower settings until a human or a rule approves the final render.
  • Key hygiene. Load the key from a secret store, rotate on a schedule, and use separate keys for test and production so a leaked test key cannot spend production budget.
  • Result ownership. Copy finished videos into storage you control as soon as the job succeeds, and treat the delivery URL as ephemeral.

Get these in place and the endpoint becomes a predictable dependency rather than a source of surprise. Start with the curl request above to confirm your credentials, then lift the Python client into your service and wrap it in the checks in this list.

Related articles

View all articles →

Start building with persistent AI artifacts

Get your API key and call image, video and audio models through one task-based API.

Read the API docs