Tutorial
How to Use pixverse-v6-max/text-to-video via the HiAPI API: curl, Python, and a Working Request
On this page
What this endpoint does and when to use it
pixverse-v6-max/text-to-video is a text-to-video endpoint on HiAPI. You send a text prompt describing the scene you want, and the endpoint returns a rendered video. Because video generation takes time, the endpoint is asynchronous: your initial request does not return a video directly. Instead, it returns a task identifier that you use to check progress and retrieve the finished result.
That request/acknowledge/poll shape is the core mental model for everything in this tutorial. Internally, the flow is always the same:
- Submit a generation job with your prompt and parameters.
- Receive a task identifier immediately.
- Poll the task until it reports completion (or failure).
- Download or embed the resulting video URL.
When this endpoint fits
Reach for pixverse-v6-max/text-to-video when you have a description and no source footage — a product teaser from a written brief, a background clip for an app, a storyboard preview. If you already have an image and want it animated, that is an image-to-video workflow, not this endpoint. If you want the model to iterate on a prompt conversationally, that is a different surface. This endpoint is the direct, single-shot path from text to video.
Because generation is async, it also fits queue-based architectures: a web backend accepts a user request, submits the job, and lets a worker poll and deliver the result later. Nothing about the call blocks for the full render time.
Before you start: auth and request basics
Before writing any code, confirm three things.
1. An API key
Every HiAPI request is authenticated with an API key. Treat it like a password: keep it out of source control, load it from an environment variable, and rotate it if it leaks. In the examples below we read it from HIAPI_API_KEY, so export it in your shell first:
export HIAPI_API_KEY="your_key_here"
2. The correct base URL
All requests go to the HiAPI API base URL, with the endpoint path appended. Use the base URL documented in your HiAPI account rather than hardcoding a host from a blog post — if you are unsure, check the API reference in your dashboard. The examples below use $HIAPI_BASE_URL as a placeholder for that value.
3. JSON conventions
Both submission and status checks are JSON over HTTPS:
- Send
Content-Type: application/jsonon every request that carries a body. - Send
Authorization: Bearer $HIAPI_API_KEYon every request, including status checks. - Expect JSON back, including on errors — read the error body, not just the HTTP status.
A quick sanity check
If you have a lightweight endpoint available (for example, a models or account route), call it once before touching the video endpoint. A 200 there proves your key, base URL, and header formatting are all correct, which removes three variables from later debugging.
A working curl request
Here is the full submission call. The endpoint path is pixverse-v6-max/text-to-video; the body carries your prompt and generation parameters.
curl -sS -X POST "$HIAPI_BASE_URL/pixverse-v6-max/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A slow dolly shot through a rain-soaked neon alley at night, cinematic",
"duration": 5,
"aspect_ratio": "16:9"
}'
Field by field
prompt— the text description. Be specific about subject, motion, camera movement, and mood. This is the single biggest lever on output quality.duration— requested clip length. See the duration and aspect ratio section below.aspect_ratio— the output frame shape, e.g.16:9,9:16,1:1.
What comes back
A successful submission returns a JSON object containing a task identifier — the handle you use for polling. The exact field name is documented in the API reference; in this tutorial we call it task_id. Capture it:
TASK_ID=$(curl -sS -X POST "$HIAPI_BASE_URL/pixverse-v6-max/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"A slow dolly shot through a rain-soaked neon alley at night, cinematic","duration":5,"aspect_ratio":"16:9"}' \
| python -c 'import sys,json; print(json.load(sys.stdin)["task_id"])')
echo "$TASK_ID"
Note what the response does not contain: the video. Generation runs in the background. Treat the submission response as a receipt, not a result.
The same request in Python
The Python version mirrors the curl call exactly. We use requests for brevity, but httpx or urllib work identically — the only requirements are the same headers and JSON body.
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"prompt": "A slow dolly shot through a rain-soaked neon alley at night, cinematic",
"duration": 5,
"aspect_ratio": "16:9",
}
resp = requests.post(
f"{BASE_URL}/pixverse-v6-max/text-to-video",
headers=headers,
json=payload,
timeout=30,
)
if resp.status_code >= 400:
# Surface the server's error body — it usually names the bad field
raise RuntimeError(f"submit failed {resp.status_code}: {resp.text}")
data = resp.json()
task_id = data["task_id"]
print("submitted:", task_id)
Points worth copying
json=payloadserializes the body and sets the content type for you. If you instead passdata=json.dumps(payload), keep the explicitContent-Typeheader.- A client timeout on submission guards against a stalled connection. It does not limit generation time — that happens server-side, which is exactly why polling exists.
- Check status codes before parsing. A 4xx response body is often more informative than the status alone; print it.
- Never log the API key. Log the
task_idinstead — it is safe to store and is your debugging handle.
Duration and aspect ratio parameters
These two fields are the most common source of rejected requests, so it is worth being deliberate about them.
duration
duration sets the requested clip length in seconds. The value you may request is bounded by what the endpoint supports; sending a value outside that set typically produces a parameter validation error rather than a silently clamped clip. Pick from the supported values documented in the API reference, and keep it as an integer. Longer clips take longer to render, so during development prefer the shortest supported duration — you are validating plumbing, not cinematography.
aspect_ratio
aspect_ratio is a string of the form W:H. Match it to where the video will live:
16:9— landscape: web heroes, YouTube-style players, desktop backgrounds.9:16— portrait: short-form mobile feeds and stories.1:1— square: grid layouts and thumbnails.
Choosing the wrong shape here is cheap to fix but expensive to discover late: re-rendering costs another full generation cycle, so decide the target surface before you submit.
What to check when they are rejected
- Type mismatch —
durationas a string ("5") instead of a number, oraspect_ratioas two numbers. Keep duration numeric and aspect ratio a string. - Unsupported value — a duration or ratio outside the documented set. Compare against the reference list exactly.
- Field naming — a typo like
aspectRatioordurationSecondsis silently treated as an unknown field at best. Copy field names from the reference.
A quick way to isolate the culprit: resubmit with only prompt, then add each parameter back one at a time. The first rejection identifies the offending field.
Polling the async task until the video is ready
Polling is a loop with three rules: check status, sleep, stop on a terminal state. Add a ceiling so a stuck task cannot spin forever.
import time
import requests
def wait_for_video(task_id, base_url, api_key, timeout=600):
headers = {"Authorization": f"Bearer {api_key}"}
url = f"{base_url}/tasks/{task_id}" # status route per API reference
deadline = time.time() + timeout
delay = 2
while time.time() < deadline:
r = requests.get(url, headers=headers, timeout=30)
r.raise_for_status()
task = r.json()
status = task["status"]
if status == "succeeded":
return task["result"]["video_url"]
if status == "failed":
raise RuntimeError(f"generation failed: {task.get('error')}")
time.sleep(delay)
delay = min(delay * 1.5, 15) # gentle backoff, capped
raise TimeoutError(f"task {task_id} not finished in {timeout}s")
Why backoff matters
A fixed one-second poll against a generation job that takes a minute is dozens of wasted requests. Start small and grow — the capped multiplier above settles at a comfortable interval without hammering the API. If you are running many jobs, a queue plus a single polling worker is friendlier than one loop per request.
Handling the result
Once the task succeeds, the response carries the video URL. Fetch it promptly and copy it to your own storage if the result needs to persist — signed URLs are not permanent. Check the content type and size on download before handing the file to users, and record the task_id alongside the stored asset so any future question can be traced back to the exact generation.
Troubleshooting common errors
Work down this list when a call fails. Most failures land in one of four buckets.
Authentication and access
- 401 / unauthorized — key missing, malformed, or not sent. Confirm the header is exactly
Authorization: Bearer <key>and that the environment variable is actually populated in the shell or process making the call. - 403 / forbidden — the key is valid but not permitted for this endpoint. Check the key's scope in your dashboard.
Request validation
- 400 / 422 — malformed JSON or a bad field value. Print the full error body; it usually names the field. Recheck
durationtype andaspect_ratiostring format. - 404 on submit — the endpoint path is wrong. Confirm the path is exactly
pixverse-v6-max/text-to-videoand that your base URL has no duplicated or missing path segment.
Task-level failures
- Status
failed— the job was accepted but generation failed. Read the error message on the task; it distinguishes a content rejection from an internal failure. A rejected prompt is a prompt problem, not an API problem — revise and resubmit. - Stuck in a running state — cap your polling deadline and treat a timeout as a failure you handle, not an exception that takes your service down.
Operational issues
- 429 / rate limited — too many submissions or polls in flight. Reduce concurrency and honor any retry hint in the response.
- Connection timeouts on submit — network or proxy issue, not generation. Retry the submission with backoff, but only if you can tolerate a possible duplicate job.
- Video URL 404 on download — the URL has expired. Re-fetch the task result rather than reusing an old URL.
A repeatable habit
Log three values on every failure: HTTP status, the response body, and the task_id if you have one. Those three turn "it broke" into "it broke here," which is the only thing that makes debugging fast.
Where to go next
You now have the complete loop: authenticate, submit, capture the task identifier, poll with backoff, and fetch the result. To productionize it, wrap submission and polling in a small client class, store task_id and prompt alongside every asset for traceability, and move polling to a background worker so user-facing requests never block on a render.
From here, explore the adjacent endpoints in the HiAPI reference — image-to-video for animating existing stills, and prompt-iteration surfaces for refining a look before you commit to a full generation. The request shape you learned here carries over almost unchanged.
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