# Gemini video generation — Veo 3.1 via predictLongRunning

Status: DOCUMENTED · PREVIEW (all three Veo 3.1 ids are previews) · validation / error shapes LIVE_VERIFIED (no paid generation was run: $0.05–0.60 per second) · generatedFiles list LIVE_VERIFIED (200 {}) · Veo 3.0 / 2.0 DEPRECATED (shutdown 2026-06-30, absent from models.list). Sources: Veo guide · Video overview (Omni vs Veo) · Pricing #veo-3.1 · Deprecations · Files guide · discovery v1beta rev. 20260918 (models.predictLongRunning, models.operations.*, generatedFiles.*) · python-genai types (GenerateVideosConfig, GenerateVideosResponse, VideoGenerationReferenceImage). Last verified: 2026-09-18. Twins: generated/fragments/endpoints/gemini-media-batch-tuning.json (api_family video-generation, operations, files), generated/fragments/parameters/gemini-video-generation.json, generated/fragments/status-lifecycles/gemini-lifecycles.json.

Google now recommends Gemini Omni Flash (Interactions API, gemini-omni-1.1-flash, conversational video editing) as the default video model; Veo 3.1 stays for extension, first/last-frame control and legacy pipelines. Omni is out of scope here (interactions agent).

# 1. Models (live list)

All Veo 3.x output: 24 fps, native audio always on, 1 video per request, SynthID watermark.

# 2. Lifecycle (long-running operation)

POST /v1beta/models/veo-3.1-generate-preview:predictLongRunning   → 200 Operation {name:"models/veo-3.1-generate-preview/operations/<id>", done:false}
GET  /v1beta/models/veo-3.1-generate-preview/operations/<id>      → poll every ~10 s (11 s … 6 min)
     done:true, response.generateVideoResponse.generatedSamples[0].video.uri
GET  <uri>  (https://generativelanguage.googleapis.com/v1beta/files/<id>:download?alt=media)  -H x-goog-api-key -L → MP4

• done:true + error (google.rpc.Status) = blocked by safety/audio filters or invalid input; not billed.
• Videos are stored 2 days (timer resets when a video is referenced for extension). They also surface in GET /v1beta/generatedFiles (state GENERATING → GENERATED | FAILED).
• No :cancel exists for model operations (only batches/*:cancel). Webhooks can replace polling (docs/gemini/long-running-operations.md).
• Request latency: min 11 s, max 6 min at peak.

# 3. Request body (PredictLongRunningRequest)

{
  "instances": [{
    "prompt": "Drone shot following a red convertible along a coastal road at sunset; engine roars.",
    "image": {"inlineData": {"mimeType": "image/png", "data": "<base64>"}},
    "lastFrame": {"inlineData": {"mimeType": "image/png", "data": "<base64>"}},
    "referenceImages": [{"image": {"inlineData": {...}}, "referenceType": "asset"}],
    "video": {"inlineData": {"mimeType": "video/mp4", "data": "<base64 of a previous Veo output>"}}
  }],
  "parameters": {"aspectRatio": "16:9", "resolution": "720p", "durationSeconds": "8", "personGeneration": "allow_all", "negativePrompt": "…", "seed": 42, "numberOfVideos": 1}
}

Only instances is required. Live validation (free): empty body → 400 INVALID_ARGUMENT "No instances in the request."; {"instances":[{}]} → 400 "Unsupported video generation request. Please check the documentation for supported usage: https://ai.google.dev/gemini-api/docs/video"; unknown model → 404 "models/veo-9-generate is not found for API version v1beta, or is not supported for predictLongRunning".

# 4. Response objects

• REST: Operation.response = {"@type": "…PredictLongRunningResponse", "generateVideoResponse": {"generatedSamples": [{"video": {"uri": "…files/<id>:download?alt=media"}}], "raiMediaFilteredCount", "raiMediaFilteredReasons"}} (path used by the official jq samples).
• SDK (GenerateVideosOperation.response → GenerateVideosResponse): generated_videos[].video.{uri, video_bytes, mime_type}, rai_media_filtered_count, rai_media_filtered_reasons[]. client.files.download(file=video) fetches the bytes; the same Video object is what you pass back as instances[].video for extension.

# 5. Pricing (paid tier only; per second of generated video, billed only on success)

An 8-second 720p clip therefore costs $0.40 (Lite) to $3.20 (Standard). Free tier: not available. Rate limits: see AI Studio rate-limit page (not documented per model in the crawled pages).

# 6. generatedFiles and download

# 7. Live log

Cost: $0. Examples (examples/gemini/video-generation/) are UNVERIFIED end-to-end; they implement the documented flow and stop before paying unless ATLAS_ALLOW_PAID=1.