Create Video Generation Task

Veo image-to-video API guide: generate video from a first-frame image and prompt using veo-3.1 and veo-3.0 models, with duration, resolution, and image specs.

(Veo Image-to-Video)

This endpoint lets you upload a first-frame image and combine it with a prompt to generate a coherent, high-quality dynamic video. Supports synchronized audio, custom voices, and off-peak generation mode.

Quick Start

Video generation is asynchronous. The whole flow takes three steps:

1. Submit the task → get a task_id
2. Poll the status → wait for status to become succeeded and return a public URL

📌 Basics

Endpoint: POST /v1/video/generations
Authentication: Bearer Token (Authorization: Bearer {{YOUR_API_KEY}})
Content type: application/json

📥 Request Parameters (Request Body)

Parameter	Type	Required	Description
model	`string`	Yes	Model name. Options: `veo-2.0-generate-001`, `veo-3.0-fast-generate-001`, `veo-3.0-generate-001`, `veo-3.1-fast-generate-preview`, `veo-3.1-generate-preview`
prompt	`string`	Yes	Video motion description. Up to 5000 characters.
aspect_ratio	`string`	Yes	Aspect ratio
images	`array`	Yes	Supported; pass the first-frame image via `input_reference` (Veo 3.1). When used, `seconds` is fixed to `"8"`
seconds	`integer`	No	Duration. Veo 3/3.1: "4", "6", "8"; Veo 2: "5"~"8" (default "8")
size	`string`	No	Resolution: 720p (default), 1080p, 4k (4K is Veo 3+ only), or pixel formats such as 1280x720, 1920x1080

🖼️ Image Requirements

Formats: PNG, JPEG, JPG, WebP.
Size: image file up to 50MB (POST body limited to 20MB).
Aspect ratio: must be between 1:4 and 4:1.

📤 Response

Status code: 200 OK (task submitted)

Field	Type	Description
id	`string`	Task instance ID.
task_id	`string`	Task ID (used for status queries).
status	`string`	Current task status (e.g. `queued`).
progress	`integer`	Generation progress percentage.
created_at	`integer`	Task creation timestamp.

{
  "id": "task_MQKsdsosLYRreob4Z4NzTFxZKtSoVRWZ",
  "task_id": "task_MQKsdsosLYRreob4Z4NzTFxZKtSoVRWZ",
  "object": "video",
  "model": "veo-2.0-generate-001",
  "status": "queued",
  "progress": 0,
  "created_at": 1775116001
}

📝 Request Example

{
  "model": "Veoq3-turbo",
  "prompt": "Contemporary dance, the people in the picture are performing contemporary dance.",
  "images": ["https://example.com/dance_start_frame.png"],
  "duration": 7
}

💡 Developer Tips

Audio splitting: Fine-grained audio_type splitting (e.g. keeping only sound effects or only speech) is supported on the Q2 and Q1 models only.
Off-peak task management: Off-peak tasks that do not complete within 48 hours are automatically canceled and the credits are refunded; you can also cancel a task manually before it is processed.
Prompt recommendation: If you are unsure about your prompt, enable is_rec: true and the system will automatically optimize it to produce a better video.
Callback signature: Veo signs its callback pushes; verify the signature on your server for security.

Create Video Generation Task

On this page