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. A photo someone in your workspace keeps as their saved photo in the studio answers 404: only that person sees it, and a key can’t read it or run it.

Delete a file

Deletes the file and its bytes, and returns { "id": "file_...", "object": "file", "deleted": true }. Runs that already used it keep their results. A file you made from a run’s output loses only its ID, and the run keeps the output. A photo the photo check blocked loses its bytes, but its ID keeps the block, so runs that name it are refused with photo_blocked once the paused check runs again. While a run that hasn’t finished uses the file, or while someone in your workspace keeps it as their saved photo in the studio, the answer is 409 file_in_use.

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 17, 2026