Files (Gemini)¶
Gemini's Files API holds large media (video, audio, long PDFs) that you then refer to in prompts. Through the gateway you upload, list and delete files with your Vidai key, every upload is recorded (name, type and size, never the content), and your Vidai key never appears in a URL.
What it is¶
| Call | Path |
|---|---|
| Upload, step 1: start | POST /upload/v1beta/files |
| Upload, step 2: the bytes | The upload address Google returns in step 1 |
| List | GET /v1beta/files |
| Details | GET /v1beta/files/{name} |
| Delete | DELETE /v1beta/files/{name} |
Files are a Gemini API (Google AI Studio) feature. Vertex AI has no Files API: on Google Cloud, put media in Cloud
Storage and refer to it by gs:// URI (see Vertex AI).
The two settings¶
The same as for Generate content: base address https://<your-gateway>, API version v1beta,
and your Vidai key as the API key. With SDK 3.0 and later the API version matters for uploads too: on v1 the SDK
starts uploads at /upload/v1/files, which the gateway doesn't serve.
Which provider holds the file¶
A file call names no model. The gateway picks the Gemini provider: one named in an x-provider header; otherwise the
one whose Files API and batches setting is Served; otherwise the only Gemini provider. If several qualify and
none is chosen, the call gets a 400 naming them, and an admin sets Files API and batches to Served on one under
Providers. A Gemini file call never goes to another vendor.
The two-step upload¶
Google's upload has two steps, and the gateway keeps your key out of every address:
- Start. Your client sends the file's name, type and size to the gateway. The gateway sends the start call to Google with its own Google key, as a header, and records what you declared.
- Bytes. Google answers with an upload address in the
x-goog-upload-urlheader. The gateway passes it back with anykey=parameter removed, and your client sends the bytes to that address. Google's SDKs send them to their base URL's host instead, so with the gateway as base URL the bytes go through the gateway too, with your Vidai key; a client that uses the address as given (curl, for example) sends them straight to Google.
A minimal call¶
from google import genai
from google.genai import types
client = genai.Client(
api_key="vk_…",
http_options=types.HttpOptions(base_url="https://<your-gateway>", api_version="v1beta"),
)
video = client.files.upload(file="launch.mp4", config={"mime_type": "video/mp4"})
response = client.models.generate_content(
model="gemini-3.5-flash",
contents=[video, "Summarise this video in three lines."],
)
print(response.text)
for f in client.files.list():
print(f.name, f.size_bytes)
client.files.delete(name=video.name)
import { GoogleGenAI, createPartFromUri, createUserContent } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "vk_…", apiVersion: "v1beta", httpOptions: { baseUrl: "https://<your-gateway>" } });
const video = await ai.files.upload({ file: "launch.mp4", config: { mimeType: "video/mp4" } });
const response = await ai.models.generateContent({
model: "gemini-3.5-flash",
contents: createUserContent([createPartFromUri(video.uri!, video.mimeType!), "Summarise this video in three lines."]),
});
console.log(response.text);
await ai.files.delete({ name: video.name! });
SIZE=$(wc -c < launch.mp4)
# Step 1: start, through the gateway. Keep the upload address from the answer's headers.
UPLOAD_URL=$(curl -s -D - -o /dev/null https://<your-gateway>/upload/v1beta/files \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "X-Goog-Upload-Protocol: resumable" \
-H "X-Goog-Upload-Command: start" \
-H "X-Goog-Upload-Header-Content-Length: $SIZE" \
-H "X-Goog-Upload-Header-Content-Type: video/mp4" \
-H "content-type: application/json" \
-d '{"file":{"display_name":"launch"}}' | tr -d '\r' | awk -F': ' 'tolower($1)=="x-goog-upload-url"{print $2}')
# Step 2: the bytes, to the address Google returned.
curl "$UPLOAD_URL" \
-H "Content-Length: $SIZE" \
-H "X-Goog-Upload-Offset: 0" \
-H "X-Goog-Upload-Command: upload, finalize" \
--data-binary @launch.mp4
The last answer describes the file; its uri goes into a prompt as
{"fileData":{"mimeType":"video/mp4","fileUri":"…"}}.
Reading what the gateway did¶
The start call, list, details and delete carry x-vidai-request-id and x-vidai-provider-key (the provider key's
label, never its secret). With an upload, the gateway records the file's name, type and declared size, never its
content.
Errors¶
In Google's shape ({"error":{"code","message","status"}}). Match on x-vidai-error-code:
| Status | Why |
|---|---|
400 INVALID_ARGUMENT |
No Gemini provider serves files, several do and none is chosen, or this gateway is set to refuse Gemini uploads (listing, details and delete still work) |
| 401, 403 | Key codes, as on Generate content |
404 NOT_FOUND |
The upload started at /upload/v1/files: set the API version to v1beta |
What goes through the gateway¶
| Call | Gemini (Google AI Studio) | Vertex AI, other vendors |
|---|---|---|
| Upload, list, details, delete | Yes | No: Vertex AI has no Files API; use Cloud Storage |
A file's uri in a prompt to a Gemini model |
Yes | |
A file's uri in a prompt to another provider's model |
The call goes ahead without it; fileData is reported in x-vidai-adapted |
Check it works in a minute¶
curl -s https://<your-gateway>/v1beta/files -H "x-goog-api-key: $GEMINI_API_KEY"
A JSON answer (an empty one is fine) means files reach your Gemini provider.
Good to know¶
- Files are shared across keys. Google stores them under the one account the gateway uses, so any Vidai key can list and delete every file there, whichever key uploaded it.
- Google deletes files by itself after 48 hours.
- Guardrails don't read file contents, and uploads are never retried on another provider.