# Gemini cachedContents API — 显式缓存

Source: https://ofox.ai/zh/docs/api/gemini/cached-contents

通过 Gemini 原生协议管理**显式上下文缓存**（cachedContents）：主动把一段大上下文缓存为一个对象，跨请求引用，命中确定性更高、计费更低。OfoxAI 兼容 Google GenAI SDK。

显式缓存的使用场景、与隐式缓存的区别、最佳实践见 [Gemini 显式缓存指南](https://ofox.ai/zh/docs/develop/advanced/gemini-explicit-cache)。本页是端点级 API 参考。

## 端点

```http
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` 字段：

```http
POST   https://api.ofox.ai/gemini/v1beta/models/{model}:generateContent
```

## 认证

使用 `x-goog-api-key` Header：

```bash
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**

```python filename="create.py" showLineNumbers
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**

```typescript filename="create.ts" showLineNumbers
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**

```bash filename="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"
  }'
```

### 响应

```json
{
  "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**

```python filename="manage.py" showLineNumbers
# 查询单条
info = client.caches.get(name=cache.name)
print(info.expire_time)

# 删除
client.caches.delete(name=cache.name)
```

**TypeScript**

```typescript filename="manage.ts" showLineNumbers
// 查询单条
const info = await ai.caches.get({ name: cache.name })
console.log(info.expireTime)

// 删除
await ai.caches.delete({ name: cache.name })
```

**cURL**

```bash filename="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**

```python filename="use.py" showLineNumbers
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**

```typescript filename="use.ts" showLineNumbers
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**

```bash filename="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` 单价见 [模型目录](https://ofox.ai/zh/models)。

OfoxAI 在多 GCP 项目间负载均衡，显式缓存为区域绑定（region-scoped）。OfoxAI 自动凭缓存句柄硬锁回创建缓存的上游，**引用零漂移**；缓存句柄仅创建它的 API Key 可引用 / 查询 / 删除（跨账户访问返回 403）。详见 [显式缓存指南 · 确定性路由](https://ofox.ai/zh/docs/develop/advanced/gemini-explicit-cache)。

## 相关文档

- [Gemini 显式缓存指南](https://ofox.ai/zh/docs/develop/advanced/gemini-explicit-cache)
- [Gemini generateContent API](https://ofox.ai/zh/docs/api/gemini/generate-content)
- [提示缓存（隐式缓存）](https://ofox.ai/zh/docs/develop/advanced/prompt-caching)