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.
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
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
{ "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: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.