Tutorial
How to Call the veo-3.1 Text-to-Video API: curl and Python Examples
A hands-on integration walkthrough for developers
On this page
What veo-3.1/text-to-video gives you
veo-3.1/text-to-video is a text-to-video generation model exposed through HiAPI's unified API. You send a text prompt, choose a few output options, and receive a generated video. It sits alongside other generation endpoints on HiAPI, so if you already use the platform for images or chat, the integration pattern will feel familiar: an authenticated HTTP request returns a job you poll until it's complete.
This endpoint is the right choice when you have a written description of a scene and want a short video clip without managing any infrastructure. You don't need to handle GPU allocation, model weights, or queueing yourself. The trade-off is that generation is asynchronous: you submit a job, then check back for the result. That's normal for video, since rendering takes longer than a single request/response cycle.
Use text-to-video when the core input is a prompt. If you later need image-conditioned or video-conditioned generation, check the model catalog for the matching endpoint. The request shape here (auth, job submission, polling) is the same pattern you'll reuse across HiAPI's media endpoints, so learning it once pays off. You can find the full model details on the veo-3.1/text-to-video model page.
Endpoint, auth, and request shape
All HiAPI requests use HTTPS and a bearer token. Store your API key in an environment variable rather than hardcoding it, and send it in the Authorization header:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
A text-to-video request is a JSON object with a model field and an input object. The input object holds the prompt and any output controls. A minimal body looks like this:
{
"model": "veo-3.1/text-to-video",
"input": {
"prompt": "A slow dolly shot through a rain-soaked neon alley at night"
}
}
The response is a job envelope rather than the finished video. It typically includes a job identifier, a status field, and timestamps. Expect something shaped like:
{
"id": "job_abc123",
"status": "queued",
"created_at": "2025-01-01T00:00:00Z"
}
Treat the exact field names as the source of truth from a live response, but the structure is consistent: you need the id to poll, and the status tells you whether the job is queued, running, or finished. Don't assume a job is done just because the submit call returned 200 — that only means the job was accepted.
Choosing parameters: native audio and resolution tiers
Beyond the prompt, the parameters that matter most for text-to-video are whether to generate native audio and which resolution tier to target. Both affect generation time and the nature of the output, so make these choices deliberately rather than defaulting blindly.
Native audio
Some video models can generate an audio track alongside the visuals. If the endpoint exposes a native audio toggle, enabling it means the generated clip includes synchronized sound. This is useful for scenes where audio is part of the experience — ambient noise, music, or effects that match the action. If you plan to add your own soundtrack or voiceover in post, leave it off to keep the output focused on visuals. Audio generation also adds processing time, so only enable it when you actually need it.
Resolution tiers
Resolution tiers let you trade off visual fidelity against cost and latency. Higher tiers produce sharper output but take longer and consume more resources. Pick the lowest tier that meets your delivery target: a draft tier for iteration and review, and a higher tier for the final render. If you're generating many candidates from one prompt, use a lower tier to explore, then regenerate the winner at full quality. Billing follows the output you generate, so choosing a tier deliberately is the main lever you control.
When you're unsure which values the endpoint currently accepts, send a request with only the prompt and inspect the response or error message. HiAPI returns structured validation errors that list the accepted fields, so you can adjust without guessing.
A working curl request
This curl command submits a text-to-video job. It sets the JSON content type, passes the bearer token from your environment, and sends a body with the model and input.
curl -X POST https://api.hiapi.ai/v1/videos/generations \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "veo-3.1/text-to-video",
"input": {
"prompt": "A slow dolly shot through a rain-soaked neon alley at night",
"duration": 5,
"resolution": "720p"
}
}'
A successful call returns a JSON object containing the job id and a status. Capture that id — you'll need it for polling. If you're scripting this, pipe the output through a JSON processor to extract the id:
JOB_ID=$(curl -s -X POST https://api.hiapi.ai/v1/videos/generations \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"veo-3.1/text-to-video","input":{"prompt":"A slow dolly shot through a rain-soaked neon alley at night"}}' \
| jq -r '.id')
echo "$JOB_ID"
Adjust the endpoint path, parameter names, and any optional fields to match what the live API expects. The pattern — POST a JSON body, read the id from the response — is what every subsequent example builds on.
The same request in Python
The Python version does the same thing with the standard requests library. Read the key from the environment, build the payload, and post it.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": "veo-3.1/text-to-video",
"input": {
"prompt": "A slow dolly shot through a rain-soaked neon alley at night",
},
}
response = requests.post(
f"{BASE_URL}/videos/generations",
headers=headers,
json=payload,
timeout=60,
)
response.raise_for_status()
job = response.json()
job_id = job["id"]
print(f"submitted job: {job_id} (status: {job.get('status')})")
Two things are worth calling out. First, response.raise_for_status() turns HTTP errors into exceptions, which makes failures visible immediately instead of silently passing a broken payload around. Second, timeout=60 prevents a hung connection from blocking your script. The submission itself is quick; the actual video renders asynchronously, so you won't wait for the file here. Next, you'll poll for completion using the job_id.
Polling an async job until the video is ready
After submission, poll the job endpoint until the status indicates completion or failure. A simple loop with a short sleep works fine to start.
import time
while True:
res = requests.get(
f"{BASE_URL}/videos/generations/{job_id}",
headers=headers,
timeout=30,
)
res.raise_for_status()
state = res.json().get("status")
print(f"status: {state}")
if state == "succeeded":
video_url = res.json().get("output", {}).get("url")
print(f"video ready: {video_url}")
break
if state == "failed":
raise RuntimeError(f"job failed: {res.json()}")
time.sleep(5)
A few practical refinements: start with a short interval and back off gradually to reduce wasted requests; add a maximum number of attempts or a deadline so a stuck job doesn't loop forever; and treat any unexpected status carefully rather than assuming it means "keep waiting." Common status values include queued, running, succeeded, and failed. When the job succeeds, the response usually carries the output URL; download and store the file promptly, since signed URLs may expire.
Make polling idempotent and log the job id with each status. If your process restarts, you can resume by id instead of resubmitting. For production, consider a webhook if the platform offers one, falling back to polling.
Troubleshooting common errors
Most failures fall into a handful of categories. Work through this checklist in order instead of retrying blindly.
Authentication failures (401/403)
Check that the Authorization header is present and correctly formatted as Bearer <key>, and that the environment variable is actually set in the shell or process making the request. A common trap is running a script in an environment where the key exists in one shell but not another.
Validation errors (400/422)
These return structured details about which field is wrong. Common causes: a missing prompt, an unsupported resolution or duration value, or a parameter in the wrong nesting level. Read the error message literally — it usually names the offending field. Send a minimal payload first, then add parameters one at a time.
Rate limiting (429)
You're sending requests too fast. Implement exponential backoff and a retry cap. If you're launching many jobs, stagger submissions and keep track of in-flight jobs.
Timeouts and network errors
Short client timeouts on submission are rarely the job's fault — the job runs server-side. Use a sensible timeout on both submit and poll requests, and retry idempotent GETs. Never retry a POST blindly without checking whether the original job was created.
Jobs that never finish
If a job stays queued or running far longer than expected, check status codes and messages rather than resubmitting. Long prompts or higher resolution tiers take longer; that's expected. If the job reports failed, log the full response body — the error message usually points to the cause.
When in doubt, reproduce with the smallest possible request and inspect every response. That beats changing several parameters at once and guessing which one mattered. For endpoint-specific details, refer to the model page.
Related articles
View all articles →-
Tutorial
kling-image-4.0 Real-World Use Cases: 5 High-Value Applications and Integration Essentials
-
Tutorial
How to Call gemini-omni-1.1-flash via the HiAPI API: curl and Python Guide
10 min read -
Tutorial
How to Use qwen-image-2.0-pro via the HiAPI API: curl, Python, and a Working Request
A hands-on integration walkthrough for developers: first successful call, request anatomy, and troubleshooting
8 min read