# Gemini 上下文缓存
> Gemini 的缓存有两种形态：隐式与显式
> 隐式由服务端自动判断，无需操作
> 显式需要先创建缓存对象，再按对象引用，适合极大且反复使用的内容
## 两种形态的区别
| 形态 | 创建方式 | 适合场景 | 有效期 |
|---|---|---|---|
| 隐式 | 自动，无需操作 | 短时间内的连续同类请求 | 较短，由服务端管理 |
| 显式 | 调用创建接口 | 超长文档、视频、音频反复问 | 显式指定，按小时计 |
## 隐式缓存
只要连续请求的前缀一致，服务端会自动复用，无需任何参数。响应里 `usageMetadata` 会给出命中量。
- `usageMetadata.cachedContentTokenCount` (integer) — 命中缓存的 token 数。未命中时不出现。
## 显式缓存
显式缓存分两步：先创建缓存拿一个 `name`，之后请求里引用这个 `name`。
- `model` (string / 必填) — 要缓存的模型 ID。
- `contents` (array / 必填) — 要缓存的内容，结构与 generateContent 的 `contents` 一致。可以是长文、图片或音视频。
- `ttl` (string / 必填) — 有效期，写成 `3600s` 这样的时长字符串。到期后缓存自动删除。
- `displayName` (string / 可选) — 便于识别的名字，仅用于管理，不参与推理。
## 使用缓存
在 `generateContent` 请求里传 `cachedContent`，填创建时返回的完整 `name`：
```json
{
  "cachedContent": "cachedContents/abc123xyz",
  "contents": [
    { "parts": [{ "text": "这份文档的核心结论是什么？" }] }
  ]
}
```
> **Note:** 
> 引用缓存时，`contents` 里只需要放新增的问题部分。如果把已经缓存的内容再贴一遍，反而可能让请求失败或重复计费。
## 计费方式
显式缓存按「缓存存储时长」和「缓存内容大小」计费，与按 token 计费的推理分开算。命中的推理请求，输入侧按折扣计价。
缓存内容越大、使用次数越多，摊薄下来越划算。如果只问一次，显式缓存反而更贵。
## 使用示例
### 创建显式缓存
先把长内容提交成缓存，拿到 `cachedContent` 名称。这一步本身不计推理费，只按存储时长计费。
### 引用缓存发问
生成内容时用 `cachedContent` 字段引用上一步返回的名称，`contents` 里只放这次的新问题。
### 依赖隐式缓存
不显式创建缓存时，Gemini 会在服务端自动复用相同前缀。同一次会话里连续追问，通常能自动命中，不需要额外参数。
**创建显式缓存{Create explicit cache}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1beta/cachedContents' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "models/gemini-3.8-flash",
    "contents": [{
      "role": "user",
      "parts": [{ "text": "以下是三千页技术手册的全文：……" }]
    }],
    "ttl": "3600s"
  }'
```
**创建显式缓存{Create explicit cache}::Python**
```
import requests
url = "https://api.oairoute.com/v1beta/cachedContents"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "model": "models/gemini-3.8-flash",
    "contents": [{
      "role": "user",
      "parts": [{ "text": "以下是三千页技术手册的全文：……" }]
    }],
    "ttl": "3600s"
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**创建显式缓存{Create explicit cache}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1beta/cachedContents", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "models/gemini-3.8-flash",
    "contents": [{
      "role": "user",
      "parts": [{ "text": "以下是三千页技术手册的全文：……" }]
    }],
    "ttl": "3600s"
  }),
});
console.log(await res.json());
```
**引用缓存发问{Query with cache}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1beta/models/gemini-3.8-flash:generateContent' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "cachedContent": "cachedContents/abc123",
    "contents": [{
      "role": "user",
      "parts": [{ "text": "手册里关于超时重试是怎么规定的" }]
    }]
  }'
```
**引用缓存发问{Query with cache}::Python**
```
import requests
url = "https://api.oairoute.com/v1beta/models/gemini-3.8-flash:generateContent"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "cachedContent": "cachedContents/abc123",
    "contents": [{
      "role": "user",
      "parts": [{ "text": "手册里关于超时重试是怎么规定的" }]
    }]
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**引用缓存发问{Query with cache}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1beta/models/gemini-3.8-flash:generateContent", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "cachedContent": "cachedContents/abc123",
    "contents": [{
      "role": "user",
      "parts": [{ "text": "手册里关于超时重试是怎么规定的" }]
    }]
  }),
});
console.log(await res.json());
```
**依赖隐式缓存{Implicit cache}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1beta/models/gemini-3.8-flash:generateContent' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [
      { "role": "user", "parts": [{ "text": "以下是三千页技术手册的全文：……" }] },
      { "role": "user", "parts": [{ "text": "手册里关于超时重试是怎么规定的" }] }
    ]
  }'
```
**依赖隐式缓存{Implicit cache}::Python**
```
import requests
url = "https://api.oairoute.com/v1beta/models/gemini-3.8-flash:generateContent"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "contents": [
      { "role": "user", "parts": [{ "text": "以下是三千页技术手册的全文：……" }] },
      { "role": "user", "parts": [{ "text": "手册里关于超时重试是怎么规定的" }] }
    ]
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**依赖隐式缓存{Implicit cache}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1beta/models/gemini-3.8-flash:generateContent", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "contents": [
      { "role": "user", "parts": [{ "text": "以下是三千页技术手册的全文：……" }] },
      { "role": "user", "parts": [{ "text": "手册里关于超时重试是怎么规定的" }] }
    ]
  }),
});
console.log(await res.json());
```
**200 创建显式缓存{Create explicit cache}**
```
{
  "name": "cachedContents/abc123",
  "model": "models/gemini-3.8-flash",
  "createTime": "2026-11-03T08:00:00Z",
  "updateTime": "2026-11-03T08:00:00Z",
  "expireTime": "2026-11-03T09:00:00Z",
  "usageMetadata": {
    "totalTokenCount": 9824
  }
}
```
**200 引用缓存发问{Query with cache}**
```
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "手册规定：超时按指数退避重试，最多三次。"
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9840,
    "candidatesTokenCount": 42,
    "totalTokenCount": 9882,
    "cachedContentTokenCount": 9824
  },
  "modelVersion": "gemini-3.8-flash"
}
```
**200 依赖隐式缓存{Implicit cache}**
```
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "手册规定：超时按指数退避重试，最多三次。"
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9840,
    "candidatesTokenCount": 42,
    "totalTokenCount": 9882,
    "cachedContentTokenCount": 9728
  },
  "modelVersion": "gemini-3.8-flash"
}
```