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