Gemini Files とキャッシュ
Gemini Files および cached content
Gemini ファイルのアップロード、および Workspace が所有するファイルと cached content の管理。
Gemini Files および cached content は、その操作をサポートする現在の TokenLab モデルで使用してください。リクエストを送信する前に、モデルの詳細を確認してサポートされているメソッドを確認してください。
Workspace の所有権
ファイルおよび cached content は、認証されたリクエストに関連付けられた Workspace に帰属します。作成、一覧表示、読み取り、参照、更新、削除を行うには、同じ Workspace を使用してください。リソース名やファイル URI によって所有権が移転することはありません。
Files
サポートされているソースには register を使用してください。これはローカルのバイトデータをアップロードするものではありません。ローカルファイルの場合は、そのバイトデータをアップロードエンドポイントに送信します。ファイルを一覧表示または読み取り、Gemini コンテンツで返された URI を使用する前に、ファイルが準備完了状態になるまで待機してください。ファイルは登録、読み取り、削除が可能ですが、これらのルートにはファイル更新操作は提供されていません。
Cached content
サポートされているモデル用に cached content を作成し、返された name を同じ Workspace からの後の generateContent リクエストで cachedContent として使用します。GET はキャッシュメタデータを読み取り、PATCH はその有効期間を更新し、DELETE はキャッシュを削除します。削除済みまたは期限切れのキャッシュは、生成に使用できません。
再開可能なアップロード (Resumable upload)
POST /upload/v1beta/files、X-Goog-Upload-Protocol: resumable、および X-Goog-Upload-Command: start を使用してセッションを開始します。メタデータを送信し、正確な X-Goog-Upload-URL レスポンスヘッダーを読み取ります。アップロードコマンドと確認済みのオフセットを使用して、各バイトチャンクをその URL に POST します。
この URL はプライベートな機能であり、継続を許可するもので、1時間で期限切れになります。秘密を保持し、公開、ログ記録、共有は行わないでください。汎用的な HTTP リダイレクトとして追跡しないでください。308 はチャンクが受け入れられたもののアップロードがまだ不完全であることを意味するため、同じ URL で継続してください。404 はセッションが存在しないか期限切れであることを意味します。410 は継続不可能であることを意味するため、新しいセッションを開始してください。最終的な成功レスポンスにファイルリソースが含まれている場合のみ、アップロードが完了したとみなしてください。
SDK のセットアップ
プロセス環境で TOKENLAB_API_KEY を設定します。Google Gen AI SDK を TokenLab ホストおよび v1beta API バージョンで構成します。
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" },
});キーとアップロード URL は、ソース管理、ブラウザストレージ、ログには含めないでください。
操作
| メソッド | パス | 操作 |
|---|---|---|
| POST | /v1beta/files:register | サポートされているソースを登録 |
| POST | /v1beta/files | ファイルメタデータを作成 |
| GET | /v1beta/files | ファイルを一覧表示 |
| GET | /v1beta/files/{fileId} | ファイルメタデータを読み取り |
| DELETE | /v1beta/files/{fileId} | ファイルを削除 |
| POST | /v1beta/cachedContents | cached content を作成 |
| GET | /v1beta/cachedContents | cached content を一覧表示 |
| GET | /v1beta/cachedContents/{cacheId} | cached content を読み取り |
| PATCH | /v1beta/cachedContents/{cacheId} | キャッシュの有効期間を更新 |
| DELETE | /v1beta/cachedContents/{cacheId} | cached content を削除 |
| POST | /upload/v1beta/files | バイトデータをアップロードまたはセッションを開始 |
| POST | /upload/v1beta/files/session/{sessionId} | 再開可能なアップロードを継続 |
一覧表示エンドポイントは pageSize および pageToken をサポートしています。返された cached-content 名を、後の Gemini リクエストで cachedContent として使用してください。すべてのフィールドについては、OpenAPI specification および コンテンツの生成 を参照してください。