API Reference

Veo 3.1

Veo 3.1 text-to-video and image-to-video with native audio and first/last-frame interpolation

Veo 3.1 generates 4–8 second videos with optional native audio, and supports first-frame, first+last-frame, and reference-image workflows.

All tasks are asynchronous: submit, poll the task status, then download the result. The full lifecycle is documented on the Video Generation page.

Model Lineup

veo-3.1-generate-preview — highest quality, native audio, up to 4K. Durations 4 / 6 / 8 s; aspect ratios 16:9 / 9:16.

veo-3.1-fast-generate-preview — balanced quality and speed. Durations 4 / 6 / 8 s; aspect ratios 16:9 / 9:16.

veo-3.1-lite-generate-preview — fastest and lowest cost; does not support 4k. Durations 4 / 6 / 8 s; aspect ratios 16:9 / 9:16.

Submit a Generation Task

openaiFailover: disabled

Routes by the model field in the request body to the matching model.

Task creation is not idempotent, so failover retries are disabled for video routes.

POST/v1/videosCompatibility aliasPOST/v1/video/generations

Request

schema

JSON body.

modelstringRequired

Veo 3.1 model ID.

veo-3.1-generate-previewveo-3.1-fast-generate-previewveo-3.1-lite-generate-preview

promptstringOptional

Video description prompt. Required for text-to-video; optional when an image input is provided via image, images, lastFrameImage, or input_reference. Chinese and English are both accepted; English prompts usually produce the best results.

size / resolutionstringOptional

Resolution. 4k is only available on the non-lite models. If omitted, the model default is used.

720p1080p4k

duration / secondsinteger | stringOptional

Video duration in seconds. At 1080p or 4k, only 8 seconds is supported.

468

aspect_ratiostringOptional

Aspect ratio. Defaults to 16:9.

16:99:16

generate_audiobooleanOptional

Whether to generate synchronized audio. Not enabled unless explicitly set — enabling roughly doubles the cost.

enhance_promptbooleanOptional

Whether to apply prompt enhancement. Not enabled unless explicitly set.

negative_promptstringOptional

Negative prompt describing what to avoid.

seedintegerOptional

Random seed, 0 to 2^32 - 1. Best-effort; determinism is not guaranteed.

person_generationstringOptional

People-generation policy.

allow_allallow_adultdisallow

imagestringOptional

First-frame image for image-to-video. Accepts HTTP(S) URL, data URI, or raw base64.

imagesarray<string>Optional

Image array; the first item is used as the main image input.

lastFrameImagestringOptional

Last-frame image. Combined with image, the model interpolates between the first and last frames.

input_referencestringOptional

Reference image input. Accepts HTTP(S) URL, data URI, or raw base64.

image_mime_typestringOptional

Optional MIME type hint for the provided image(s), e.g. image/png.

Response

schema

Submission receipt. Fields are returned at the top level of the JSON body (no data wrapper).

idstringOptional

Task ID (task_xxx). Same value as task_id, kept for OpenAI SDK compatibility.

task_idstringOptional

Task ID used for polling and download.

objectstringOptional

Always video.

modelstringOptional

Model name from the request.

statusstringOptional

Initial task status, usually QUEUED.

SUBMITTEDQUEUEDIN_PROGRESSSUCCESSFAILURE

progressintegerOptional

Progress 0–100, usually 0 right after submission.

created_atintegerOptional

Task creation time (Unix seconds).

4K output (resolution = 4k) is only available on the non-lite models.

1080p and 4k resolutions only support 8-second duration.

Audio is not generated unless generate_audio is set to true (which roughly doubles the cost).

Both success and business failures return HTTP 200. A failed call carries an error object — { "error": { "message", "type", "code" }} — instead of the receipt fields; check for the error field to tell them apart.

Query and Download

Poll the task until it reaches SUCCESS or FAILURE (every 10–15 seconds, never below 5 seconds), then download the result. The download endpoint supports Range requests (HTTP 206) for resumable download and seek-while-playing.

GET/v1/videos/{task_id}Compatibility aliasGET/v1/video/generations/{task_id}

GET/v1/videos/{task_id}/content

Response

schema

Core fields below. The full task detail schema, status lifecycle, and polling guidance are documented on the Video Generation page.

statusstringOptional

Task status.

SUBMITTEDQUEUEDIN_PROGRESSSUCCESSFAILURE

progressstringOptional

Progress percentage string, such as "50%".

result_urlstringOptional

Result video download URL, present when status is SUCCESS. Has the form /v1/videos/{task_id}/content.

fail_reasonstringOptional

Failure reason, present when status is FAILURE.

Submit a Generation Task

bashText to video

Language

curl -X POST https://api.tokenbay.com/v1/videos \
  -H "Authorization: Bearer sk-XXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "A golden retriever playing fetch on a sunny beach",
    "resolution": "1080p",
    "duration": 8,
    "aspect_ratio": "16:9"
  }'

200 json200 response

Language

{
  "id": "task_9dXfUz8h5GxBvDqIvYoVnZ3r",
  "task_id": "task_9dXfUz8h5GxBvDqIvYoVnZ3r",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "QUEUED",
  "progress": 0,
  "created_at": 1778250615
}

bashImage to video (portrait, with audio)

Language

curl -X POST https://api.tokenbay.com/v1/videos \
  -H "Authorization: Bearer sk-XXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-fast-generate-preview",
    "prompt": "Product animation with natural motion",
    "images": ["https://example.com/product.png"],
    "resolution": "1080p",
    "duration": 6,
    "aspect_ratio": "9:16",
    "generate_audio": true
  }'

bashFirst + last frame interpolation

Language

curl -X POST https://api.tokenbay.com/v1/videos \
  -H "Authorization: Bearer sk-XXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "Smooth cinematic transition between scenes",
    "image": "https://example.com/start.jpg",
    "lastFrameImage": "https://example.com/end.jpg",
    "resolution": "1080p",
    "duration": 8
  }'

bashReference image

Language

curl -X POST https://api.tokenbay.com/v1/videos \
  -H "Authorization: Bearer sk-XXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "Character walks through a neon-lit city",
    "input_reference": "https://example.com/character.png",
    "duration": 8
  }'

Query and Download

bashPoll the task

Language

curl https://api.tokenbay.com/v1/videos/task_9dXfUz8h5GxBvDqIvYoVnZ3r \
  -H "Authorization: Bearer sk-XXXXXXX"

200 json200 response

Language

{
  "task_id": "task_9dXfUz8h5GxBvDqIvYoVnZ3r",
  "action": "generate",
  "status": "SUCCESS",
  "progress": "100%",
  "result_url": "https://api.tokenbay.com/v1/videos/task_9dXfUz8h5GxBvDqIvYoVnZ3r/content",
  "quota": 12000,
  "submit_time": 1778250615,
  "start_time": 1778250620,
  "finish_time": 1778250745,
  "created_at": 1778250615,
  "updated_at": 1778250745
}

bashDownload the result

Language

curl -L https://api.tokenbay.com/v1/videos/task_9dXfUz8h5GxBvDqIvYoVnZ3r/content \
  -H "Authorization: Bearer sk-XXXXXXX" \
  -o result.mp4

Model Lineup

Submit a Generation Task

Request

Response

Query and Download

Response

Related