Veo 3.1 Official API with APIDot

Build with the Veo 3.1 Official API using APIDot: cURL, Node.js, polling, webhooks, pricing, and production notes in one GitHub repo.

Try on APIDot | Get API Key | API Docs | Pricing | Main Examples

Why this repo exists

Google DeepMind Veo 3.1 Official API for cinematic text-to-video, image-to-video, first/last-frame, reference, and native audio workflows.

This repository turns the APIDot workflow into runnable server-side examples: a verified cURL request, a native Node.js polling example, webhook receiver notes, prompt examples, pricing context, and production integration guardrails.

Overview

Veo 3.1 Official uses APIDot's shared async generation workflow. Send one supported public model ID in top-level model, optional callback_url, and parameters inside input. A successful submit returns task_id; retrieve the final video through status polling or webhook delivery.

Capabilities

• Use veo3.1-lite-official for lower-cost 720p or 1080p iteration when reference mode and 4K are not needed.
• veo3.1-lite-official first/last-frame mode (two image_urls, with or without generation_type: "frame") only supports duration: 8.
• Use veo3.1-fast-official when you need the broadest generation modes, including reference mode and 4K.
• Use veo3.1-quality-official when higher quality is worth the additional credits.
• Store the returned task_id and use polling or callback_url for terminal delivery.

Common use cases

• Product and marketing video generation
• Social-first creative testing
• Storyboard previews and prompt iteration
• Backend media workflow prototypes
• Production queues that need polling or webhooks

Pricing on APIDot

Catalog price: Starting at 3.6 credits per second | Lite 720p no audio starts at 3.6 credits/sec ($0.018); Fast 720p/1080p starts at 10 credits/sec ($0.050); Quality starts at 24 credits/sec ($0.120).

Tier	Model	Resolution	Credits	APIDot listed price	fal.ai listed price
veo3.1-fast-official	720p/1080p	no audio	veo3.1-fast-official	720p/1080p	10
veo3.1-fast-official	720p/1080p	audio	veo3.1-fast-official	720p/1080p	15
veo3.1-fast-official	4K	no audio	veo3.1-fast-official	4K	30
veo3.1-fast-official	4K	audio	veo3.1-fast-official	4K	35
veo3.1-lite-official	720p	no audio	veo3.1-lite-official	720p	3.6
veo3.1-lite-official	720p	audio	veo3.1-lite-official	720p	6
veo3.1-lite-official	1080p	no audio	veo3.1-lite-official	1080p	6
veo3.1-lite-official	1080p	audio	veo3.1-lite-official	1080p	9.6

This README uses pricing data currently published in the APIDot model catalog. Check the APIDot model page before high-volume production runs.

Quick start

cp .env.example .env
# Edit .env and set APIDOT_API_KEY
cd node
npm start

The same request shape is available as a copy-paste cURL example in curl/generate.md.

API workflow

flowchart LR
    A[Submit generation request] --> B[Receive data.task_id]
    B --> C{Delivery mode}
    C -->|Polling| D[Check task status]
    C -->|Webhook| E[Receive callback_url event]
    D --> F[Read result URL from finished task]
    E --> F

Loading

Use polling for local tests and webhook delivery for production queues. Store data.task_id before the first status check so retries, callbacks, and result URLs can be reconciled safely.

Minimal API request

Submit to APIDot's unified async generation endpoint:

POST https://api.apidot.ai/api/generate/submit
Authorization: Bearer <APIDOT_API_KEY>
Content-Type: application/json

Primary payload:

{
  "model": "veo3.1-fast-official",
  "input": {
    "prompt": "A cinematic product launch shot of a compact electric bike rolling through a rain-lit city street, slow tracking camera, realistic reflections, confident commercial pacing.",
    "duration": 8,
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "sound": true
  }
}

Submit Veo 3.1 Official generation jobs through APIDot's unified async generation endpoint.

Model IDs and request variants

Fast Official text-to-video

{
  "model": "veo3.1-fast-official",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "A cinematic product launch shot of a compact electric bike rolling through a rain-lit city street, slow tracking camera, realistic reflections, confident commercial pacing.",
    "duration": 8,
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "sound": true
  }
}

Lite Official image-to-video

{
  "model": "veo3.1-lite-official",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "Animate this product photo into a clean ecommerce teaser with a gentle camera push and soft studio lighting.",
    "duration": 8,
    "aspect_ratio": "auto",
    "resolution": "720p",
    "sound": false,
    "image_urls": [
      "https://your-domain.com/product.webp"
    ]
  }
}

Lite Official first/last-frame

{
  "model": "veo3.1-lite-official",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "Start with the engineer standing at the entrance of the vertical farm aisle holding a tablet, then move smoothly down the hydroponic corridor as they crouch to inspect basil leaves near the final frame, clean morning light, realistic greenhouse motion, calm documentary pacing.",
    "duration": 8,
    "aspect_ratio": "auto",
    "resolution": "720p",
    "sound": true,
    "generation_type": "frame",
    "image_urls": [
      "https://your-domain.com/veo31-official-first-frame-start.png",
      "https://your-domain.com/veo31-official-first-frame-end.png"
    ]
  }
}

Quality Official reference

{
  "model": "veo3.1-quality-official",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "Create an 8-second premium brand film that keeps the product shape and material language close to the reference images.",
    "duration": 8,
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "sound": true,
    "generation_type": "reference",
    "image_urls": [
      "https://your-domain.com/reference-1.webp",
      "https://your-domain.com/reference-2.webp",
      "https://your-domain.com/reference-3.webp"
    ]
  }
}

Request parameters

Field	Type	Required	Description
model	string	yes	Target model ID: veo3.1-fast-official, veo3.1-lite-official, or veo3.1-quality-official.
callback_url	string	no	Optional webhook URL for terminal task updates.
input.prompt	string	yes	Text prompt for generation. Maximum length is 1000 characters.
input.duration	integer	no	Generation duration in seconds. Generation models support 4, 6, or 8; reference mode uses 8; veo3.1-lite-official with two image_urls also requires 8.
input.aspect_ratio	string	no	Output aspect ratio. Supported values are 16:9, 9:16, and auto where the selected mode allows it.
input.resolution	string	no	Output resolution. Fast and Quality support 720p, 1080p, and 4k; Lite supports 720p and 1080p.
input.sound	boolean	no	Whether to generate native audio. Audio and silent jobs use different per-second credit rates.
input.generation_type	string	no	Use frame for two-image first/last-frame generation or reference for three-image reference mode. When model is veo3.1-lite-official and two image_urls are provided, input.duration must be 8.
input.image_urls	string[]	no	Optional image URLs. Use one image for image-to-video, two for first/last-frame, or three for reference mode. For veo3.1-lite-official, two images require duration: 8.

Practical integration notes

• Keep APIDot API keys in server-side environment variables.
• Persist task_id, selected model, request payload, user ID, and status together.
• Poll at a moderate interval for local tests and use webhooks for durable production callbacks.
• Validate source media URLs before submitting requests that depend on source files.
• Avoid logging API keys, private prompts, private media URLs, or callback URLs.

Polling and webhooks

APIDot media generation is asynchronous. Store data.task_id immediately after submit, poll /api/generate/status/{task_id} for local tests, and use callback_url webhooks for production queues where users may leave the page before completion.

Webhook handlers should verify task ownership, persist callback events, return 2xx quickly, and be idempotent because duplicate deliveries can happen.

Response and errors

• code: HTTP-style status code. Successful submits return 200.
• data.task_id: Async task identifier returned immediately after submission.
• data.status: Initial task status, typically not_started.
• data.created_time: ISO 8601 timestamp for task creation.

Common error classes:

• 400 invalid_request: Missing fields or unsupported parameter combinations.
• 401 authentication_error: Missing, expired, or invalid Bearer API key.
• 402 insufficient_credits: The current prepaid balance cannot cover the job.
• 429 rate_limited: Submission rate is temporarily above the current allowed limit.

Production notes

• Keep APIDot API keys in server-side environment variables.
• Persist task_id, selected model, request payload, user ID, and status together.
• Use a moderate polling interval for tests and webhooks for durable production callbacks.
• Validate source media URLs before submitting requests that depend on source files.
• Avoid logging API keys, private prompts, private media URLs, or callback URLs.
• Retry transient network failures with backoff, but do not retry unchanged invalid payloads.

FAQ

Which model IDs are supported?

veo3.1-fast-official, veo3.1-lite-official, and veo3.1-quality-official.

How many images can I send?

Send no images for text-to-video, one image for image-to-video, two images for first/last-frame generation, or three images for reference mode. Lite accepts at most two images, does not support reference mode, and only supports 8 seconds for first/last-frame generation.

When is aspect_ratio: auto valid?

auto is valid for one-image and two-image workflows. Text-only and reference requests should use 16:9 or 9:16.

Related links

• Website: https://apidot.ai
• Docs: https://apidot.ai/docs
• Veo 3.1 Official docs: https://apidot.ai/docs/veo-3-1-official
• Veo 3.1 Official model page: https://apidot.ai/models/veo-3-1-official
• GitHub repo: https://github.com/APIDotAI/veo-3-1-official-api
• Main examples: https://github.com/APIDotAI/apidot-examples