Blog

Tutorial

How to Use minimax-h3-max-turbo/image-to-video via the HiAPI API: curl, Python, and a Working Request

Nov 17, 2026 11 min read
Abstract cover art of wide horizontal stepped bands in terracotta and umber descending across a warm sand background, with flat print edges.
On this page

What this endpoint does and when to use it

minimax-h3-max-turbo/image-to-video takes a single source image plus a text prompt and returns a short generated video that begins from that image. The image acts as the first frame (or the visual anchor), so the output inherits its composition, palette, and subject identity. The prompt then describes what should happen next — camera motion, subject action, atmosphere.

When to pick this over text-to-video

Text-to-video is the right tool when you have no reference visual and want the model to invent everything. Image-to-video is the right tool when the first frame is the point: you already have an approved product shot, a storyboard keyframe, a character design, or a user-uploaded photo, and you need it to move while staying recognizable. Concretely, teams reach for this endpoint when:

  • The first frame is contractual. Marketing needs the exact hero image to open the clip, not a lookalike.
  • Consistency matters across clips. Reusing the same source image keeps a character or product stable across a series.
  • You are animating user content. Photos uploaded by end users should animate, not be re-imagined.
  • You want tighter prompt scope. Describing motion is easier than describing an entire scene from nothing, so prompts stay short and predictable.

The endpoint is asynchronous: you submit a job, then retrieve the rendered video. That shape fits queue-driven backends well and is covered in detail below. If you want the full parameter surface, see the model page.

Prerequisites and request anatomy

Before calling the endpoint, confirm you have four things:

  1. An API key. Created in your HiAPI account and sent as a bearer token. Treat it as a secret — never embed it in client-side code.
  2. The base URL. All requests go to the HiAPI unified API host; the endpoint path is the model identifier.
  3. A source image that is reachable or encodable — either a public HTTPS URL or a base64 payload, depending on what the request schema accepts.
  4. An HTTP client — curl for smoke tests, and any standard library or requests in Python for real integrations.

The parts of a request

Every job submission carries the same conceptual pieces, regardless of language:

  • Model / endpoint — minimax-h3-max-turbo/image-to-video, part of the request path and echoed in the body for clarity.
  • Source image — the first frame. This is the field that distinguishes image-to-video from text-to-video, and the one most likely to cause validation errors.
  • Prompt — the motion and scene description. Keep it about what changes, not what already exists in the image.
  • Optional generation hints — duration and resolution style controls, if the endpoint exposes them. Only send parameters the schema documents; unknown keys are a common source of 4xx responses.

A submission returns a job identifier and status. The video itself arrives later, via a second request — which is why the polling section below matters as much as the submit call.

A working curl request

The following command submits an image-to-video job. Replace the placeholders — uppercase tokens in angle brackets — with your own values before running it.

curl -X POST "https://api.hiapi.ai/v1/<ENDPOINT_PATH>" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-max-turbo/image-to-video",
    "image": "https://<YOUR_PUBLIC_IMAGE_HOST>/first-frame.jpg",
    "prompt": "Slow push-in on the product, soft studio light shifting across the surface, shallow depth of field."
  }'

A few practical notes on this command:

  • Read the key from the environment. $HIAPI_API_KEY keeps the secret out of your shell history if you export it rather than paste it inline.
  • Use a public image URL for the first test. It removes base64 encoding from the equation while you confirm auth and connectivity work.
  • Keep the JSON body small. The -d payload is the whole request; a missing comma here produces a confusing 400 rather than a clear schema error.
  • Quote the prompt. Prompts with punctuation will break unquoted shell strings.

The response is a job object, not a video. Capture the job ID from it — you will feed that ID into the polling request. If the call fails immediately, jump to the troubleshooting section; auth and payload errors surface at this step rather than later.

The same request in Python

Here is the equivalent submit call in Python using requests. It assumes HIAPI_API_KEY is set in the environment.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1/<ENDPOINT_PATH>"

payload = {
    "model": "minimax-h3-max-turbo/image-to-video",
    "image": "https://<YOUR_PUBLIC_IMAGE_HOST>/first-frame.jpg",
    "prompt": (
        "Slow push-in on the product, soft studio light shifting "
        "across the surface, shallow depth of field."
    ),
}

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

response = requests.post(BASE_URL, json=payload, headers=headers, timeout=30)
response.raise_for_status()
job = response.json()
print(job["id"], job.get("status"))

What to keep from this snippet when you adapt it:

  • The timeout is not optional. Submission is fast, but a hung socket in a web request handler will take your worker down with it.
  • raise_for_status() before parsing. It turns a silent 401 into an exception you can actually log.
  • Return the job ID, not the response. In a service, the submit function should hand back the identifier so a separate poller — or a background task — can own the wait.
  • Keep the payload in a variable. Once the call works, swapping the image URL for a signed upload URL or a base64 string is a one-line change.

This is deliberately a plain HTTP client rather than a wrapper library: the request shape is the contract, and you should be able to reproduce it in any language your stack uses.

Preparing images and the first frame

Most failed image-to-video jobs fail on the image, not the prompt. A few habits prevent that.

Format and delivery

Use a standard, widely supported raster format — JPEG or PNG — and make sure the URL is publicly fetchable without cookies, redirects to login pages, or expiring signatures you generate after submission. If your assets live in a private bucket, generate a signed URL with a lifetime comfortably longer than the job's expected runtime. For base64 payloads, strip the data-URI prefix if the schema expects raw encoded bytes, and keep the encoded size well within the documented limit.

Sizing and framing

The model renders video at fixed output dimensions, so your source will be adapted to fit. Two consequences:

  • Match the aspect ratio you want. A tall portrait photo fed into a landscape render will be cropped or letterboxed, and the subject may land off-center.
  • Leave headroom for motion. If the prompt describes the camera pushing in or the subject moving upward, compose the source with room in that direction.

Keeping the first frame intact

The opening frame is largely the image's job. Write the prompt as instructions for what happens after frame one: describe camera behavior, subject action, and lighting changes. Avoid re-describing the scene — repeating "a red chair on a white floor" when the image already shows it tends to add drift rather than fidelity. If the result veers away from the source, shorten the prompt before changing the image.

Do not assume undocumented parameters exist. If a control you want is not in the schema, achieve it through the prompt or through image preparation.

Handling the async job lifecycle

Image-to-video jobs are not synchronous. The pattern is submit → poll → retrieve, and a production integration should implement all three explicitly.

1. Submit and persist

Submit the request and store the returned job ID immediately, ideally alongside your own correlation ID, the request payload hash, and a timestamp. If the process dies between submission and storage, you have paid for a job you cannot retrieve.

2. Poll with backoff

Poll the job status endpoint with the stored ID. Video rendering takes appreciably longer than image generation, so:

  • Start with a modest interval — a few seconds — and increase it as the job ages, rather than hammering the endpoint at a fixed rate.
  • Cap total waiting at a job-appropriate maximum, then treat the job as timed out and decide whether to retry.
  • Treat terminal states as terminal: once a job reports success or failure, stop polling.
import time

def wait_for_job(poll_fn, job_id, max_wait=600):
    deadline = time.time() + max_wait
    interval = 5
    while time.time() < deadline:
        job = poll_fn(job_id)
        if job["status"] in ("succeeded", "failed"):
            return job
        time.sleep(interval)
        interval = min(interval * 1.5, 30)
    raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")

3. Retrieve and store the output

On success, the job object carries the result location. Download the video promptly and copy it to your own storage — output URLs should be treated as temporary, not as your permanent asset store. Record the job ID next to the stored file so support can trace any clip back to its request.

For retries, only re-poll jobs whose IDs you stored; never resubmit blind, or you will generate duplicate renders and duplicate charges.

Troubleshooting common errors

Authentication failures (401 / 403)

Check the Authorization header first: the word Bearer, a single space, then the key, with no trailing newline from a copied secret. Confirm the key is active and belongs to the account you expect. If curl works and Python does not, print the header length — an empty environment variable produces a valid-looking but useless token.

Malformed or unsupported image payloads (400 / 422)

The most common non-auth failure. Check, in order:

  • The image URL resolves without a redirect to an HTML login page.
  • The format is JPEG or PNG, not WebP, HEIC, or a PDF thumbnail.
  • The encoded or downloaded size is within the documented limit.
  • Base64 payloads have no data: prefix and no whitespace from line wrapping.
  • The image is not corrupt — fetch it yourself and open it before blaming the API.

Unknown or invalid parameters

A typo in a field name, or a parameter the endpoint does not expose, typically returns a validation error naming the field. Remove speculative parameters and rebuild from the documented minimum.

Rate limits (429)

Back off exponentially and honor any retry hint in the response. Do not retry in a tight loop; that deepens the limit. If you routinely hit it, batch your submissions through a queue rather than firing them inline from user requests.

Job timeouts and stuck polls

If a job never reaches a terminal state within your budget, log the job ID and status history and stop polling. Persistent timeouts usually indicate an oversized or unusual image at submission time, so revisit the image preparation section. Do not resubmit automatically without a ceiling on attempts.

Production checklist before you ship

Before this endpoint goes anywhere near real traffic, verify each of the following:

  • Timeouts everywhere. Short timeout on submission, bounded total wait on polling, and a hard cap on retry attempts. No unbounded while True loops.
  • Retries with backoff. Retry 429s and transient 5xx responses; never retry validation errors — they will fail identically.
  • Job IDs in logs. Log the job ID, your correlation ID, and the final status for every request. This is the single most useful debugging artifact you can keep.
  • Outputs in your own storage. Copy finished videos out of returned URLs into durable storage, and keep the source image reference with them for reproducibility.
  • Image validation at the edge. Reject wrong formats and oversized uploads before they reach the API, so users get a fast, clear error instead of an async failure minutes later.
  • Cost awareness. Generation is billed per output based on the rendered video, so track job volume and duration per user or feature. Check the current pricing panel rather than hardcoding assumptions into your code or docs.
  • A canary prompt. Keep one known-good image and prompt pair in your test suite and run it after any integration change to confirm the request contract still holds.

The endpoint is straightforward once the async lifecycle is handled correctly — submit, persist, poll, store. Start from the model page for the exact schema, then wire up the submit-and-poll pattern above.

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