Veo 3.1 API Guide: Your First Video in 5 Minutes

TL;DR

• Veo 3.1 is Google's video generation model. On HiAPI it comes in three tiers, standard, Fast and Lite, each with text-to-video and image-to-video endpoints. Open the model page to generate in the browser; new accounts get 200 free credits.
• Billing is per second: Lite at 720p without sound is $0.06, Fast at 720p/1080p with sound is $0.25, and standard is $0.57. A 4-second Lite draft costs $0.24.
• The API is two calls: POST /v1/tasks to submit, then poll with the taskId. The curl and Python below run as-is.

What Veo 3.1 does

• Native sound: picture and audio are generated together, so ambience, effects and action sounds follow what's on screen. generate_audio is on by default; turning it off is cheaper.
• 4, 6 or 8 seconds, in 16:9 landscape or 9:16 portrait.
• Up to 4K: standard and Fast support 720p, 1080p and 4K; Lite supports 720p and 1080p.
• Image-to-video: pass one image as the first frame and the model animates it; the aspect ratio can follow the source image.

This 6-second vertical 1080p clip came from one sneaker product photo and a single request. The landing thud and the bass pulse were generated by the model:

VIDEO

The sneaker slowly rotates about 90 degrees as the camera pushes in from a low angle. Dust particles drift through the rim light. The shoe settles onto the wet stone pedestal with a deep, satisfying thud, sending a soft ring of mist rolling off the edges. A warm light sweep travels across the suede texture. Subtle bass-heavy electronic pulse builds in the background with a low whoosh on the landing. Cinematic product commercial, smooth stabilized motion, no text overlays.

Open the model page with this prompt → (upload a 9:16 product photo first)

veo-3.1/image-to-video, 1080p, 6 seconds, with sound, $3.42, about 115 seconds from submit to finish.

Which tier to use

All prices are per second. An 8-second clip with sound costs $1.12 on Lite at 1080p, $2.00 on Fast and $4.56 on standard. For the full breakdown, see Veo 3.1 API pricing; for a same-prompt test of the two cheaper tiers, see Veo 3.1 Fast vs Veo 3.1 Lite.

Two ways to start

In the browser (no code)

1. Open the Veo 3.1 Lite text-to-video model page and sign in.
2. Paste a prompt, pick duration, resolution and aspect ratio, and choose whether you want sound.
3. Click generate and download the clip when it's done.

Through the API

1. Create an API key in the dashboard.
2. POST https://api.hiapi.ai/v1/tasks to submit; you get a taskId back.
3. GET /v1/tasks/{taskId} to check status; when status is success, download the video from output[0].url.

curl: your first clip

Start with Lite at 4 seconds, 720p, no sound, for $0.24:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-lite/text-to-video",
    "input": {
      "prompt": "A matte-black wireless earbud case slowly rotates on a reflective black surface under a single overhead spotlight.",
      "duration": 4,
      "resolution": "720p",
      "aspect_ratio": "9:16",
      "generate_audio": false
    }
  }'

Response:

{"code": 200, "data": {"taskId": "tk-hiapi-..."}, "message": "success"}

Check the result:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer $HIAPI_KEY"

Python: submit, poll, download

# pip install requests; export HIAPI_KEY=your-key first
import os, time, uuid, requests

KEY = os.environ["HIAPI_KEY"]
H = {"Authorization": f"Bearer {KEY}"}

def generate(prompt, model="veo-3.1-lite/text-to-video", timeout_s=900, **params):
    body = {"model": model, "input": {"prompt": prompt, **params}}
    # Reuse the same Idempotency-Key when retrying a submit, so a retry never bills twice
    headers = {**H, "Idempotency-Key": str(uuid.uuid4())}
    r = requests.post("https://api.hiapi.ai/v1/tasks", json=body, headers=headers, timeout=30)
    r.raise_for_status()
    res = r.json()
    if res.get("code") != 200:
        raise RuntimeError(res)
    task_id = res["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)
    raise TimeoutError(task_id)

url = generate(
    "A barista pours hot water in a slow spiral over ground coffee, steam rising in morning light",
    duration=4, resolution="720p", aspect_ratio="16:9", generate_audio=True,
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

Once the prompt works, switch model to veo-3.1-fast/text-to-video or veo-3.1/text-to-video for the final render; everything else stays the same.

Image-to-video

Change the model to …/image-to-video and add one image in input (image_url is a string and takes exactly one image):

{
  "model": "veo-3.1/image-to-video",
  "input": {
    "prompt": "The sneaker slowly rotates and settles onto the wet stone pedestal with a deep thud",
    "image_url": "https://your-cdn.example.com/sneaker-916.jpg",
    "aspect_ratio": "auto",
    "resolution": "1080p",
    "duration": 6
  }
}

• aspect_ratio: "auto" follows the source image; you can also force 16:9 or 9:16, and other image shapes get cropped.
• Use a source image of 720p or larger, ideally 16:9 or 9:16. SVG isn't supported.
• Write the prompt about what happens next, not a fresh description of the whole image.

Before you ship

• Use a callback instead of polling: add "callback": {"url": "https://your-domain/hiapi/callback"} at the top level of the request, and HiAPI notifies you when the task ends. Deduplicate by taskId.
• Store outputs right away: output[0].url is temporary, so copy it to your own storage as soon as you get it.
• Set every parameter: duration defaults to 8 seconds, and resolution is required on standard and Fast. Set duration, resolution and generate_audio explicitly so the bill matches your budget.
• Turn sound off when you don't need it: with generate_audio: false, Lite 720p drops from $0.10 to $0.06 per second, and standard from $0.57 to $0.29.
• Failed tasks are refunded: you pay only for clips that generate successfully.

FAQ

Can I write prompts in other languages?

Yes. Prompts in English and Chinese both work. Writing camera, action and sound as separate sentences gives the most consistent results.

Can I generate a 10-second clip?

Not in one request; durations are 4, 6 or 8 seconds. For longer pieces, generate segments and edit them together.

Can I control the sound separately?

Describe each layer of sound in the prompt (close action sounds, background voices, wind) and the model generates them; to drop sound entirely, set generate_audio to false.

I tuned a prompt on Lite. What changes for standard?

Only the model name. prompt, duration, aspect_ratio and generate_audio carry over; set resolution to 4k if you want 4K (Lite has no 4K).

For more prompt examples, open the sneaker prompt above on the image-to-video model page, or compare all three tiers in Veo 3.1 API pricing.