Skip to main content

Veo 3.1

Veo 3.1 is Google’s video model. It generates a clip with native audio from a text prompt or from a starting image. The call is asynchronous: submit a job, poll the operation until done is true, then download the clip. The request and response shapes mirror Google’s own API.

Models

Veo 3.1 ships in three tiers. Each tier is a model ID that you name in the submit path. The request body is identical across tiers. Every tier generates native audio with the picture. Use Standard when quality matters most. It has the highest fidelity. Use Fast for iteration. It is quicker and cheaper than Standard, and it still reaches 4K. Use Lite for the cheapest runs. It is the most economical tier. It stops at 1080p, so it does not accept a 4K request.

Endpoints

The base URL is https://api.nunchux.ai. {model} is the model ID of the tier. {handle} is the name that the submit returns.

Request

Send your API key in the X-API-Key header. See Authentication. Set Content-Type: application/json on the submit. Send a User-Agent header that names your application, for example YourApp/1.0. The body carries a single instances entry (the prompt, plus a starting image for image-to-video) and optional parameters.
array
required
One generation request. Veo takes a single instance.
object
Generation controls.
Image inputSend bytesBase64Encoded with its mimeType. Google’s own Veo REST documentation shows an inlineData wrapper. Do not copy it here. Send bytesBase64Encoded.

Response

The submit returns only the operation handle. Poll it until done is true. On success, the video URL is under response.generateVideoResponse.generatedSamples[0].video.uri.

Submit

string
required
The operation handle. Poll GET /v1/google/v1beta/operations/{handle} with it. The handle is opaque and variable in length (about 260 characters), with no operations/ prefix. Store it as an unbounded string, not in a fixed-width column sized from the sample.

Poll

string
required
The operation handle, echoed back.
boolean
required
false while the job runs. true once the video is ready or the job failed. Check error before you read response.
object
Present once done is true and the job failed. response is then absent. Carries a message that describes the failure.
object
Present once done is true and the job succeeded.
The status of the job follows from done and from which of error and response is present.

Example

Submit, poll, download. Swap the model ID in the submit path for the tier that you want. The poll starts at 5 s and backs off to 30 s.

Tips

  • Poll, do not busy-wait. Veo usually takes 1 to 4 min. Poll every 5 to 10 s at first, then back off to 30 s.
  • Polls are free, and they never take a simultaneous-job slot.
  • Set client timeouts to 10 min or more. Render time scales with clip length.
  • Check error before you read response. done is true on failure too.
  • Download the clip as soon as done is true. The output URL expires about an hour after the operation completes, so do not store the URL.
  • Store name as an unbounded string, and poll with that exact value.
  • Pick durationSeconds deliberately. You are billed per output-second, so 4, 6 and 8 s each cost differently.
  • Use Lite for cheap iteration and Standard when fidelity matters. 4K is available on Standard and Fast only.
  • Do not double-submit. A submit reserves credits, so resubmitting a running job charges twice. If the submit returned a name, poll it.

Errors and limits

  • A 200 on the submit is acceptance, not success. A failed job does not return an HTTP error. It appears in the poll as done: true with error, and error.message explains the failure. Read it before you resubmit.
  • durationSeconds is 4, 6 or 8. resolution is 720p, 1080p or 4k, and 4k is available on Standard and Fast only. A parameter that is out of range, such as a Lite request for 4k, is rejected with a 400. A 400 is never charged.
  • Veo is priced per output-second times the duration, reserved at submit. A job that ends in failure is refunded automatically. The rates are on the pricing page. See Credits and pricing.
  • A submit takes a simultaneous-job slot. Polls do not. See Rate limits.
  • A 5xx or a timeout on the submit does not tell you whether the job was created, so a bare resubmit can bill twice. If the submit returned a name, poll it. If it returned nothing, check GET /v1/credits before you try again. A charge with no delivered job is refunded automatically.
  • A 5xx on a poll is safe to retry with backoff. Polls change nothing.
  • A 503 with the code google_unreachable means that Google could not be reached before anything was sent. Nothing was charged. Retry with backoff.
  • A 503 whose message says google pass-through not enabled means that the route is not available. Do not retry it in a loop.
The full error contract, the retry rules and the per-plan caps are on the Errors and Rate limits pages. How every asynchronous partner model submits, polls, bills and refunds is on the Partner models overview.