Blog

Tutorial

How to Use pixverse-v6-max Image-to-Video via the HiAPI API: curl, Python, and a Working Request

Nov 13, 2026 12 min read
Flat editorial-style cover image: on a deep pine green background, a large prism is cut into blocks of sage green and mist green.
On this page

What the pixverse-v6-max image-to-video endpoint expects

The pixverse-v6-max/image-to-video endpoint on HiAPI is an asynchronous, image-conditioned video generation task. That single sentence shapes almost every decision you will make when integrating it.

The endpoint takes a source image (the first frame) plus a set of generation parameters, and returns a job reference rather than a finished video. The actual rendering happens server-side and can take anywhere from seconds to minutes depending on the parameters you chose. Your client is responsible for submitting the job and then asking about its state until it reports a terminal status.

Contrast this with a synchronous image edit, where you POST a payload and receive the transformed image in the same HTTP response. Here the flow is:

  1. POST your image and parameters to the generation endpoint.
  2. Receive a job identifier (and typically an initial status).
  3. GET the job status at intervals until it is complete or failed.
  4. Read the resulting video URL from the completed job payload.

Because of this split, two separate categories of errors exist: problems with submission (bad auth, malformed payload, rejected image) and problems with execution (a job that fails or stalls after being accepted). Good integrations handle both explicitly — see the troubleshooting section later for a concrete checklist.

One more thing to internalize: the source image is the anchor. The model animates from that first frame, so image quality, aspect ratio, and content all influence the output more than any prompt text you might supply. Treat upload correctness as a first-class concern, not an afterthought.

Getting your API key and endpoint ready

Before your first request you need exactly two things: a HiAPI API key and the correct base URL for the endpoint.

Obtain your key

Create an API key from your HiAPI account dashboard. Treat it like a password: keep it in an environment variable rather than in source code or shell history.

export HIAPI_API_KEY="your_key_here"

If you use a .env file locally, add it to .gitignore before committing anything. Any key that has appeared in a shared log, screenshot, or repository should be rotated immediately.

Know your base URL and path

The endpoint lives under the HiAPI API host, with the model path pixverse-v6-max/image-to-video. In the examples below the base URL is shown as https://api.hiapi.ai and the full path is constructed from it. If your account or region gives you a different host, substitute it consistently — a mismatch between host and key is one of the most common causes of a 401 that developers misread as “bad key”.

Choose your tooling

  • curl for a first smoke test — it removes every variable except the request itself.
  • Python 3 with requests (or httpx) for the real integration.
python3 -c "import requests; print(requests.__version__)"

If that prints a version, you are set. No SDK installation is required for the examples in this post; everything is plain HTTP, which also means you can port it to any language later. Once your key and host are confirmed, you are ready to build the request.

Building the request with curl

Start with the smallest request that can actually succeed, then add parameters. The payload below shows the shape of a complete image-to-video submission.

curl -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://your-cdn.example.com/first-frame.jpg",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

Three things are happening here:

  • Auth is a bearer token in the Authorization header.
  • The body is JSON, so the image is supplied as a URL string (see the next section for how to pass a local file instead).
  • The two generation parameters — duration and aspect_ratio — are top-level fields.

A successful submission returns a JSON object containing a job identifier. Capture it:

JOB_ID=$(curl -s -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image":"https://your-cdn.example.com/first-frame.jpg","duration":5,"aspect_ratio":"16:9"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
echo "$JOB_ID"

Then poll it:

curl -s "https://api.hiapi.ai/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Always inspect the status field and the raw error body on failure. curl will happily print an error JSON while exiting 0, so do not rely on the exit code alone when scripting.

Supplying the first frame image correctly

The source image is the single most common point of failure, and almost every rejection comes down to one of four causes.

1. The image is not reachable

When you pass a URL, HiAPI's servers must be able to GET it — from their network, not yours. A localhost URL, a private bucket, a signed URL that expires in sixty seconds, or an endpoint behind a VPN will all fail. Use a publicly readable object-storage URL or a CDN link, and confirm it loads in a fresh browser session without cookies.

2. The image is not a supported format

Stick to standard web formats — JPEG, PNG, WebP. Files with unusual extensions, HEIC from phones, or animated GIFs are risky. If your pipeline produces something exotic, transcode it first.

3. The first frame does not match the declared aspect ratio

This is the subtle one. If your source image is square but you request 16:9, the service must either crop, pad, or reject the input. Behavior can vary, and none of the three options is what most developers intend. Crop or letterbox the image yourself before uploading so its geometry already matches the aspect_ratio you will request. That makes the output predictable and avoids a wasted job.

4. The image is too large or too small

Extremely high-resolution stills (e.g. 8K camera output) cost bandwidth and may be rejected or downscaled; tiny thumbnails give the model almost nothing to animate. Normalize to a sensible long-edge size as part of your pre-upload step.

Passing a local file

If the endpoint accepts multipart uploads for the image field, the pattern is:

curl -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -F "image=@./first-frame.jpg" \
  -F "duration=5" \
  -F "aspect_ratio=16:9"

Note that with multipart the numeric fields become strings. Check the endpoint reference for which content types are accepted, and prefer the URL form for production pipelines — it keeps large binaries out of your application servers entirely.

Setting duration and aspect ratio

These two fields do more to determine cost and output than anything else in the payload.

duration

duration is expressed in seconds and represents the length of the generated clip. It is also the field most directly tied to billing — real-time pricing is computed on the output duration you request, so pick deliberately rather than defaulting to the maximum. Practical guidance:

  • Start with the shortest duration that tells your story. A 5-second clip is ideal for a loop, a product tease, or a social hook.
  • Use longer durations only when the shot genuinely needs the time; a static first frame animated for a long stretch tends to drift and lose coherence.
  • Validate client-side: reject non-integers, zero, negatives, and absurdly large values before the request leaves your service.
if not isinstance(duration, int) or not 1 <= duration <= 8:
    raise ValueError("duration out of supported range")

Confirm the currently supported range in the endpoint reference and mirror it in your validation — do not hardcode assumptions from this post.

aspect_ratio

aspect_ratio is a string such as "16:9", "9:16", or "1:1". It controls the output frame geometry.

  • 16:9 for landscape: YouTube, web hero videos, desktop playback.
  • 9:16 for portrait: Reels, Shorts, TikTok-style placements.
  • 1:1 for feeds and thumbnails.

Two rules keep you out of trouble. First, match the source image to the requested ratio — a portrait first frame in a landscape request leads to cropping you probably did not intend. Second, treat the ratio as an enum, not free text: validate against a whitelist so a typo like "16x9" fails fast in your code rather than after a round trip.

Everything else

If the endpoint exposes additional generation controls, keep them out of your first request. A minimal, known-good payload is your baseline; add one parameter at a time and diff the output. That discipline makes it obvious which field caused a regression.

The same request in Python

Here is the curl flow translated into Python. It is deliberately dependency-light: requests plus the standard library.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def submit(image_url: str, duration: int = 5, aspect_ratio: str = "16:9") -> str:
    resp = requests.post(
        f"{BASE}/v1/pixverse-v6-max/image-to-video",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"image": image_url, "duration": duration, "aspect_ratio": aspect_ratio},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["id"]

def fetch(job_id: str) -> dict:
    resp = requests.get(f"{BASE}/v1/jobs/{job_id}", headers=HEADERS, timeout=30)
    resp.raise_for_status()
    return resp.json()

if __name__ == "__main__":
    job_id = submit("https://your-cdn.example.com/first-frame.jpg")
    print("submitted", job_id)

A few deliberate choices worth copying:

  • raise_for_status() on submission. A 400 or 401 should surface immediately as an exception, not as a KeyError when you try to read ["id"] from an error body.
  • Explicit timeouts. Without them, a stalled connection hangs your worker indefinitely.
  • Config from environment. The base URL and key are never literals in code.
  • Small typed helpers. submit returns a job id string; fetch returns a dict. Keeping the parsing in one place means a schema change is a one-line fix.

If you prefer httpx, substitute httpx.post(...) and httpx.get(...); the calls are otherwise identical. For anything that runs inside a web request handler, submit here and hand the job id to a background worker rather than blocking the user's HTTP request on video generation.

Polling the async job until it finishes

Polling is the part most tutorials gloss over and most incidents come from. The loop itself is short; the discipline around it is what matters.

def wait_for_video(job_id: str, timeout: int = 600, interval: int = 5) -> str:
    deadline = time.time() + timeout
    while time.time() < deadline:
        job = fetch(job_id)
        status = job.get("status")
        if status == "completed":
            return job["output"]["video_url"]
        if status in ("failed", "cancelled"):
            raise RuntimeError(f"job {job_id} ended as {status}: {job.get('error')}")
        time.sleep(interval)
    raise TimeoutError(f"job {job_id} did not finish within {timeout}s")

The essentials encoded above:

  • Always have a deadline. Video generation is slow; an unbounded loop becomes an unbounded bill and a wedged worker. Ten minutes is a reasonable ceiling for short clips — tune it to your duration settings.
  • Distinguish terminal states. Only completed yields a URL. failed and cancelled are terminal too — stop polling and surface the error field.
  • Use a sane interval. Every few seconds is plenty. Hammering the status endpoint will get you rate-limited and tells you nothing new.
  • Back off gently for long jobs: grow the interval from 3s to 10s after the first minute. It reduces load and costs you nothing in latency.
  • Persist job ids. Store them alongside your own record so that if your process restarts, you can resume polling instead of re-submitting — and re-paying for — the same job.
  • Never poll from the browser directly with your API key. Proxy status checks through your backend.

When a job completes, download the video to your own storage promptly rather than linking to the returned URL forever; generated asset URLs are not guaranteed to be permanent.

Troubleshooting failed and stalled jobs

Work through this checklist in order. Each step isolates one layer.

Submission errors (the job was never created)

  • 401 Unauthorized — key missing, malformed, revoked, or paired with the wrong host. Verify the header is exactly Authorization: Bearer <key> with a single space and no stray newline from your env var.
  • 403 Forbidden — the key is valid but not permitted for this model or endpoint. Check the resource path character for character: pixverse-v6-max/image-to-video.
  • 400 Bad Request — your JSON is malformed or a field is invalid. Decode the error body; it usually names the offending field. Common culprits: duration as a string instead of a number, "16x9" instead of "16:9", a missing image.
  • 422-style validation errors — the fields are present but out of range. Compare against the endpoint reference rather than guessing.
  • 429 Too Many Requests — you are submitting too fast. Queue submissions and retry with exponential backoff plus jitter; never retry in a tight loop.

Execution failures (the job was created but did not succeed)

  • Status failed with an image-related error — the fetch of your source URL failed after submission. This is the classic “worked in my browser” trap: the URL required cookies, a referrer, or an IP allowlist. Re-host the image publicly.
  • Status failed with a content or validation error — the source image was rejected on technical grounds (format, geometry, size). Transcode, resize, and re-crop to the declared aspect ratio.
  • Job stuck in a queued or processing state past your deadline — first confirm you are reading the correct job id (a copy-paste error is embarrassingly common). Then check whether the status is genuinely unchanged or whether your poll is hitting the wrong base URL. If it truly is stalled, cancel if the API allows it and resubmit once; repeated silent resubmission is how budgets disappear.

A habit that saves time

Log the full request id, job id, HTTP status, and response body for every call — redacting the key. When something breaks at 2 a.m., a request id is the difference between a five-minute fix and an hour of speculation. Start with a minimal known-good payload, add one parameter at a time, and you will rarely need this checklist at all.

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