Skip to main content

​
Overview

VEO 3.1 Official is APIYI’s official-relay channel for Google Veo 3.1 — a transparent passthrough to Google AI Studio’s veo-3.1-generate-preview / veo-3.1-fast-generate-preview async endpoints, with model IDs, response fields, and constraints identical to the upstream. Pay-per-request billing, callable on the Default group — the lowest-friction official-quality Veo 3.1 channel available today.
🎬 Highlights: Transparent passthrough to Google AI Studio + native synchronized audio + flexible 4 / 6 / 8 second durations + three resolution tiers (720p / 1080p / 4k) + per-request billing from $0.3 + Default group + Pay-per-request or Pay-as-you-go Priority Tokens (no dedicated group needed; pure Pay-as-you-go is not supported). Suited for ad shorts, e-commerce assets, social-media content, and product demos that need official-grade quality with the simplest possible onboarding.
⚠️ Download via /content and re-host it yourself: once status: "completed", call GET /v1/videos/{task_id}/content to fetch the MP4 binary and store it in your own OSS / CDN before serving to end users. The completed response may also carry a video_url (a direct link, no auth) — it expires after about 24 hours (see expires_at) and is not guaranteed on every task, so use it only for temporary previews, never as a durable address. See API Endpoints below.

Text-to-Video API

POST /v1/videos, generate video from text only — JSON request body, the simplest entry point.

Image-to-Video API

POST /v1/videos + multipart upload of input_reference to animate a static image into a clip.

Official vs Reverse

Decision matrix against the existing VEO 3.1 (Reverse Channel).

Visual API Testing

Debug this endpoint directly in the iCover visual testing tool — no code required.

Async Task Lookup / Download

View submitted video tasks and download video links in the APIYI console — a lookup entry outside the API.

​
Let an AI Agent Do the Integration

If you build with Codex / Claude Code / Cursor, copy the prompt below and hand it to your agent. It first fetches the plain-text version of this page (append .md to any docs URL), then writes code in your project’s own stack — async polling, the fact that you must pull the MP4 down yourself, tiered timeouts and the hard 4K constraints are already baked into the requirements.

Have a coding agent integrate or troubleshoot VEO 3.1 Official text-to-video and image-to-video. Copy and paste into Codex, Claude Code, Cursor and similar tools.

​
Why APIYI’s VEO 3.1 Official?

Drop-in replacement for the Google official / Vertex AI channel, optimized for production scenarios across onboarding friction, stability, and cost:

Official Passthrough · Identical Model IDs

Transparent passthrough to Google AI Studio’s Veo 3.1 async endpoints. Model IDs (veo-3.1-generate-preview / veo-3.1-fast-generate-preview) match the upstream exactly, with one-to-one alignment on request and response fields and constraints.

Zero-Friction Onboarding · No Group Switching

Calls work on the Default group with Pay-per-request or Pay-as-you-go Priority Tokens (pure Pay-as-you-go is not supported). No dedicated group switch needed; existing Pay-per-request Tokens work as-is — the lowest-friction official-quality channel for Veo 3.1.

Unlimited Concurrency · Production Scale

Aggregated account pool with transparent proxy — scale batch shoots, ad pipelines, and high-volume production linearly. No Google per-account tier ceiling.

Per-Request Pricing · 60%+ Cheaper than Google

veo-3.1-fast-generate-preview $0.3/req, veo-3.1-generate-preview $1.2/req — flat across 4/6/8 sec and 720p/1080p/4k. Vs. Google’s official 8s 1080p, save 62–68%, stack top-up bonuses for further savings; failed tasks not billed.

Global Zero-Friction Access

No overseas server or proxy required — connect to api.apiyi.com directly from Mainland China data centers, residential networks, or overseas nodes. Skip the Google AI Studio / Vertex AI cross-border setup entirely.

Professional Support · Enterprise Onboarding

Our team has deep expertise in video generation: prompt engineering, resolution selection, batch production, and post-processing. Full PoC-to-production technical support for enterprise customers.

​
Key Features

Native Synchronized Audio

Veo 3.1 natively outputs video with synchronized audio (ambient sound, dialogue, score). No separate audio post-production needed — describe audio intent in your prompt.

Flexible 4 / 6 / 8 Second Durations

seconds string enum: "4" / "6" / "8". Per-request billing, duration does not affect price. 1080p / 4k tiers require "8".

Three Resolution Tiers

720p / 1080p / 4k, uniform per-request pricing. Toggle landscape (16:9) and portrait (9:16) freely.

Precise Instruction Following

Veo 3.1 leads its tier on camera motion, object physics, and character expression fidelity. Rich camera-language keyword support (push/pull/pan/dolly, low/high angles).

Image-to-Video (input_reference)

Upload one image as the visual anchor to animate static content. See Image-to-Video.

Async Task Model

Submit returns a task_id immediately. Poll status independently and download the final video — ideal for batch management and resume-on-failure flows.

OpenAI-Compatible Protocol

base_url=https://api.apiyi.com/v1 + Bearer auth. Works via raw HTTP or the OpenAI SDK’s low-level client.post().

Failures Are Free

In async mode, failed generations, content-policy rejections, parameter errors are not billed. Only status=completed tasks are charged.

​
Pricing

APIYI uses pay-per-request billing — flat price within supported duration/resolution combos, no surcharge for longer or higher-res output. Per ai.google.dev/gemini-api/docs/pricing public rates, Google’s official Veo 3.1 charges per second; the discounts below are computed for 8-second videos.
Billing notes:
  • Charged per request by model name, independent of duration (4/6/8 sec), resolution (720p/1080p/4k), or whether input_reference is provided — picking 4K costs the same as 720p
  • In async mode, failed generations / content-policy rejections / capacity errors are all not billed
  • Top-up bonus tiers under Top-Up Promotions further reduce effective cost
  • 4K renders 4–6× slower and produces files ~10× larger — default to 1080p for daily use
  • Google’s official 4K rate is $0.30/sec (fast) / $0.60/sec (standard), i.e. $2.40 / $4.80 for 8 sec (source: ai.google.dev/gemini-api/docs/pricing)

​
Group Setup

VEO 3.1 Official works on the Default group (1x), no dedicated group switching required. The Token’s billing mode must be Pay-per-request or Pay-as-you-go Priority — pure Pay-as-you-go is not supported (switch the Token mode in the console if needed).
Low onboarding friction: VEO 3.1 Official runs on the Default group and accepts both Pay-per-request and Pay-as-you-go Priority, with no dedicated group to set up — ideal when you want “drop in your existing Pay-per-request Token + change base_url” zero-config onboarding.

​
Technical Specs

At 1080p / 4k resolution, seconds must be "8" — "4" or "6" will be rejected upstream. All three durations are supported at 720p.

​
API Endpoints

⚠️ Download via /content; video_url is for temporary previews onlyThe standard way to retrieve the video is GET /v1/videos/{task_id}/content, which returns the MP4 binary stream (requires the Authorization: Bearer header).Implications:
  • The completed response may carry video_url (a direct link, no auth) and expires_at (about 24 hours later); it is not guaranteed on every task, so your code must handle its absence
  • Frontends cannot put the /content endpoint directly in a <video> tag — browser requests without the auth header will 401; video_url can be used for a temporary preview until it expires
  • As soon as status: "completed", download the MP4 and store it in your own OSS / CDN, then serve your URL to end users
  • The remote copy is kept for about 24 hours — do not depend long-term on the remote task_id or video_url to retrieve videos
Endpoint selection: Primary api.apiyi.com; backup gateway b.apiyi.com has identical behavior.

​
Key Parameters

⚡ Full parameter reference: Jump to Text-to-Video - Parameter Reference for the complete table covering model / prompt / seconds / size / metadata.* types, defaults, and constraints. This section unpacks only the 3 most pitfall-prone parameters.

​
seconds (video length)

The length field is named seconds (not duration) and must be a string ("4" / "6" / "8"). Passing a number returns:
Common pitfall: naming the field duration is silently ignored. duration is not recognized by this channel → it’s dropped → length falls back to the default 4 sec:
  • At 720p (and other tiers that allow 4 sec): no error, but you only get 4 sec (this is exactly the “sent 8s, got 4s” case)
  • At 1080p / 4k: 4 sec is illegal, so it errors with Resolution 1080p requires duration seconds to be 8 seconds, but got 4
Correct usage: send the seconds field with value "8" (string).
Parameter precedence: metadata.durationSeconds > seconds > 8

​
metadata.resolution (resolution tier)

Parameter precedence: metadata.resolution > size > 720p

​
⚠️ Do not pass generateAudio

Veo 3 / 3.1 is natively audio-aware, but the generateAudio parameter must not be passed — upstream will reject with INVALID_ARGUMENT. To control audio, write the intent into your prompt:
“Coastal lighthouse at dusk; waves, distant seabirds, low wind sounds, cinematic atmosphere”

​
Best Practices

1

Pick a model by need

  • Iteration / batch previews → veo-3.1-fast-generate-preview ($0.3/request)
  • Final delivery / 4K → veo-3.1-generate-preview ($1.2/request)
  • Run both with the same prompt + seed; pick by eye
2

Validate with 4 seconds first

For every new prompt, start with seconds: "4" to validate camera direction and style (60–90 sec render, $0.3). Scale up to 8 sec or 1080p once the look is locked.
3

Use async polling, not sync wait

The Official channel is async-only: POST to submit and get task_id → poll GET /v1/videos/{task_id} every 8–10 sec until status: "completed" → download from /content. No webhooks; polling only.
4

Set client timeouts by tier

  • 720p / 1080p: 3 min hard timeout
  • 4K: 10 min hard timeout
  • POST submit (multipart): 30 sec minimum
5

Download immediately on completion

Once status flips to completed, download to your own OSS / CDN immediately — the remote copy is kept for only about 24 hours, so do not depend long-term on the remote task_id. The /content endpoint occasionally returns 400 right after status flips; retry after 4 seconds (the sample clients have this baked in). A 502 from the same endpoint means the provider cannot retrieve the file — retrying will not help.
6

Encode audio intent in the prompt

Do not pass generateAudio (it returns INVALID_ARGUMENT). For ambient sound, dialogue, BGM, describe in the prompt: “waves, distant seabirds, low wind sounds”.
7

Rate-limit on your end

Concurrency caps are not publicly documented; in practice 10 simultaneous submissions all queued successfully. Recommend production-side limit of in-flight ≤ 10, with exponential backoff for 429 / 5xx.

​
Error Codes & Retries

Recommended client settings:
  • POST submit timeout: 30 sec (multipart uploads may need more)
  • Polling interval: 8–10 sec; max wait 720p/1080p 3 min, 4K 10 min
  • Exponential backoff retry for 5xx and failed (1–2 attempts recommended)
  • On a 400 from /content, retry every 4 seconds for up to about 30 seconds
  • Handle 400 and 502 from /content differently: 400 clears on retry; 502 does not — stop after 2 attempts, mark the task failed and keep the task_id

​
FAQ

Official (this page): Transparent passthrough to Google AI Studio’s upstream endpoints. Model IDs match Google upstream (veo-3.1-generate-preview / veo-3.1-fast-generate-preview), priced at $0.3 / $1.2 per request, async endpoint only.Reverse (existing VEO 3.1): Reverse-engineered access to Google Flow. Model IDs are veo-3.1-fast / veo-3.1 / -fl series, priced from $0.15 per request — cheaper, and supports both streaming sync and async modes, plus frame-to-video (first/last frame).See the full Official vs Reverse decision matrix. Both channels coexist; pick by business need.
The request field is seconds (string "4" / "6" / "8"). Naming it duration is not recognized — it’s silently dropped and length falls back to the default 4 sec, which is the root cause of “sent 8s but only got 4s”.As for why it must be a string: the backend Go struct declares this field (internally named duration) as string, so a number is rejected at the decoder layer with parse_request_failed: cannot unmarshal number into Go struct field ... duration of type string (the duration in that error is the backend’s internal field name — your request still sends seconds). Remember: send seconds, and quote the value: "4" / "6" / "8".
Veo 3 / 3.1 is a natively audio-enabled video model, but the generateAudio parameter must not be passed (upstream returns INVALID_ARGUMENT). To control sound, write the intent into your prompt:
“Coastal lighthouse at dusk; waves, distant seabirds, low wind sounds, cinematic atmosphere”
  • At equivalent parameters, render time is roughly the same (measured 720p 8 sec: fast 83s, standard 78s). fast is not faster — it is cheaper ($0.3 vs $1.2)
  • Default to veo-3.1-fast-generate-preview
  • Switch to veo-3.1-generate-preview for final delivery or when detail fidelity / physics consistency matters
  • A/B in production: run both with same prompt + seed, pick by eye
Not recommended for most cases:
  • Same per-request price sounds attractive
  • But rendering is 4–6× slower (720p 80s → 4K 350s)
  • Files are ~10× larger (720p 4MB → 4K 40MB) — bandwidth and storage costs double
  • 1080p is visually sufficient for most playback scenarios
When you do need 4K: use veo-3.1-generate-preview, set seconds="8" (mandatory), client timeout ≥ 10 min, run as a backgrounded async task.
  • There are no webhooks; poll GET /v1/videos/{task_id} only
  • Recommended polling interval: 8 sec (measured sufficient, won’t trip rate limits)
  • Measured times: 720p / 1080p 60–115 sec, 4K 5–6 min
  • Client timeouts: 3 min for 720p/1080p, 10 min for 4K
400: just wait. Right after status flips to completed, calling /v1/videos/{task_id}/content occasionally returns 400 because the video file has not finished syncing. The window lasts up to about 20 seconds, so retry every 4 seconds for up to about 30 seconds (the sample clients already do this). With curl, note that --retry does not retry a 400 by default — add -f --retry-all-errors.502: retrying will not help. The body looks like {"error":{"message":"Upstream service returned status 502"}}. Generation itself succeeded — GET /v1/videos/{task_id} still returns status: "completed" with progress: 100 — but the provider cannot retrieve that video file. In our measurements it is still 502 hours later, so it does not recover on its own. Never write this as an unbounded retry loop.What to do:
  1. Retry at most twice; if it is still 502, mark that task as failed
  2. Keep the task_id and contact us — that generation was already billed, and we will verify and handle it
  3. Resubmitting as a new task normally produces a video; you do not need to change the prompt
This is now rare: most tasks are checked for a retrievable video file before being reported completed; if the file cannot be retrieved, the task becomes status: "failed" (with the reason in error.message) and the charge is refunded automatically, so you are no longer billed for a video you cannot get. It cannot be ruled out entirely, though — GET /v1/videos/{task_id} returning completed does not mean the video is retrievable. Treat these as two separate success checks.
Sometimes, but only temporarily. The completed response may carry video_url (a direct link, no auth) and expires_at (a timestamp about 24 hours after completion). It is not guaranteed on every task and stops working once it expires, so do not distribute it as a durable address.Standard way to retrieve the video: after status: "completed", call GET /v1/videos/{task_id}/content to get the MP4 binary stream (requires Authorization: Bearer header). This works for every task.Standard production pattern:
  1. Backend downloads the MP4 as soon as the task completes → push to your own OSS / CDN
  2. Serve your CDN URL to end users
  3. The frontend <video> tag should NOT point directly at /content — browsers can’t include the auth header, requests will 401; when video_url is present you can use it for an immediate preview
About 24 hours, per the expires_at field in the response (assume 24 hours when the field is absent). Strongly recommended: download immediately on completion and store locally — do not depend long-term on the remote task_id or video_url; neither works after expiry.
The progress field is coarse-grained — it jumps between a few fixed steps only (such as 0 / 10 / 30 / 50 / 100). Do not use it for a percentage progress bar. Use a spinner, or compute “elapsed / expected” yourself.
No. Only status=completed tasks are charged. failed / canceled / content-policy rejected / parameter error are all free. No real video output, no charge.
Not byte-identical. Measured: same prompt + same seed (88888) + same params, fast run twice — file sizes 9.81 MB vs 9.25 MB, md5 completely different, render times also differ.But seed is not decorative: same-seed outputs cluster together (5-run test, intra-group file size spread only 6%), different seeds shift systematically (inter-group spread +36.8%). Implications:
  • Want a “stable look” → fix the seed
  • Want to “explore variations” → swap seed instead of fiddling with prompt
  • Want “exact replay” → forget it, store the mp4
Neither is currently supported. Image-to-video accepts only 1 image, with the field name fixed as input_reference, and only as file or Base64, not remote URL.Google upstream Veo 3.1 supports multi-reference / first-last-frame / video extension, but this channel does not. For first/last frame, use the VEO 3.1 (Reverse) -fl series.
Measured 10 simultaneous submissions, all queued successfully — no rejection. The exact cap is not publicly stated. Recommend production-side limit of in-flight ≤ 10, with exponential backoff on 429 / 5xx.
  • No visible watermark
  • But they carry Google C2PA Content Credentials (issued by Google C2PA Media Services, format urn:c2pa:...) embedded in MP4 metadata. End users cannot see them; C2PA tools (e.g., Adobe Content Authenticity) can verify “generated by Veo”
  • For redistribution scenarios, be aware; usually does not affect playback
Partially. The interface follows OpenAI conventions (Bearer auth + /v1/...), but the OpenAI official SDK does not expose a videos.create method (/v1/videos is a custom path). Use the OpenAI SDK’s low-level client.post() or raw HTTP. Raw HTTP is simplest — see code samples in Text-to-Video Playground.
VEO 3.1 Official is APIYI’s stable official-relay service — a transparent passthrough to Google AI Studio. Model IDs, response fields, and constraints match Google upstream exactly, and the channel works on the Default group with pay-per-request billing — the lowest-friction official-quality channel available. Please file feedback in the console support panel.