Blog

Tutorial

How to Call kling-4.0-flash Reference-to-Video via the HiAPI API: curl and Python

A working request walkthrough for multi-reference image-to-video, async polling, and troubleshooting

Nov 12, 2026 11 min read
Cover image: two large flat color blocks, pale purple and ink black, meet along a straight hard edge, with a narrow purple seam set into the boundary; the composition is restrained and calm.
Model
kling-4.0-flash
On this page

When to Use Reference-to-Video Instead of Text-to-Video

Text-to-video is a writer's tool: you describe a scene and the model invents everything. Reference-to-video is a director's tool: you hand the model one or more images and ask it to generate motion that keeps those subjects, styles, or compositions recognizable. On HiAPI this distinction is expressed at the endpoint level — kling-4.0-flash/reference-to-video is a separate route from a plain text-to-video call, and picking the right one up front saves you from prompt engineering that can never fully recover a specific look.

Reach for reference-to-video when any of the following is true:

  • Identity or product consistency matters. You have a character sheet, a product photo, or a mascot, and the output must not drift into a generic look-alike.
  • You need to combine sources. A scene may need one image for the character and another for the setting or wardrobe. Multiple reference images let you express that composition explicitly rather than in prose.
  • Style transfer is the point. You want the palette, lighting, or rendering of a supplied frame to carry into motion.
  • You are iterating on a shot. Reference images make reruns comparable, because the visual anchor stays fixed while you tweak motion-related parameters.

Stay with text-to-video when you are exploring concepts, when you have no rights-clean imagery to anchor on, or when the brief is abstract ("a slow aerial over fog at dawn") and any plausible interpretation is acceptable. Reference images constrain the model, and constraints are only useful when you actually want them.

One practical rule: if you find yourself writing a paragraph describing a specific object's exact appearance, that is a signal to switch endpoints and supply the image instead. Descriptions cost tokens and still drift; references anchor.

Request Anatomy: Reference Images and Core Parameters

The endpoint accepts a JSON body. The parts you will actually touch fall into three groups: the reference images, the prompt, and the output-shaping parameters.

Reference images

References are passed as an array, so the same field scales from one image to several. Each entry is a URL that the service must be able to fetch. Practical constraints to design around:

  • Use publicly reachable HTTPS URLs, or URLs your account is authorized to access. Local file paths and file:// URIs are not fetchable by a remote service.
  • Prefer stable hosting over signed links that expire in minutes — a long-running job may fetch later than you expect.
  • Keep each image focused. A clean subject shot contributes more than a busy collage, because the model has to attribute what it sees.
  • Order can matter for how references are interpreted, so keep the array order deterministic in your code rather than relying on dict iteration.

The prompt

With references supplied, the prompt should describe motion, camera, and mood, not appearance. Say how the subject moves, what the camera does, what the pacing feels like. Re-describing the reference image wastes prompt budget and can fight the anchor you just provided.

Output-shaping parameters

Beyond prompt and the reference array, request bodies typically carry fields controlling the output format and generation behavior. Treat these as the knobs you tune last: get a valid call working with defaults first, confirm the references are being honored, and only then adjust output settings. Field names and accepted values are defined in the endpoint reference, and sending an unrecognized field is a common cause of rejected payloads, so validate against the documented schema rather than guessing.

The mental model is simple: references say what, the prompt says how it moves, parameters say what you get back.

A Working curl Request

The most reliable way to sanity-check your payload before writing client code is a single curl call. Set your credentials and inputs as shell variables so the JSON stays readable, then send the request.

API_KEY="$HIAPI_API_KEY"
BASE_URL="https://api.hiapi.ai"   # use the base URL shown in your dashboard

curl -sS -X POST "$BASE_URL/v1/kling-4.0-flash/reference-to-video" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The character turns toward the window as the camera slowly pushes in; soft morning light, calm pacing.",
    "reference_images": [
      "https://your-cdn.example.com/refs/character-front.png",
      "https://your-cdn.example.com/refs/location-window.jpg"
    ]
  }'

Three things to check before you run it:

  1. Path and version prefix. Confirm the exact route against the endpoint documentation in your account; paths are versioned and a stale prefix returns a not-found rather than a validation error.
  2. Auth header. The key goes in the Authorization header as a bearer token. Never place it in the body or in a query string, where it leaks into logs.
  3. Placeholders. Every value you must replace is visibly a placeholder — the base URL comment, the two CDN URLs, the prompt. Grep your request for example.com before declaring it production-ready.

A successful submission returns a task identifier rather than a finished video. Capture that identifier from the response body; you will need it for polling in the next steps. Piping the response through a JSON formatter (| jq .) makes the task ID obvious and is worth the habit.

The Same Call in Python

The Python version differs mainly in how the payload is constructed: build a dict, serialize it once, and keep the request function separate from the polling logic so each can be tested in isolation.

import os
import requests

BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
API_KEY = os.environ["HIAPI_API_KEY"]

REFERENCE_IMAGES = [
    "https://your-cdn.example.com/refs/character-front.png",
    "https://your-cdn.example.com/refs/location-window.jpg",
]

def submit_reference_video(prompt: str) -> str:
    payload = {
        "prompt": prompt,
        "reference_images": REFERENCE_IMAGES,
    }
    response = requests.post(
        f"{BASE_URL}/v1/kling-4.0-flash/reference-to-video",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["task_id"]

if __name__ == "__main__":
    task_id = submit_reference_video(
        "The character turns toward the window as the camera slowly pushes in."
    )
    print("submitted:", task_id)

Notes that prevent avoidable pain:

  • Read the key from the environment. Hard-coded keys end up in git history and in screenshots.
  • Use json= rather than data= so the client sets the content type and escapes the body correctly.
  • Set an explicit timeout. The default of waiting forever turns a stalled connection into a hung worker.
  • raise_for_status() before parsing means a 4xx body is reported as an HTTP error instead of a confusing KeyError on the response JSON.
  • Confirm the response field name for the task identifier against the documentation rather than assuming task_id; adapt the extraction line to match.

Keep submit_reference_video returning the ID only. Polling is a separate concern and belongs in its own function.

Handling the Asynchronous Task Lifecycle

Video generation takes time, so the endpoint is asynchronous by design. The submission call returns quickly with a task identifier; the actual work happens afterward. Your integration has to model that, and the simplest correct model has three states: pending or processing (keep waiting), succeeded (fetch the output), and failed (read the error and stop).

Poll the task endpoint on an interval, with a ceiling on total wait time:

import time

def wait_for_task(task_id: str, interval: float = 5.0, max_wait: float = 600.0) -> dict:
    deadline = time.monotonic() + max_wait
    url = f"{BASE_URL}/v1/tasks/{task_id}"
    while time.monotonic() < deadline:
        r = requests.get(url, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError(f"task {task_id} did not finish within {max_wait}s")

Adapt the status strings and the task path to what the documentation specifies — the structure above is the pattern, and most failures in this area come from assuming a status label that does not exist.

Polling etiquette worth adopting early:

  • Back off gradually. A fixed short interval hammers the API for no benefit. Start modest and increase the sleep between attempts.
  • Always bound the loop. A while True around a remote task is an outage waiting to happen. The deadline above raises instead of hanging.
  • Persist the task ID. If your process crashes after submission, the ID is the only way to recover the result without paying for a second generation.
  • Treat failed as terminal. Do not retry a failed task by polling again; read the error and resubmit a corrected payload if appropriate.
  • Handle expiry explicitly. Task results may not be retrievable forever, so download and store the output as soon as the task succeeds.

Common Errors and How to Fix Them

Most first-integration failures fall into a small number of buckets. Match the symptom to the cause before changing code.

Authentication and authorization failures

A 401 or 403 almost always means the credential is wrong, missing, or scoped incorrectly. Check that the header is exactly Authorization: Bearer <key>, that the environment variable is actually populated in the process that made the call (a shell export does not reach a systemd unit), and that the key has not been rotated or revoked.

Reference image problems

If the request is rejected for its images, or generation ignores a reference, the URL is the suspect. Verify the link resolves from outside your machine — an internal hostname or a localhost address is unreachable to the service. Check expiry on signed URLs, check that the file is actually an image and not an HTML error page served with a 200, and check size and format limits. A single bad entry in a multi-image array can fail the whole request, so test references one at a time when debugging.

Invalid payloads

A 400 with a validation message usually means a malformed body: a top-level array instead of an object, a missing required field, reference_images sent as a quoted string instead of an array, or an unrecognized parameter name. Compare your body against the documented schema field by field, and log the exact payload you sent — the bug is frequently a serialization difference between your test and production paths.

Wrong route or method

A 404 generally means the path is wrong, not that the model is unavailable. Recheck the version prefix and the endpoint name against the docs, and confirm you are using POST for submission and GET for task status.

Timeouts and polling mistakes

If submission itself times out, raise your client timeout modestly and retry — but if the task was accepted, do not resubmit blindly, or you will pay for duplicate generations. If polling never terminates, your status check is probably comparing against the wrong strings; log the raw status value on the first few polls and read what actually comes back.

Rate limiting

A 429 means slow down. Honor the interval you are given rather than retrying immediately, and apply exponential backoff with jitter so parallel workers do not synchronize their retries.

Production Checklist Before You Ship

Working code in a notebook is not the same as a reliable integration. Before you put this endpoint in front of users, tighten the operational edges.

  • Configuration. Keep the base URL and API key in environment or secret management, never in source. Make the endpoint path a constant so a version bump is a one-line change.
  • Retries with backoff. Retry transient failures — connection resets, 429s, 5xx — with exponential backoff and jitter. Do not retry 4xx validation errors; they will fail identically.
  • Idempotency discipline. Record every task ID you submit alongside its inputs. On restart, resume polling existing tasks instead of submitting new ones.
  • Bounded waits. Give both the HTTP client and the polling loop explicit timeouts, and route timeouts into a dead-letter path a human can inspect rather than a silent drop.
  • Structured logging. Log the task ID, the status transitions with timestamps, the timing of submission and completion, and the error body on failure. Redact the key and truncate prompts if they contain user data.
  • Output handling. Download generated media to your own storage as soon as a task succeeds, and validate the result before showing it to a user.
  • Cost visibility. Billing follows usage, so track how many tasks you submit per feature and per user. A retry loop that resubmits on ambiguity is the most common cause of surprising spend.
  • Input hygiene. Validate reference URLs and prompt length on your side first. Catching a broken URL locally is faster and cheaper than a round trip.

With those in place, the integration is a thin, predictable layer: build a payload, submit, poll, store. Start from the endpoint reference, run the curl example once, then move the same body into Python — the request that works in the shell will work in your service.

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