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

计费

相关文档