Cached Contents
透過 Gemini 原生協議管理顯式上下文快取（cachedContents）：主動把一段大上下文快取為一個物件，跨請求引用，命中確定性更高、計費更低。OfoxAI 相容 Google GenAI SDK。
顯式快取的使用場景、與隱式快取的區別、最佳實踐見 Gemini 顯式快取指南。本頁是端點級 API 參考。
端點
POST https://api.ofox.ai/gemini/v1beta/cachedContents # 建立
GET https://api.ofox.ai/gemini/v1beta/cachedContents/{id} # 查詢
DELETE https://api.ofox.ai/gemini/v1beta/cachedContents/{id} # 刪除引用快取做內容生成，走標準 generateContent 端點，請求體帶 cachedContent 欄位：
POST https://api.ofox.ai/gemini/v1beta/models/{model}:generateContent認證
使用 x-goog-api-key Header：
x-goog-api-key: <你的 OFOXAI_API_KEY>資源欄位
CachedContent 資源的主要欄位：
| 欄位 | 類型 | 說明 |
|---|---|---|
name | string（唯讀） | 快取控制代碼，形如 cachedContents/{id}，建立後回傳 |
model | string（必填，不可變） | 快取繫結的模型，如 models/gemini-3.1-pro-preview |
contents | array | 要快取的內容（與 generateContent 的 contents 同結構） |
systemInstruction | object | 要快取的系統指令（可選） |
tools | array | 要快取的工具定義（可選） |
ttl | string | 存活時長，秒數字串（如 "600s"）；與 expireTime 二選一 |
expireTime | string | 過期時間點（RFC 3339）；與 ttl 二選一 |
displayName | string（不可變） | 自訂名稱（可選） |
usageMetadata.totalTokenCount | integer | 被快取的 token 數（用於計費） |
TTL 支援範圍：最小 / 預設 600s（10 分鐘），最大 3600s（1 小時）。
建立快取
Python
create.py
from google import genai
from google.genai import types
client = genai.Client(
api_key="<你的 OFOXAI_API_KEY>",
http_options={"api_version": "v1beta", "base_url": "https://api.ofox.ai/gemini"},
)
cache = client.caches.create(
model="google/gemini-3.1-pro-preview",
config=types.CreateCachedContentConfig(
contents=[open("knowledge_base.txt").read()],
system_instruction="你是一個只依據所給文件回答的助手。",
ttl="600s",
display_name="kb-v1",
),
)
print(cache.name) # cachedContents/xxxxxxxx
print(cache.usage_metadata.total_token_count)回應
{
"name": "cachedContents/xxxxxxxx",
"model": "google/gemini-3.1-pro-preview",
"createTime": "2026-06-26T08:00:00Z",
"updateTime": "2026-06-26T08:00:00Z",
"expireTime": "2026-06-26T08:10:00Z",
"displayName": "kb-v1",
"usageMetadata": {
"totalTokenCount": 14407
}
}查詢 / 刪除
查詢、刪除無需傳 model，OfoxAI 憑快取控制代碼定位上游。
Python
manage.py
# 查詢單條
info = client.caches.get(name=cache.name)
print(info.expire_time)
# 刪除
client.caches.delete(name=cache.name)引用快取生成
在 generateContent 請求體加 cachedContent 欄位引用快取，contents 只放本次新增的問題：
Python
use.py
response = client.models.generate_content(
model="google/gemini-3.1-pro-preview",
contents="根據上面的文件，總結三條要點",
config=types.GenerateContentConfig(cached_content=cache.name),
)
print(response.text)
print(response.usage_metadata.cached_content_token_count) # 命中的快取 token 數命中時，回應 usageMetadata.cachedContentTokenCount 顯示走快取的 token 數。
計費
| 階段 | 計費公式 |
|---|---|
| 建立快取 | totalTokenCount × cache_write 單價 |
| 引用命中 | cachedContentTokenCount × cache_read 單價（約標準輸入價 0.10x） |
| 引用新內容 | 本次新增 prompt / 輸出按標準價 |
各模型 cache_write / cache_read 單價見 模型目錄 。
OfoxAI 在多 GCP 專案間負載平衡，顯式快取為區域繫結（region-scoped）。OfoxAI 自動憑快取控制代碼硬鎖回建立快取的上游，引用零漂移；快取控制代碼僅建立它的 API Key 可引用 / 查詢 / 刪除（跨帳戶存取回傳 403）。詳見 顯式快取指南 · 確定性路由。
相關文件
Last updated on