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 untildone 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 ishttps://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 theX-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 untildone 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.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
errorbefore you readresponse.doneistrueon failure too. - Download the clip as soon as
doneistrue. The output URL expires about an hour after the operation completes, so do not store the URL. - Store
nameas an unbounded string, and poll with that exact value. - Pick
durationSecondsdeliberately. 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
200on the submit is acceptance, not success. A failed job does not return an HTTP error. It appears in the poll asdone: truewitherror, anderror.messageexplains the failure. Read it before you resubmit. durationSecondsis4,6or8.resolutionis720p,1080por4k, and4kis available on Standard and Fast only. A parameter that is out of range, such as a Lite request for4k, is rejected with a400. A400is 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
5xxor 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 aname, poll it. If it returned nothing, checkGET /v1/creditsbefore you try again. A charge with no delivered job is refunded automatically. - A
5xxon a poll is safe to retry with backoff. Polls change nothing. - A
503with the codegoogle_unreachablemeans that Google could not be reached before anything was sent. Nothing was charged. Retry with backoff. - A
503whose message saysgoogle pass-through not enabledmeans that the route is not available. Do not retry it in a loop.