Blog

Tutorial

How to Call hailuo-2.3/image-to-video via the HiAPI API: curl and Python

Nov 12, 2026 10 min read
Cover image: interwoven wide fabric stripes on a dark coffee-colored background, flat weave diagram style, dotted with small brass-colored squares.
On this page

What hailuo-2.3/image-to-video does and when to use it

hailuo-2.3/image-to-video is an image-to-video model exposed through the HiAPI unified API. You give it a single still image as the first frame, add a prompt that describes how the scene should move, and the model generates a short video that starts from that image and animates forward from it.

The key word is first frame. Unlike text-to-video, where the model invents the entire scene from a prompt, image-to-video anchors the composition, subject, lighting, and style to the image you supply. That makes it the better choice when you already have a specific visual you need to preserve — a product shot, a character reference, a storyboard panel, a concept render — and you want motion layered on top of it rather than a fresh interpretation.

Reach for this endpoint when:

  • You need continuity with an existing asset. A product photo should not be regenerated into a slightly different product; it should move.
  • You are building storyboards or animatics from static frames and want quick motion previews.
  • You want controlled composition: the camera and subject placement come from the image, and the prompt only needs to describe dynamics.

Prefer text-to-video instead when you have no reference image and want the model to design the shot, or when the visual details are better expressed in words than pinned down by a frame.

Prerequisites and getting your API key

Before the first request you need three things: a HiAPI account, an API key, and a publicly reachable URL for your first-frame image.

Account and API key

Sign in to HiAPI and create an API key from the dashboard. Treat the key as a secret: store it in an environment variable rather than pasting it into source files. Throughout this guide the examples read it from HIAPI_API_KEY.

export HIAPI_API_KEY="your-api-key-here"

A reachable image URL

The image you pass as the first frame must be fetchable by the service — a signed cloud storage URL, a CDN link, or any public HTTPS URL works. Local file paths will not. If your assets live behind auth, generate a time-limited signed URL for the request.

Before you automate anything, confirm the current endpoint path, parameter names, and allowed values in the live HiAPI API reference. Model surfaces evolve, and hard-coding a parameter name you saw in an old tutorial is a common source of avoidable errors. Current pricing and any quota rules are listed on the site's pricing panel — check there rather than assuming.

The request shape: image input and parameters

Conceptually, an image-to-video request has three parts: the model identifier, the image, and the generation parameters.

The model identifier

Every call targets hailuo-2.3/image-to-video. Keep it in one place in your code so switching models later is a one-line change.

The first-frame image

This is a URL to the still that the video will begin from. Its aspect ratio and resolution set the baseline geometry of the output, so pick an image that already has the framing you want rather than cropping later. A clean, well-lit image with a clear subject produces far more predictable motion than a busy collage.

The prompt

A text field describing the motion — covered in the next section.

Duration and resolution

Image-to-video jobs typically expose options for clip length and output resolution. These are the parameters most likely to shift between model versions, so do not hard-code them from memory. Open the live API reference, read the accepted field names and allowed values, and put those values in a config object rather than scattering literals through your code. If a value is rejected, the API response will usually tell you which field is at fault.

The request body is JSON; the response returns a task identifier rather than a finished video, which is the subject of the polling section below.

Writing a prompt that produces believable motion

The image already describes what is in the scene. The prompt's job is to describe how it moves. Prompts that re-describe the subject waste the model's capacity; prompts that specify motion, camera behavior, and physics produce much better clips.

Describe motion, not content

Weak: "a woman in a red coat standing on a bridge."

Strong: "the woman turns her head slowly toward the camera, her coat shifting in the wind; the camera pushes in gently."

Separate subject motion from camera motion

Be explicit about both. "Slow dolly forward," "handheld drift," "static camera," and "orbit to the right" tell the model how the frame itself behaves, while "hair moves," "steam rises," and "pages flutter" describe what happens inside the frame. Combining the two gives a coherent shot instead of a drifting one.

Respect physics

Ask for plausible motion at plausible speed: "fabric ripples gently," "water flows downstream," "smoke curls upward." Avoid instructions that contradict the scene — asking a seated subject to walk, or requesting a fast pan from a locked-off product shot, usually ends in artifacts.

Keep it short and concrete

Two or three sentences of specific, physical language beat a paragraph of adjectives. Name the primary motion first, then the camera, then any secondary detail like lighting changes.

Submitting a job and polling for the result

Video generation takes time, so the API is asynchronous. The lifecycle has three steps:

1. Create the task

POST your image URL, prompt, and parameters to the endpoint. A successful response returns a task identifier and an initial status, typically something like queued or processing. Nothing in that response is a video yet.

2. Poll the task

Send periodic GET requests for that task identifier. Each response reports a status and, once finished, the result payload. Poll on a sensible interval — a few seconds apart is typical — rather than in a tight loop, and cap the number of attempts so a stuck job cannot hang your process forever.

3. Retrieve the video

When the status reports success, the response contains the video location (usually a URL) and often metadata such as duration. Download or store it according to your own retention rules.

Design notes for production

  • Persist the task ID. If your worker crashes mid-poll, you want to resume rather than resubmit and pay for a duplicate job.
  • Handle terminal failure states. A job can fail; treat failure as a distinct branch, not as "keep polling."
  • Decouple submit and poll. In a web backend, submit from the request handler and poll from a background worker so HTTP timeouts never kill a running generation.

Runnable curl example

The following submits a job. Replace the image URL and prompt with your own; the key comes from the environment variable set earlier.

curl -sS -X POST \
  "https://api.hiapi.ai/v1/hailuo-2.3/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://your-cdn.example.com/first-frame.jpg",
    "prompt": "The subject turns slightly toward the camera and smiles; the camera pushes in slowly, soft light shifting across the face."
  }'

The response contains a task identifier. Poll for it with a GET request:

curl -sS \
  "https://api.hiapi.ai/v1/hailuo-2.3/image-to-video/TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Repeat until the status is a terminal success, then read the video URL from the payload. The exact endpoint paths and field names shown here illustrate the pattern — confirm them against the live API reference before you paste anything into production code, since model surfaces do change.

Runnable Python example

This script submits a job, then polls until it finishes, with a timeout and basic error handling.

import os
import time

import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1/hailuo-2.3/image-to-video"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def create_task(image_url: str, prompt: str) -> str:
    resp = requests.post(
        BASE,
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"image_url": image_url, "prompt": prompt},
        timeout=60,
    )
    resp.raise_for_status()
    data = resp.json()
    task_id = data.get("task_id") or data.get("id")
    if not task_id:
        raise RuntimeError(f"No task id in response: {data}")
    return task_id


def poll_task(task_id: str, timeout_s: int = 600, interval_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()
        status = str(data.get("status", "")).lower()
        if status in {"succeeded", "success", "completed"}:
            return data
        if status in {"failed", "error", "cancelled"}:
            raise RuntimeError(f"Task {task_id} failed: {data}")
        time.sleep(interval_s)
    raise TimeoutError(f"Task {task_id} did not finish in {timeout_s}s")


if __name__ == "__main__":
    task = create_task(
        image_url="https://your-cdn.example.com/first-frame.jpg",
        prompt="Steam rises from the cup; the camera drifts slowly to the right.",
    )
    result = poll_task(task)
    print(result)

Because status strings can differ across API versions, the code checks a small set of common success and failure values rather than one literal — verify the exact vocabulary in the API reference and trim the sets accordingly. If you build several media pipelines, keeping this helper isolated makes it easy to reuse.

Common failure modes and how to debug them

Most problems with this endpoint fall into a handful of buckets.

The image is rejected or cannot be fetched

The service must be able to download your image. If you get a fetch or validation error, check that the URL is public HTTPS, not expired (signed URLs time out), and that the format and size are within the documented limits. A quick sanity check is opening the URL in a private browser window — if it prompts for login, the service cannot read it either.

Invalid parameters

A rejected duration, resolution, or an unknown field usually returns a validation error naming the field. Compare your payload against the live API reference rather than against a tutorial, and log the full error body — the message is more specific than the HTTP status code alone.

Authentication errors

A 401 or 403 almost always means the key is missing, malformed, or lacks access. Confirm the Authorization header is present and that the environment variable is actually exported in the shell or process running the request.

Polling times out

If the job is still processing after your timeout, first check you are polling the right task ID, then extend the timeout. In production, distinguish "still running" from "stuck": persist state and let a worker resume polling rather than resubmitting, which wastes jobs.

Jobs fail after submission

A failed job usually points at the prompt or the image pair — contradictory motion instructions, or a first frame that conflicts with the requested movement. Simplify the prompt, try a cleaner first frame, and re-run.

Output looks wrong

If motion is subtle or strange, the fix is almost always the prompt: state the primary movement explicitly, separate camera behavior from subject behavior, and keep physical motion plausible. Track request and task IDs in your logs so you can correlate a bad clip with the exact inputs that produced it. Confirm parameter names and current pricing on the API reference and pricing panel before shipping.

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