HiAPI
Blog

Tutorial

How to Call the veo-3.1 Text-to-Video API: curl and Python Examples

A hands-on integration walkthrough for developers

Nov 17, 2026 8 min read
Flat faceted mineral cross-section cover art in deep petrol, teal and malachite tones for the veo-3.1 text-to-video API tutorial.
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 →

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