Gemini 的缓存存储时长要单独计费：估成本时容易漏掉的一项
数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。
Gemini API 官方 FAQ 把计费依据写成四项：输入 token 数、输出 token 数、缓存的 token 数，以及缓存 token 的存储时长。前三项都是「按次」的——你发一次请求，它算一次。第四项不是，它按时间累积：缓存内容只要还在，计时就在走，哪怕这段时间里你一次请求都没发。估 Gemini 月成本时，很容易只把缓存当成「输入便宜了一截」，于是漏掉这条挂在时间上的支出。这篇把这项支出的来源、官方文档对两种缓存交代到哪一层、以及怎么把它算进预算里，按官方文档里能查到的部分讲一遍——查不到的地方也会明说查不到。
官方把计费依据列成四项，第四项和前三项不是一个维度
先把这条事实摆正。官方 FAQ 里列出的计费依据是四项：输入 token 数、输出 token 数、缓存的 token 数、缓存 token 的存储时长。
前三项的共同点是它们都由「一次请求」触发。你不调用，它们就是零。这也是绝大多数人对 API 计费的直觉模型：调用产生费用，不调用不产生费用。
第四项打破了这个直觉。存储时长是一个时间量，它的自变量不是请求数，而是「这份缓存内容在服务端存在了多久」。官方在长上下文文档里给的说法很直白：把用户上传的文件缓存起来，按小时为存储付费，换来的是重复提问时输入成本的下降。也就是说，缓存这件事在 Gemini 上被拆成了一笔交易——你付一份随时间累积的存储成本，去换重复请求时的输入成本下降。这笔交易划不划算，取决于你在缓存存活期内到底复用了多少次。
这个结构带来的第一个直接后果是：缓存不是「开了就一定省钱」的开关。如果你缓存了一份很大的上下文，然后接下来几个小时里只用了一两次，存储那一侧的成本照收，输入那一侧省下来的却很有限。反过来，一段高频复用的长上下文，存储成本会被大量复用摊薄。判断依据不是「内容够不够大」，而是「在它活着的这段时间里被复用得够不够密」。
如果你想先建立一个跨厂商的对照坐标系，可以先看站内那篇讲通用机制的 API 缓存计费机制，再回来看 Gemini 这一份的差别在哪里。
隐式缓存和显式缓存，在这件事上不能混为一谈
Gemini 提供隐式缓存和显式缓存两种。这两种在计费叙事里的位置不一样，混着讲很容易得出错的结论。
隐式缓存，官方说明是对 Gemini 2.5 及更新型号默认启用，无需任何操作；命中之后自动返还节省的费用。它同时支持有状态（通过 previous_interaction_id）与无状态两种对话模式。这条路径的特点是你什么都不用配，命中与否由服务端判断，省下来的部分以返还的形式体现。
显式缓存是与它并列的另一条路径。这里必须先划一条边界：本文查证到的官方说明里，显式缓存只交代了两件事——它存在，以及下面马上要讲的那条接口限制。至于「显式」这一侧具体怎么显式：用哪个接口把内容放进缓存、参数怎么写、一份缓存能存活多久、这个时长是否由调用方指定，本文都没有在官方文档里找到相关说明。这些请以官方缓存文档的当前版本为准。
同样需要划清的还有存储费的归属。官方在长上下文文档里描述的那条路径——把用户上传的文件缓存起来、按小时为存储付费，换取重复提问时输入成本的下降——用的措辞是「上下文缓存」，并没有言明它对应的是隐式还是显式。所以这里只能就事论事：按小时计存储费这件事官方是明说的；它归属于哪一种缓存，官方没有交代，别替官方把这层归属补上。
把这两条边界合起来说清楚：本文没有在官方文档里找到「存储费具体覆盖哪一种缓存、隐式缓存是否也单独计收存储费」的说明。已经明确的只有两点——计费依据里确实包含缓存 token 的存储时长；长上下文文档里明确写了缓存文件按小时付存储费。这两点之间的覆盖关系，请以官方定价页与缓存文档的当前版本为准，别按直觉外推。这类地方宁可去官网确认一次，也别拿一个想当然的结论去做预算。
隐式缓存怎么才能被命中，是另一个独立话题，站内有单独一篇讲 Gemini 隐式缓存的命中条件。
一个容易撞上的接口选型坑
还有一条和计费直接相关的接口限制：Interactions API 仅支持隐式缓存，不支持显式缓存。要用显式缓存，必须改用 generateContent API。
这条限制的现实意义在于，如果你的应用是照着 Interactions API 那条路径写的，那么凡是要走显式缓存的成本方案在当前接口下都不成立——不是配置没配对，是接口本身不支持，只能改用 generateContent。发现这件事的时机很关键：等到成本方案都做完了才发现要换 API，返工量比想象中大。所以选接口这一步就要把缓存策略一起定下来，别把它留到后面再补。
存储这一项在什么场景下会被点着
按官方长上下文文档的口径，上下文缓存被直接点名为长上下文场景下的主要优化手段。把这句话和上一节那条按小时计的存储费放在一起看，方向就清楚了：官方推荐用缓存的场景，恰恰是上下文体量本来就很大的场景，存储这一侧的分量自然也跟着上去。
官方在这一节里还承认了一个很少有人写的能力边界：「大海捞针」式的评估是最基本的设置，只找一根针；当你要找多根针或者特定信息时，准确率会变化，性能可能因上下文而变化很大。官方明确点出检索准确率与费用之间存在固有权衡——想在单次查询上拿到很高的准确率，代价是每次都要付全量输入 token 的费用；想检索大量条目还要保持高准确率，可能得发很多次请求。上下文缓存正是在后一种形态下成为降本关键的。
把这段话翻译成预算语言：当你的用法是「一份大上下文 + 多次追问」时，存储费是值得付的；当你的用法是「一份大上下文 + 问一次就走」时，缓存这条路本身就不成立。
另外还有一类内容需要单独留意：官方提到处理视频时必须注意视频是怎么被切成 token 的，因为这会影响结算与用量限额。视频进入长上下文的场景下，这句提醒的分量不轻。
怎么把这一项算进自己的账里
官方文档里能直接用上的手段有这么几个，都是具体字段和具体接口，不是泛泛的建议。
查缓存命中量：响应对象里的 usage.total_cached_tokens 字段，Python 与 JavaScript 都有。这是判断缓存到底有没有在起作用的第一手依据——如果这个数字长期贴地，说明你付了成本却没吃到收益，得回去看命中条件。
事前估 token：官方给的 token 计数方法是 GenerativeModel.count_tokens。在把一份大上下文推进缓存之前先数一遍，比事后看账单可控得多。
别只盯着控制台图表：官方在结算文档里明确写了几处延迟，其中结算流水线本身存在延迟（具体时长以官方文档为准），这段时间里可能继续产生超额用量；而总费用明细图表的更新滞后更明显（滞后上限同样以官方文档为准）。这意味着你在图表上看到的「今天花了多少」并不是当下的真实值。想做实时控制，得靠自己在调用侧统计 token，而不是靠刷控制台。这套思路在站内的 API 成本监控 里有更通用的展开。
用官方给的两级支出上限兜底：官方的支出上限分两级，结算账号级（每月）与项目级；项目级被官方标注为实验性、适用范围有限，设置项目级上限需要项目编辑者、所有者或管理员角色。项目迁移到其他结算账号时，支出上限设置会保留，但累计支出在新结算周期重置。
顺带提高一下命中率，别让存储费白付
存储费付了却命中不了，等于两头落空。官方给出的提高命中率的方法有两条：把较大且常见的内容放在提示开头；在短时间内发送具有相似前缀的请求。
同时官方长上下文 FAQ 里还有三条实操结论，和上面这两条并不矛盾，但顺序上要理清楚：一是把查询或问题放在提示的末尾，也就是放在所有其他上下文之后，尤其当总上下文很长的时候效果更好；二是不需要传给模型的 token 就别传；三是当你有一组要重复使用的相似上下文时，用上下文缓存来降本。
这几条合起来其实描述的是同一种提示结构：大块的、稳定的、要复用的内容压在前面，变动的问题放在最后。前半段稳定，缓存前缀才有机会被匹配上；后半段变动，才不会因为每次都改开头而让整段前缀失效。
还有一条限制要记住：隐式缓存有最低输入 token 门槛，而且这个门槛因模型而异，具体数值请查官方文档当前版本。这条的实际含义是——短提示根本进不了缓存这条路，在小请求上做缓存优化是白费力气。
最后一个坑：别让缓存活着但账号停了
如果你用的是预付款结算方案，有一条运维风险必须知道：预付款余额归零时，该结算账号下所有项目的所有 API 密钥会同时停止工作。这不是缓存本身的机制，但它和存储计费这种「不发请求也在扣」的支出叠加在一起时特别危险——你可能在一段没有业务流量的时间里，被一项按时间累积的支出慢慢拖到余额见底，然后在下一次真正需要调用的时候发现全线停摆。
所以这篇的结论浓缩成一句话：把缓存存储当成一项订阅式支出来管，而不是一项按次支出。上线前先用 count_tokens 估好体量，跑起来之后盯 usage.total_cached_tokens 看命中，成本这边不要依赖有滞后的控制台图表，账号那边把支出上限设好。至于每一档的具体单价和门槛数值，一律以官方定价页和缓存文档的当前版本为准——这些数字变得比文档写得还快。