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.
⚠️ No CDN URL returned — you must download the MP4 stream yourself: The channel currently does not return any distributable public / CDN URL. 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. Browsers cannot hit /content directly (auth header required). 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.

​
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).
Onboarding friction comparison: Versus Sora 2 Official (which requires the dedicated Sora2Official group + Pay-as-you-go Priority only), VEO 3.1 Official runs on the Default group and accepts both Pay-per-request and Pay-as-you-go Priority — 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

⚠️ MP4 binary download only — no CDN URL returnedThis channel currently does not output any CDN / public URL in the response — the video file can only be retrieved as an MP4 binary stream via GET /v1/videos/{task_id}/content (requires the Authorization: Bearer header).Implications:
  • No video_url / data.url / any directly distributable link is returned in the response
  • Frontends cannot put the endpoint URL directly in a <video> tag — browser requests without the auth header will 401
  • As soon as status: "completed", download the MP4 and store it in your own OSS / CDN, then serve your URL to end users
  • Video retention is not officially documented — do not depend long-term on the remote task_id to retrieve videos
Endpoint selection: Primary api.apiyi.com; backup gateways vip.apiyi.com / b.apiyi.com have 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 — 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).
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)
  • Retry /content 3–5 times with 4-second gaps

​
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
Right after status flips to completed, calling /v1/videos/{task_id}/content occasionally returns 400 due to upstream CDN sync delay. Wait 4 sec and retry once typically resolves it (the sample clients retry 3–5 times with 4-second gaps).
Not currently. This channel does not return any CDN / public URL in the response — no video_url / data.url / any other directly distributable link.The only 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).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
If/when the upstream exposes CDN URLs, this page will be updated.
Retention period is not officially documented. Strongly recommended: download immediately on completion and store locally — do not depend long-term on the remote task_id; /content will eventually 404 after expiry.
The progress field is coarse-grained — only jumps between 0 / 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.