Create Veo Video

POST/v1/videos

Start an asynchronous text-to-video, image-to-video, first-and-last-frame, multi-reference, or reference-video task with a supported Veo or Gemini Omni model. Save the returned public task ID and poll the status endpoint until the task completes.

Asynchronous workflow

Submitting a request only places the job in the generation queue. It does not mean that the video is ready.

POST /v1/videos and save the id field from the response.
GET /v1/videos/{task_id} every 5-10 seconds. Avoid rapid polling.
When status becomes completed, download or play the video from url.
When status becomes failed, inspect error. Upstream-failed jobs are not charged under the documented provider policy.

Model capabilities

Model / mode	Duration	Aspect ratio	Reference images	Reference video	Resolution
veo-3.1-fast-generate-preview	4 / 6 / 8 s	16:9, 9:16	0-2; 1=image drive, 2=first/last	No	720p
veo-3.1-generate-preview	4 / 6 / 8 s	16:9, 9:16	0-2; 1=image drive, 2=first/last	No	720p
veo-3.1-generate-preview-ref with images	8 s only	16:9 only	1-3 multi-reference images	No	720p
veo-3.1-generate-preview-ref without images	4 / 6 / 8 s	16:9, 9:16	None	No	720p
gemini-omni-flash	3-10 s, every integer	16:9, 9:16	0-1	0-1 public URL, <=100 MiB	720p

Reference media rules

No image_url, image_urls, or video_url means text-to-video.
Fast and standard Veo: one image drives the video; two image_urls are ordered first frame, then last frame.
The Ref model uses image_urls for 1-3 references. With images it strictly requires duration=8 and aspect_ratio=16:9.
Gemini Omni accepts at most one reference image or one public reference-video URL. The video must be directly downloadable and no larger than 100 MiB.
image_url and image_urls are mutually exclusive. Image strings may be public HTTP(S) URLs, data URLs, or raw base64; {data, mime_type} objects are not accepted.

Prompt and optional controls

Keep duration and aspect-ratio instructions out of prompt. Set them only with duration and aspect_ratio.
generate_audio defaults to true. Send false for silent output.
negative_prompt describes unwanted visual content.
generateAudio and negativePrompt are accepted compatibility aliases, but snake_case is recommended.

Header Parameters

Authorization:requiredstring

Bearer authentication header containing your API key.

ExampleBearer <YOUR_API_KEY>

Content-Type:requiredstring

Media type of the request body.

Exampleapplication/json

Request Body

application/json

model:requiredenum<string>

Select exactly one supported model. Do not append duration, aspect ratio, or resolution to the model name. See the model capability table above for the valid input combinations.

Allowedveo-3.1-fast-generate-previewveo-3.1-generate-previewveo-3.1-generate-preview-refgemini-omni-flash

Exampleveo-3.1-fast-generate-preview

prompt:requiredstring

Non-empty description of the requested scene and motion. Do not write duration or aspect-ratio instructions such as 'vertical', '16:9', or '8 seconds' in the prompt; use the dedicated parameters instead.

ExampleA paper boat sailing down a rain puddle, cinematic

duration:requiredinteger

Required duration in seconds. Veo models accept only 4, 6, or 8. gemini-omni-flash accepts every integer from 3 through 10. A reference-image veo-3.1-generate-preview-ref request requires 8.

Allowed345678910

Example4

seconds:optionalstring

Compatibility alias for duration. Send it as a JSON string, for example "4". If both fields are present, duration takes precedence. Prefer duration for new integrations.

Allowed345678910

Example4

aspect_ratio:optionalenum<string>

Output aspect ratio. The default is 16:9. All models accept 16:9 or 9:16 except reference-image veo-3.1-generate-preview-ref requests, which require 16:9.

Allowed16:99:16

Example16:9

image_url:optionalstring

One reference image. Use either image_url or image_urls, never both. Accepted values are a directly accessible public HTTP(S) URL, a data:image/...;base64,... URL, or raw base64. Object values such as {data, mime_type} are not supported.

Examplehttps://example.com/first-frame.jpg

image_urls:optionalarray<string>

Reference image array. Fast and standard Veo accept up to 2 images; two images mean first frame then last frame. The Ref model accepts 1-3 multi-reference images. Gemini Omni accepts at most 1 image. Each item supports a public URL, data URL, or raw base64.

Example["https://example.com/first-frame.jpg", "https://example.com/last-frame.jpg"]

video_url:optionalstring<uri>

Available only for gemini-omni-flash. Provide one directly downloadable public HTTP(S) video URL no larger than 100 MiB. Data URLs and raw base64 video data are not supported.

Examplehttps://example.com/reference.mp4

generate_audio:optionalboolean

Whether to generate audio with the video. The default is true; explicitly send false for a silent video. The generateAudio alias is also accepted.

Allowedtruefalse

Exampletrue

negative_prompt:optionalstring

Describe elements that should not appear in the result. The negativePrompt alias is also accepted.

Exampleblurry, distorted faces, subtitles

generateAudio:optionalboolean

Camel-case compatibility alias for generate_audio. Prefer generate_audio in new integrations.

Allowedtruefalse

Exampletrue

negativePrompt:optionalstring

Camel-case compatibility alias for negative_prompt. Prefer negative_prompt in new integrations.

Exampleblurry, distorted faces, subtitles

Response

200

A successful request returns a JSON response. The complete example is shown in the code panel.