Skip to main content
Models that edit, animate or listen take files as input, by ID. Upload the file first, then put its id (file_...) in the input field the model’s input schema names, such as photo, first_frame or images. A field that takes a file has the pattern ^file_[0-9A-Za-z]{24}$. Models don’t take URLs.

Upload an image

Send the image itself as the request body. There’s no multipart encoding:
POST /v1/files takes PNG, JPEG or WebP images up to 4 MB. The type is read from the file’s bytes, not the header. filename is optional. Videos and sounds go through direct uploads, whatever their size. To make a larger photo fit, resize it first, for example to 2048 pixels on its long side. On macOS, sips -Z 2048 photo.jpg does it in place; in code, use Pillow in Python or sharp in Node.js. Then pass the ID:

Upload a video or a sound

Videos and sounds go straight to storage in three steps: ask for an upload URL, PUT the file there, then complete the upload. The upload becomes a file with the same ID.
The upload answer:
content_type takes one of these values: Completing an upload reads the file’s type and length from its bytes, not from the content_type you declared. If the bytes aren’t an MP4, MOV or WebM video or an MP3, WAV or M4A sound, or the file breaks a limit above, completing gets a 400 with param set to file, and the bytes are deleted, so start a new upload. Completing before the file has arrived is a 404. Completing the same upload again returns the same file. bytes counts toward the day’s 5 GB when you start the upload, whether or not you complete it. An upload stops counting toward the 10 in flight once it’s completed, refused or past its URL’s hour.

Read a file

Returns the file with a fresh url, valid for 24 hours.

Feed one run into the next

Output links expire after 24 hours, but you don’t need to download and upload an image to use it again. Turn an output into a file of your workspace and pass its ID:
The 0 is the output’s index. This works for the image outputs of a succeeded generation; anything else gets a 400. Calling it again returns the same file. For example, make a still with an image model, keep it, then animate it with google/veo-3.1-fast by passing the file ID as first_frame. Turn a photo into a video does the same with a photo you upload, in one script.

How long files last

The outputs of your runs are kept as long as your workspace exists. Only their links expire: read the generation or the file again for a fresh one. Files you upload are kept too, for now. If we ever set a limit on how long they’re kept, we’ll announce it before it applies. A direct upload that’s never completed is deleted a day after its URL expires. If the URL expired before your file arrived, start a new upload.
Last modified on October 4, 2026