What you can set on a Veo 3.1 request, and what is host-dependent

Updated 2026-10-02

The Veo 3.1 request body is simple, but how much of it is honoured depends on the tier (google/veo-3.1, -fast, -lite) and on the host serving the job. This page lists each field, states what VideoRouter's documentation says about it, and flags the places where the honest answer is to check the model page for the host you intend to use.

Field overview

duration_secs

Send whole seconds. The value is snapped to the nearest duration the model supports, and you are billed once at creation for the snapped value. If you omit the field the platform default is 4 seconds. Which durations a given tier and host accept is not something this page will state, because it varies and the model page is the authority. The safe workflow is to request a short clip, read the job back, and only then standardise on a length. For cost control, the shortest clip that proves the shot is the cheapest request you can make, since the charge happens at creation and does not depend on how much of the clip you keep.

resolution

The Veo 3.1 model page lists 720p, 1080p and 2160p as resolution tiers. VideoRouter's documentation says that for veo-3.1 and veo-3.1-fast, resolution and aspect_ratio select among a small set of confirmed tiers, and that for Fast the tier also changes the price. It also says the DeepInfra and SiliconFlow rows ignore both fields. Whether the Lite tier supports the same set is something to confirm on its page rather than assume.

The behaviour to design around: an unsupported combination is never rejected. It is ignored, and the model default is used. That means a wrong tier string produces a successful job with the wrong dimensions, and for Fast possibly a different price than you planned. Put a dimension check (for example ffprobe) in your tests and log the requested tier next to every job id.

aspect_ratio

The accepted vocabulary across the platform is 16:9, 9:16, 1:1, 4:3, 3:4 and 21:9, but each model supports only some of these, and the Veo model page does not enumerate which. Treat 16:9 and 9:16 as the values to test first, and verify the output. For image-to-video, match the ratio of your source image, since a mismatch invites cropping.

If you need exact pixels, height and width integers are accepted and override resolution and aspect_ratio, though host support still applies.

Image input

Add start_image_url (public https:// URL or data:image/...;base64,... URI) to animate a first frame. This is a per-host capability, wired on a subset of hosts and variants, and a model or host that does not support it rejects the field with a 400. The model page for Veo 3.1 lists start and end images, reference images, reference video and reference audio as input modes in general terms; do not read that as support on every host. Note that end_image_url is documented as accepted by no model yet and returns a 400 if sent. For a local file, POST /v1/uploads returns a presigned URL that expires in 30 minutes. The image-to-video guide has the full workflow, and the reference arrays and editing field are mutually exclusive with start_image_url in a single request.

Provider preferences

With no preference, the request goes to the cheapest healthy host and falls through on rejection. You can shape that with a provider object:

• only and ignore: allow-list and block-list of host slugs.
• order: a priority sequence, not a restriction.
• sort: price, latency, reliability or queue.
• allow_fallbacks: set false for exactly one attempt.

A separate failover.on_timeout_sec hedges an accepted but stalled job to the next host, and both attempts are billed if both complete. Because rates differ between hosts, host choice is also a price decision:

Per second, before VideoRouter's 2% platform fee. For tiered models each row compares the resolution tier with the widest host-to-host gap. Built 2026-10-02 from the live catalog.

A request that uses the fields deliberately

{
  "model": "google/veo-3.1-fast/replicate",
  "prompt": "slow push-in on the mug, steam rising, soft morning light",
  "start_image_url": "https://example.com/mug.jpg",
  "duration_secs": 8,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "provider": {"only": ["replicate"], "allow_fallbacks": false}
}

That pins Replicate, which the image-to-video guide names as an image-capable host for Veo 3.1 Fast, and refuses to fall back to a host that would reject the image.

What to verify yourself

1. Supported durations for each tier on the host you choose.
2. Whether your resolution and aspect_ratio were honoured, by inspecting the output file.
3. Whether the host accepts image input, with one cheap test call.
4. Whether any capability you need (audio, references) is available on that host, per its model page.

When a detail is not stated on the model page, treat it as unknown and test with a short request. The call guide has runnable code, the model pages list hosts, and you can create a key to test. See also the pricing page.

Frequently asked questions

Keep reading

• Veo 3.1 vs Veo 3.1 Fast vs Lite — Which to Call from Your API
• Veo API Without Google Cloud: What You Skip and What You Keep
• Veo 3.1 Image-to-Video API: Request Shape and Workflow
• Veo 3.1 Cost Control: Drafts, Caching and Tier Gating