API DocsAI Model APIsVideos

Veo 3.1 Video Generation

Veo 3.1 is Google's latest-generation video creation model, supporting text and image inputs, up to 4K resolution output, and native synchronized speech and sou

Veo 3.1 Video Generation

Veo 3.1 is Google's latest-generation video creation model, supporting text and image inputs, up to 4K resolution output, and native synchronized speech and sound effect generation. AutoRouter exposes it through the unified /v1/video/generations async task endpoint.

Veo 3.1 uses an async task-based API: submit a request, receive a task_id, poll for status, then download the video from data.url.


1. Supported Models

Model IDVersionStrengthsBest For
veo-3.1-generate-001Veo 3.1Highest quality, 4K support, native audioHigh-quality creative content, commercial production
veo-3.1-fast-generate-001Veo 3.1 FastFaster speed, balanced qualityRapid iteration, batch generation
veo-3.1-lite-generate-001Veo 3.1 LiteFastest speed, lowest costPrototyping, high-volume testing

All 3 models share the same endpoint, differentiated only by the model field. All support text-to-video, image-to-video, and optional audio generation.


2. Common Endpoints

2.1 Submit Task

POST /v1/video/generations

Request Headers

HeaderRequiredDescription
AuthorizationBearer sk-YourApiKey
Content-Typeapplication/json

Request Body Fields

FieldTypeRequiredDescription
modelstringVeo 3.1 model ID (see table above)
promptstringVideo description; English recommended for best results
sizestringResolution: 720p / 1080p / 4000 (4K, standard model only). Default: 1080p
durationintVideo duration in seconds: 4 / 6 / 8. Default: 8
generate_audioboolGenerate synchronized audio (speech, sound effects, ambient sound). Default: false
imagesstring[]Image-to-video reference image URL(s); the model generates motion starting from this image. Supports first-frame or last-frame by specifying lastFrameImage
negative_promptstringNegative prompt describing content to exclude
aspect_ratiostringAspect ratio: 16:9 / 9:16. Default: 16:9
seedintRandom seed to improve reproducibility
lastFrameImagestringLast-frame image URL; when images is provided, specifies the image as the last frame (model generates transition from the first image)
input_referencestring(Legacy) First-frame image URL for image-to-video, equivalent to images[0]

generate_audio: true roughly doubles the cost. Enable only when audio is needed. See Section 6 for pricing details.

Response

{
  "id": "task_DduhCcHShyasO6lCV7o5SK9JQEYUnO1j",
  "task_id": "task_DduhCcHShyasO6lCV7o5SK9JQEYUnO1j",
  "object": "video",
  "model": "veo-3.1-generate-001",
  "status": "queued",
  "progress": 0,
  "created_at": 1778590105
}

2.2 Query Task Status

GET /v1/video/generations/{task_id}

The response uses AutoRouter's unified {code, message, data} wrapper format.

Response (Completed / succeeded)

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_DduhCcHShyasO6lCV7o5SK9JQEYUnO1j",
    "status": "succeeded",
    "error": null,
    "format": "mp4",
    "metadata": null,
    "url": "https://autorouter.top/v1/videos/task_DduhCcHShyasO6lCV7o5SK9JQEYUnO1j/content"
  }
}

Response (Failed / failed)

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_DduhCcHShyasO6lCV7o5SK9JQEYUnO1j",
    "status": "failed",
    "error": "SafetyFilterActivated: prompt violates content policy",
    "format": null,
    "metadata": null,
    "url": null
  }
}

Status Enum

StatusDescription
queuedSubmitted, waiting to start
processingGenerating
succeededCompleted; data.url contains the video download URL
failedFailed; data.error contains details

data Fields

FieldTypeDescription
task_idstringTask ID
statusstringTask status
errorstring / nullFailure reason; null on success
formatstring / nullOutput format (e.g., mp4); null while processing or on failure
metadataobject / nullAdditional metadata
urlstring / nullVideo download URL; null while processing or on failure

The video download URL (data.url) is a temporary signed link, valid for 24 hours. Download or transfer to your own storage immediately.


3. OpenAI-Compatible Endpoints (Optional)

In addition to /v1/video/generations, Veo 3.1 also supports OpenAI-style /v1/videos endpoints. Both are fully equivalent.

Submit: POST /v1/videos (identical request body fields)

Query: GET /v1/videos/{task_id} returns OpenAI flat format:

{
  "id": "task_DduhCcHShyasO6lCV7o5SK9JQEYUnO1j",
  "object": "video",
  "model": "veo-3.1-generate-001",
  "status": "completed",
  "progress": 100,
  "created_at": 1778590105,
  "completed_at": 1778590201
}

The OpenAI-compatible query endpoint does not return the video URL. Use /v1/video/generations/{task_id} and get the download URL from data.url.


4. Full Request Examples

# Step 1: Submit task
curl -X POST https://autorouter.top/v1/video/generations \
  -H "Authorization: Bearer sk-YourApiKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-001",
    "prompt": "A golden retriever playing fetch on a sunny beach, cinematic wide shot, slow motion",
    "size": "1080p",
    "duration": 8,
    "aspect_ratio": "16:9"
  }'

# Step 2: Poll (recommended interval: 10~15 seconds)
curl https://autorouter.top/v1/video/generations/task_DduhCcHShyasO6lCV7o5SK9JQEYUnO1j \
  -H "Authorization: Bearer sk-YourApiKey"

# Step 3: When data.status == "succeeded", download from data.url
curl -o output.mp4 "https://autorouter.top/v1/videos/task_DduhCcHShyasO6lCV7o5SK9JQEYUnO1j/content"
# Enable generate_audio: true for synchronized speech, sound effects, and ambient sound
curl -X POST https://autorouter.top/v1/video/generations \
  -H "Authorization: Bearer sk-YourApiKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-001",
    "prompt": "A jazz musician performing on a rainy street at night, neon lights reflecting on wet pavement",
    "size": "1080p",
    "duration": 8,
    "generate_audio": true
  }'

Enabling audio roughly doubles the cost. Veo 3.1 standard, 1080p, 8s with audio = 1,360,000 quota.

# Pass a reference image via images
# The model generates motion starting from this image
curl -X POST https://autorouter.top/v1/video/generations \
  -H "Authorization: Bearer sk-YourApiKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-001",
    "prompt": "The cat slowly opens its eyes and stretches, sunlight streaming through the window",
    "images": ["https://example.com/cat.jpg"],
    "size": "1080p",
    "duration": 8
  }'
curl -X POST https://autorouter.top/v1/video/generations \
  -H "Authorization: Bearer sk-YourApiKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-fast-generate-001",
    "prompt": "The cat slowly opens its eyes and stretches, birds chirping outside",
    "images": ["https://example.com/cat.jpg"],
    "size": "1080p",
    "duration": 8,
    "generate_audio": true
  }'

5. Model Comparison

Veo 3.1Veo 3.1 FastVeo 3.1 Lite
Model IDveo-3.1-generate-001veo-3.1-fast-generate-001veo-3.1-lite-generate-001
QualityHighestBalancedBasic
Speed (8s video, measured)~90–130s~75–105s~50–80s
Max Resolution4K1080p1080p
Audio
Image-to-Video

6. Billing

Video Only (generate_audio: false)

Model720p1080p4K
veo-3.1-generate-001$0.20 / sec$0.20 / sec$0.40 / sec
veo-3.1-fast-generate-001$0.08 / sec$0.10 / sec$0.25 / sec
veo-3.1-lite-generate-001$0.03 / sec$0.05 / sec

Video + Audio (generate_audio: true)

Model720p1080p4K
veo-3.1-generate-001$0.40 / sec$0.40 / sec$0.60 / sec
veo-3.1-fast-generate-001$0.10 / sec$0.12 / sec$0.30 / sec
veo-3.1-lite-generate-001$0.05 / sec$0.08 / sec

Quota calculation formula:

quota = modelPrice × QuotaPerUnit × groupRatio × pricingRatio × seconds

QuotaPerUnit = 500,000
groupRatio   = 1.0 (production default group)

Example (veo-3.1-generate-001, 1080p, 8s, with audio):
  modelPrice   = 0.20
  pricingRatio = 2.0 (audio doubles the cost)
  quota = 0.20 × 500,000 × 1 × 2.0 × 8 = 1,600,000

Example (veo-3.1-lite-generate-001, 1080p, 8s, video only):
  modelPrice   = 0.03
  pricingRatio ≈ 1.667 (1080p multiplier)
  quota = 0.03 × 500,000 × 1 × 1.667 × 8 ≈ 200,000

On task failure (failed), AutoRouter automatically refunds quota to your account. No manual action required.


7. Polling Guide

ItemRecommendation
Poll intervalEvery 10–15 seconds; minimum 5 seconds
Terminal statedata.status == "succeeded" or data.status == "failed"
Total timeout5 minutes recommended
Typical duration (8s video, measured)Lite: 50–80s; Fast: 75–105s; Standard: 90–130s
Video URL validity24 hours; download or transfer immediately

Simple Polling Script (Bash)

#!/bin/bash
TID="task_DduhCcHShyasO6lCV7o5SK9JQEYUnO1j"
KEY="sk-YourApiKey"
while true; do
  RESP=$(curl -sS "https://autorouter.top/v1/video/generations/$TID" \
    -H "Authorization: Bearer $KEY")
  echo "$RESP"
  STATUS=$(echo "$RESP" | python3 -c \
    "import sys,json;print(json.load(sys.stdin)['data'].get('status',''))")
  case "$STATUS" in
    succeeded|failed) break ;;
  esac
  sleep 15
done

8. Error Handling

HTTP Errors

CodeCauseAction
400Invalid parameters (missing prompt, unsupported duration, etc.)Check request body
401API Key invalid or expiredCheck Authorization header
403API Key lacks access to this modelCheck token model allowlist
402Insufficient balanceRecharge at AutoRouter console

Task Failure (failed)

Common ReasonRecommendation
Safety policy violation (data.error contains safety review details)Revise prompt; avoid sensitive content; use negative_prompt
Inaccessible image URLEnsure images URLs are publicly accessible and not expired
Unsupported duration valueUse 4, 6, or 8 only
4K not supported by modelOnly veo-3.1-generate-001 supports size: "4000"

9. FAQ

How do I choose between Veo 3.1, Fast, and Lite?

Choose based on your requirements:

  • Veo 3.1: Best quality, 4K support, ideal for final deliverables and commercial production. Highest cost.
  • Veo 3.1 Fast: Balanced speed and quality, good for rapid iteration and previews. Mid-range cost.
  • Veo 3.1 Lite: Fastest, cheapest, suitable for prototyping and large-scale testing.

What does generate_audio produce?

Veo 3.1 audio generation is natively synchronized and includes:

  • Dialogue / speech (when characters appear to be speaking)
  • Sound effects (wind, water, footsteps, etc.)
  • Background music / ambient sound

You cannot control each audio type independently — the model determines audio content based on the prompt and video.

Are duration values restricted to 4/6/8?

Yes. The supported values are 4, 6, and 8 seconds (integers). Other values may result in an error or be overridden to the default of 8.

How many reference images does image-to-video support?

Use the images array to pass reference images. Supported modes:

  • First-frame: Only pass images, the model generates motion starting from this image
  • Last-frame: Pass images and set lastFrameImage to a last-frame image URL; the model generates a transition from first to last frame

Multi-image reference is not currently supported.

Does every model support 4K (size: 4000)?

No. Only veo-3.1-generate-001 supports 4K output. Both veo-3.1-fast-generate-001 and veo-3.1-lite-generate-001 max out at 1080p.

Does the same seed reproduce identical results?

A fixed seed improves reproducibility but does not guarantee identical output due to the model's inherent stochasticity.

When does the video result URL expire?

The temporary signed link generally expires 24 hours after generation. Best practice: download or transfer to your own storage immediately after the task succeeds.

On this page