Skip to content
HiAPI Docs
HiAPI
Playground Get API Key
English
English 中文

Veo 3.1 Text to Video API

POST /v1/tasks

All models are called through the Unified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).

Model summary

Model name veo-3.1/text-to-video
Type Video generation (text-to-video)
Endpoint POST /v1/tasks
Pricing See HiAPI Pricing

Google Veo 3.1 flagship text-to-video API with cinematic quality and native audio, up to 4K resolution, generating 4 / 6 / 8-second clips for ad-grade shorts and demanding creative work.

Production guidance

Production guidance
  • For production, pass callback.url at the top level of the request body so HiAPI can notify your service when the task reaches a terminal state.
  • GET /v1/tasks/:id is better for local debugging, low-volume jobs, or fallback reconciliation if a callback is missed.
  • Use callback.when=final. Both success and fail are terminal states, so your service should deduplicate by taskId.

Best suited for

Cinematic footage

The flagship Veo 3.1 tier delivers top-tier visual quality, motion realism, and lighting consistency for ads, brand films, and narrative shots.

promptresolution
Narrative clips with native audio

Generate visuals and native audio (ambience/effects/score) in one call with synchronized sound.

generate_audio
Up to 4K delivery

Supports 720p / 1080p / 4K so you can pick the resolution your placement needs.

resolutionduration
Landscape and portrait

One prompt adapts to 16:9 feeds and 9:16 vertical shorts.

aspect_ratio

Request parameters

model string required

Fixed value veo-3.1/text-to-video.

example veo-3.1/text-to-video
input object required

Business parameters. Put Veo 3.1 Text to Video-specific configuration here.

prompt string required

Text prompt describing the video to generate.

aspect_ratio enum optional

Output video aspect ratio.

default 16:9 enum: 16:99:16
resolution enum required

Output video resolution. Higher resolution costs more.

default 720p enum: 720p1080p4k
duration enum required

Clip length in seconds. Cost scales with duration.

default 8 enum: 468
generate_audio boolean optional

Generate a native audio track. Pricing is higher when enabled.

default true
negative_prompt string optional

Describe what to avoid in the generated video.

seed integer optional

Random seed for reproducible generation.

callback object optional

Optional callback configuration. When set, HiAPI notifies your service when the task reaches a terminal state.

url string required

Required when callback is set; HTTPS URL that receives terminal task notifications.

example https://your-domain.com/hiapi/callback
when enum optional

Callback trigger timing. Use final.

default final enum: final

Example requests

4K cinematic clip with audio

4K / 8s with native audio — the flagship tier at full quality.

Request body
{
  "model": "veo-3.1/text-to-video",
  "input": {
    "prompt": "A surfer rides inside a massive turquoise barrel wave, sunlight bursting through the crest, tracking shot, roaring ocean sound",
    "aspect_ratio": "16:9",
    "resolution": "4k",
    "duration": 8,
    "generate_audio": true
  }
}
1080p narrative mood shot

1080p / 8s with audio for narrative, music-driven scenes.

Request body
{
  "model": "veo-3.1/text-to-video",
  "input": {
    "prompt": "A saxophonist plays a soulful solo under an amber spotlight in a dim jazz bar, rain on the window, neon glow",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 8,
    "generate_audio": true
  }
}
720p silent draft (lowest cost)

720p / 4s with audio off — the cheapest tier for creative validation.

Request body
{
  "model": "veo-3.1/text-to-video",
  "input": {
    "prompt": "Raindrops racing down a window pane at night, neon bokeh lights shifting, macro static shot",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 4,
    "generate_audio": false
  }
}

Getting the result

  1. The response returns a taskId immediately without waiting for generation to finish.
  2. In production, prefer waiting for callback.url to receive the terminal notification. For local debugging, poll GET /v1/tasks/:id.
  3. When status=success, download the generated video from output[].url.
  4. When status=fail, fix the request based on the returned error instead of retrying the same invalid payload.

FAQ

What is the difference between Veo 3.1 and Veo 3.1 Fast?

veo-3.1 is the flagship quality tier with better detail, motion realism, and audio quality at a higher price. veo-3.1-fast generates faster at a lower price. Both share the same parameters (720p/1080p/4K, 4/6/8 seconds, native audio), so you can switch based on quality vs. cost.

Which resolutions and durations are supported?

Resolutions 720p / 1080p / 4K and durations 4 / 6 / 8 seconds. Pricing is billed by resolution, audio, and duration (per second); 4K and audio cost more. See the live pricing page. View pricing

How does generate_audio affect price?

Native audio (generate_audio=true, on by default) costs more per second. Set it to false when you do not need sound to reduce cost. See the pricing page for rates. View pricing

How do I get the generated video?

The response returns a taskId immediately. When the task reaches a terminal state, download the video from output[].url. In production, pass callback.url at the top level to receive terminal notifications.

Next steps