Tutorial
How to Use pixverse-v6-max Image-to-Video via the HiAPI API: curl, Python, and a Working Request
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:
POSTyour image and parameters to the generation endpoint.- Receive a job identifier (and typically an initial status).
GETthe job status at intervals until it is complete or failed.- 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(orhttpx) 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
Authorizationheader. - 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 —
durationandaspect_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:9for landscape: YouTube, web hero videos, desktop playback.9:16for portrait: Reels, Shorts, TikTok-style placements.1:1for 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. A400or401should surface immediately as an exception, not as aKeyErrorwhen 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.
submitreturns a job id string;fetchreturns 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
completedyields a URL.failedandcancelledare 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 exactlyAuthorization: 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:durationas a string instead of a number,"16x9"instead of"16:9", a missingimage.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
failedwith 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
failedwith 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 →-
Tutorial
gpt-6.2-sol in Practice: 5 High-Value Uses of a Text Model in Business
-
Tutorial
gpt-6.2-astra Practical Guide: Integration and Implementation Key Points for 5 High-Value Text Scenarios
A Developer's Checklist from Scenario Selection to Engineering Implementation
-
Tutorial
Tripo H3.1 Practical Application Scenarios: 5 High-Value Use Cases and Implementation Essentials
From text-to-3D to multiview reconstruction: choosing the right mode and parameters by business scenario