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.8-flash`
`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.8-flash",
    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)

TypeScript

create.ts


import { GoogleGenAI } from '@google/genai'
import fs from 'node:fs'
 
const ai = new GoogleGenAI({
  apiKey: '<你的 OFOXAI_API_KEY>',
  httpOptions: { apiVersion: 'v1beta', baseUrl: 'https://api.ofox.ai/gemini' },
})
 
const cache = await ai.caches.create({
  model: 'google/gemini-3.8-flash',
  config: {
    contents: [fs.readFileSync('knowledge_base.txt', 'utf-8')],
    systemInstruction: '你是一個只依據所給文件回答的助手。',
    ttl: '600s',
    displayName: 'kb-v1',
  },
})
 
console.log(cache.name) // cachedContents/xxxxxxxx
console.log(cache.usageMetadata?.totalTokenCount)

cURL

Terminal


curl "https://api.ofox.ai/gemini/v1beta/cachedContents" \
  -H "x-goog-api-key: $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.8-flash",
    "contents": [
      { "role": "user", "parts": [{ "text": "<要快取的大段上下文>" }] }
    ],
    "ttl": "600s"
  }'

回應


{
  "name": "cachedContents/xxxxxxxx",
  "model": "google/gemini-3.8-flash",
  "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)

TypeScript

manage.ts


// 查詢單條
const info = await ai.caches.get({ name: cache.name })
console.log(info.expireTime)
 
// 刪除
await ai.caches.delete({ name: cache.name })

cURL

Terminal


# 查詢單條
curl "https://api.ofox.ai/gemini/v1beta/cachedContents/xxxxxxxx" \
  -H "x-goog-api-key: $OFOX_API_KEY"
 
# 刪除
curl -X DELETE "https://api.ofox.ai/gemini/v1beta/cachedContents/xxxxxxxx" \
  -H "x-goog-api-key: $OFOX_API_KEY"

引用快取生成

在 generateContent 請求體加 cachedContent 欄位引用快取，contents 只放本次新增的問題：

Python

use.py


response = client.models.generate_content(
    model="google/gemini-3.8-flash",
    contents="根據上面的文件，總結三條要點",
    config=types.GenerateContentConfig(cached_content=cache.name),
)
 
print(response.text)
print(response.usage_metadata.cached_content_token_count)  # 命中的快取 token 數

TypeScript

use.ts


const response = await ai.models.generateContent({
  model: 'google/gemini-3.8-flash',
  contents: '根據上面的文件，總結三條要點',
  config: { cachedContent: cache.name },
})
 
console.log(response.text)
console.log(response.usageMetadata?.cachedContentTokenCount) // 命中的快取 token 數

cURL

Terminal


curl "https://api.ofox.ai/gemini/v1beta/models/google/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cachedContent": "cachedContents/xxxxxxxx",
    "contents": [
      { "role": "user", "parts": [{ "text": "根據上面的文件，總結三條要點" }] }
    ]
  }'

命中時，回應 usageMetadata.cachedContentTokenCount 顯示走快取的 token 數。

計費

階段	計費公式
建立快取	`totalTokenCount × cache_write 單價`
引用命中	`cachedContentTokenCount × cache_read 單價`（約標準輸入價 0.10x）
引用新內容	本次新增 prompt / 輸出按標準價

各模型 cache_write / cache_read 單價見模型目錄。

OfoxAI 在多 GCP 專案間負載平衡，顯式快取為區域繫結（region-scoped）。OfoxAI 自動憑快取控制代碼硬鎖回建立快取的上游，引用零漂移；快取控制代碼僅建立它的 API Key 可引用 / 查詢 / 刪除（跨帳戶存取回傳 403）。詳見顯式快取指南 · 確定性路由。

Cached Contents

端點

認證

資源欄位

建立快取

Python

TypeScript

cURL

回應

查詢 / 刪除

Python

TypeScript

cURL

引用快取生成

Python

TypeScript

cURL

計費

相關文件