Gemini Files and cached content

Use Gemini Files and cached content with a current TokenLab model that supports the operation. Check the model details for supported methods before sending a request.

Workspace ownershipCopy Anchor Link

Files and cached content belong to the Workspace associated with the authenticated request. Use that same Workspace to create, list, read, reference, update, and delete them. A resource name or file URI does not transfer ownership.

FilesCopy Anchor Link

Use register for a supported source; it does not upload local bytes. For a local file, send its bytes to the upload endpoint. List or read the file and wait until it is ready before using its returned URI in Gemini content. Files can be registered, read, and deleted; these routes do not provide a file update operation.

Cached contentCopy Anchor Link

Create cached content for a supported model, then use the returned name as cachedContent in a later generateContent request from the same Workspace. GET reads cache metadata, PATCH updates its lifetime, and DELETE removes it. A deleted or expired cache cannot be used for generation.

Resumable uploadCopy Anchor Link

Start a session with POST /upload/v1beta/files, X-Goog-Upload-Protocol: resumable, and X-Goog-Upload-Command: start. Send metadata and read the exact X-Goog-Upload-URL response header. POST each byte chunk to that URL with the upload command and acknowledged offset.

The URL is a private capability: it authorizes continuation and expires after one hour. Keep it secret; do not publish, log, or share it. Do not follow it as a generic HTTP redirect. A 308 means the chunk was accepted but the upload is still incomplete, so continue at the same URL. A 404 means the session is missing or expired. A 410 means it can no longer continue; start a new session. Treat upload as complete only when the final successful response contains the file resource.

SDK setupCopy Anchor Link

Set TOKENLAB_API_KEY in the process environment. Configure the Google Gen AI SDK with the TokenLab host and v1beta API version:

import os
from google import genai

client = genai.Client(
    api_key=os.environ["TOKENLAB_API_KEY"],
    http_options={"base_url": "https://api.tokenlab.sh", "api_version": "v1beta"},
)

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
  apiKey: process.env.TOKENLAB_API_KEY,
  httpOptions: { baseUrl: "https://api.tokenlab.sh", apiVersion: "v1beta" },
});

Keep the key and upload URL out of source control, browser storage, and logs.

OperationsCopy Anchor Link

The list endpoints support pageSize and pageToken. Use the returned cached-content name as cachedContent in a later Gemini request. See the OpenAPI specification and Generate Content for all fields.