跳转到主要内容
API易 的 Gemini 通道自动启用隐式上下文缓存（implicit caching）：请求前缀命中时按官方折扣计费，cached_content_token_count 字段原样回吐，零代码改动。 先说结论：Gemini 缓存”有，但别指望” —— 隐式缓存的命中行为由上游控制，实际命中率明显不如 OpenAI 和 Claude。把它当作”有则更好”的额外优惠，做成本测算时一律按无缓存价格估算。 本页基于 Google 官方文档整理（ai.google.dev/gemini-api/docs/caching，2026年6月数据）。

​
机制一句话

请求开头部分（前缀）与近期请求相同且达到最小长度时，上游自动复用缓存：命中部分按官方折扣计费（官方口径最高可省 90%），无需打任何标记。

​
触发条件

条件要求
最小前缀长度Gemini 3 / 3.1 / 3.5 系列：4096 tokens；2.5 系列：2048 tokens
前缀稳定从第一个字符起逐字节相同，动态内容（时间戳、随机 ID）会切断匹配
时间窗口缓存会在闲置一段时间后过期，短时间内的连续请求更容易命中
注意 Gemini 的起缓阈值（4096）比 OpenAI（1024）高不少 —— 短系统提示词在 Gemini 上基本不会命中，这是”Gemini 缓存体感差”的原因之一。

​
怎么判断命中

看 usage_metadata.cached_content_token_count： 
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=[LONG_STABLE_PREFIX, question]
)

usage = response.usage_metadata
print(f"输入: {usage.prompt_token_count}")
print(f"缓存命中: {usage.cached_content_token_count}")  # > 0 即命中
命中部分在后台账单中按折扣倍率单列计费项；REST 响应里的对应字段为 usageMetadata.cachedContentTokenCount。

​
尽量提高命中率

方法论和 OpenAI 一致（详细解释见 OpenAI 缓存计费指南）：
  • 稳定内容放前面：长系统指令、文档、few-shot 示例在前；用户输入、时间戳在后
  • 前缀做长：不足 4096 tokens（Gemini 3 系）的前缀永远不会命中
  • 短时间内集中复用：批量任务连续发，不要拉开间隔
  • 多轮对话天然是追加式前缀，相对容易命中
即便全部做对，也不保证命中 —— 隐式缓存是 best-effort 的，这点和 OpenAI/Claude 的确定性行为不同。

​
显式缓存（cachedContents）

Google 官方还有显式缓存 API（cachedContents，创建一个有 TTL 的缓存对象再引用）。该接口是有状态的服务端资源，API易 通道暂不支持，请使用隐式缓存。

​
与其它通道对比

GeminiOpenAIClaude
触发隐式自动全自动手动标记
最小阈值4096（3 系）/ 2048（2.5 系）10241024–4096
命中折扣官方口径最高省 90%命中 0.1×命中 0.1×
命中稳定性⚠️ 不保证，体感一般✅ 稳定✅ 稳定
命中字段cached_content_token_countcached_tokenscache_read_input_tokens
缓存敏感的高频长前缀业务（Agent、RAG、批量文档），建议优先选 OpenAI 或 Claude 通道。 全平台缓存支持总览见 缓存计费 FAQ。

​
相关链接