Gemini 限流是按项目算的，不是按 API 密钥算的

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

Gemini API 的速率限制按项目（project）应用，不按 API 密钥应用。 这句话是官方限流文档里的明文，值得在动手排查前先记牢。它的直接后果是：在同一个项目下再签发几把新密钥，它们共享同一份配额，用量合并计入，谁先发请求谁先把额度吃掉，换密钥这个动作对限流没有任何缓解作用。官方还把这层关系往上又推了一级——API 密钥没有独立的结算设置，它继承所属项目的层级与结算状态；而层级、限流、账号上限这三样都是在结算账号级别确定的，不在项目级别。所以真实的层次是三段：结算账号决定你处在哪个层级、限流规模有多大，项目是限流实际的计数单位，密钥只是进门的凭证。搞错任何一段，排查方向都会跑偏。

先看清楚被计数的到底是哪几个维度

官方列出的基本维度有三个：RPM（每分钟请求数）、TPM（每分钟输入 token 数）、RPD（每日请求数）。这三个是并列关系，超出任何一个维度就会触发限流错误，不是把三项综合起来评估。这一点非常容易在实现重试逻辑时写反：有人会想当然地认为要请求数和 token 数一起顶格才算超，于是在客户端只盯着请求数做节流，结果单条请求塞进去一个超长上下文，TPM 先被打穿，RPM 看着还很空闲，日志上就会出现”明明没发几个请求却被限流”的怪现象。

除了这三个通用维度，官方还提到两类附加维度。一是 IPM（每分钟图片数），只对可生成图片的模型计数；二是部分模型另有 TPD（每日 token 数）。也就是说，不同模型头上挂的计数器数量并不一样，做多模型混跑的服务时，不能拿一个模型的限流模型套到另一个模型上去推算。具体每个模型挂了哪几个维度、各维度的数值是多少，都以官方限流页当前版本为准，这类数字变动很快，记在代码注释里迟早会过期。

TPM 计的是输入 token，这个限定条件值得单独强调一句。它意味着把提示词塞得越长，越容易在请求数还很低的时候就撞上限流。反过来，如果你的场景是短提示、长输出，压力更可能落在 RPM 上。两种场景要用的削峰手段完全不同：前者要削的是上下文体积，后者要削的是发起频率。

为什么多签几把密钥没用

这就回到开头那句话。官方文档里写得很直白：限流按项目应用，一个项目内所有密钥的用量合并计入。密钥这一层根本不是配额的边界。

理解这件事的关键，是看清密钥在权限体系里的定位——它没有独立的结算设置，层级和结算状态全部继承自所属项目。既然连结算都不独立，配额自然也不会独立。很多人是从别的平台带着”一把 Key 一份额度”的直觉过来的，在 Gemini 这边这个直觉不成立。

那什么才是真正的隔离边界？是项目。如果你确实需要让两条业务线互不干扰——比如线上服务和内部批跑评估不能互相挤兑——正确的做法是把它们放进不同的项目，而不是在同一个项目里发两把密钥。至于把密钥分开签发的价值，那是在权限与安全层面，不在配额层面：不同用途分开签发，出事时能精确定位和吊销，这个道理和怎么做 API 密钥的安全管理是同一套逻辑，但别指望它顺带解决限流。

再往上一层：层级和限流其实定在结算账号上

官方的层级体系有四档：免费、第 1 层级、第 2 层级、第 3 层级。免费层的门槛是有一个有效项目或处于免费试用；第 1 层级的门槛是设置并关联一个有效的结算账号；第 2、3 层级的门槛则是累计支付金额与自首次成功付款起的天数两个条件同时满足——注意是”同时”，只满足一个不够，光砸钱不等时间不行，光等时间不花钱也不行（金额与天数的具体数值见官方文档，本文不列）。

有一处结构性设计值得特别留意：层级资格的判定，基于该结算账号在 Google Cloud 服务整体上的累计总支出，不限于 Gemini API。也就是说，如果你的团队本来就在用 Google Cloud 的其他产品，这部分支出是算进层级资格里的。反过来，如果你为了做实验单开了一个干净的结算账号，那它的层级只能从零开始积累。

正因为层级挂在结算账号上，就有了几条容易被忽略的连带效应：

• 项目从一个结算账号换到另一个结算账号，层级与限流会随新结算账号变化，可能上去也可能下来；
• 解除项目与结算账号的关联，项目可能退回免费层——这个操作在清理账单时很容易被顺手做掉，然后线上限流突然缩水；
• 层级随用量与支出自动升级，当前限流可以在 AI Studio 中查看；
• 即便条件都满足，官方仍保留否决权：文档里写明满足条件通常足以获批，但升级申请仍可能因审核中的其他因素被拒。最后这条意味着排期时不能把”到期自动升级”当成确定事件写进容量规划。

还有一层限流不按分钟算

除了 RPM / TPM 这类按分钟计的限制，官方文档另外提到一种基于支出的速率限制。它的评估方式和前面那几个维度不一样，是按一个滚动时间窗口来评估的（窗口长度以官方文档当前版本为准），而且是否适用取决于结算记录与账号状态——不是所有账号都会遇到。

触发时返回的是 429 RESOURCE_EXHAUSTED。官方给出的处置有三条：等待一段时间后重试；降低高费用请求的发送速率，具体手段是使用更小的上下文窗口或更短的输出；如果持续触发，就申请提高限流。

这里有一处命名上的落差，值得在写客户端分支之前先讲清楚。429 RESOURCE_EXHAUSTED 这个写法出自官方限流文档，用的是 Google API 通用的全大写状态名；而 Interactions API 的错误码参考里，error 对象的 code 字段列的是小写 snake_case 形式，那张表在 429 这一栏只列了 rate_limit_exceeded 与 quota_exceeded 两个码，官方文档里没有找到基于支出的这层限制在错误码表里对应哪个 code 的说明。所以别把「能靠一个 code 字段把三种限流干净地三路分开」当成既定事实写进代码——能从文档里确定的，是前两个码各自的语义与处置；基于支出的这一层，判断依据要落在账号状态与请求分量上，而不是指望一个字面值。

第二条处置其实透露了这层限制的性质：它约束的不是请求的”条数”，而是请求的”分量”。所以当你已经把并发压得很低、请求数看着一点都不多，却仍然反复被 429 挡回来，该动的不是并发数，而是单条请求的体积——把上下文削薄、把输出上限调低，比继续往下压并发有用。这一层和通用意义上的RPM 与 TPM 限速机制是叠加关系，不是替代关系。

RPD 在太平洋时间午夜重置

这条属于”知道了就少熬一次夜”的信息：RPD 配额在太平洋时间午夜重置——不是本地时间，也不是 UTC。

对国内团队来说，这意味着每日配额的重置时刻会落在一个和自己作息完全错开的时点上，而且太平洋时间还有夏令时切换。所以两件事要注意：一是定时批跑任务的排期，如果按北京时间的整点去卡”新的一天开始”，很可能卡在上一个配额日的尾巴上，一开跑就被挡；二是做用量看板时，日聚合的切分点要跟官方的重置时点对齐，否则你看到的”今日用量”和官方计的”今日用量”根本不是同一段区间，对账时会一直对不上。

另外，官方明确写了实验性模型与预览版模型的限流更严格。拿预览模型做压测，然后按压测结果去规划正式模型的容量，或者反过来，都不成立。

哪些流量不走这套计数

有两处是独立计数的，做容量规划时不能混在一起算：

Batch API 的限流完全独立于非批量调用。 它不占用你日常在线请求的那份配额，另有一套自己的约束，官方列出了四类：并发作业数、输入文件大小、文件存储总量、每个模型的排队 token 数。这四类约束的存在意味着批量任务的瓶颈形态和在线请求完全不同——在线请求卡在”每分钟能发多少”，批量任务更容易卡在”能同时排多少作业、文件能传多大”上。

优先级推理有自己的限流。 官方给出了它与标准限流之间的默认关系（是一个固定倍率，数值见官方文档，本文不列）。要点是：它是另一套计数，不是把标准配额挪过来用。

最后还得把官方那句免责原话摆上：指定的速率限制无法保证，实际容量可能有所变化。所以任何把官方标称限流直接当作 SLA 写进设计文档的做法都有风险，客户端该有的退避与降级逻辑一样都不能省。

撞上了之后，先分清是哪一种 429

限流这件事最后总会以一个 429 收场，但 Gemini 的 429 不止一种，处置方式也完全相反。在 Interactions API 的错误参考里，rate_limit_exceeded 对应的是超出每分钟/每秒级别的请求或 token 限制，官方推荐的处置是等待加指数退避重试；而 quota_exceeded 对应的是超出每日配额，官方推荐的处置是等待配额重置或申请增加配额。

这个区别是硬的：后者退避多少次都没用，因为配额要到重置时点才回来，客户端在那儿反复重试只是在制造无效流量和延迟。判断依据不能只看 HTTP 状态码——两者的状态码都是 429，得读 error 对象里的 code 字段（机器可读的 snake_case 形式），配套的 message 字段是给人看的。这一格展开讲的是Gemini 两种 429 的区别，和站内通用的429 该怎么处理一起看会更完整。

排查顺序建议

把上面这些串起来，遇到限流时的检查顺序大致是这样：

1. 先读 error 对象里的 code 字段，区分 rate_limit_exceeded（分钟级限流，退避重试是有效手段）与 quota_exceeded（每日配额耗尽，只能等重置或申请提额）。至于基于支出的那层限制，官方限流文档记的是触发时返回 429 RESOURCE_EXHAUSTED，但它在错误码表里对应哪个 code，官方文档里没有找到相关说明，不要预设三种情况都能靠这一个字段分开；
2. 确认被打穿的是哪个维度。请求数不高却被限，优先怀疑 TPM（计的是输入 token）；用图片生成类模型时还要看 IPM；
3. 把范围从密钥收回到项目上统计。同项目所有密钥的用量是合并计的，只看单把密钥的调用量会严重低估；
4. 再往上确认结算账号层级有没有变过——项目换过结算账号、或者解除过关联，限流规模会跟着变；
5. 确认这条流量走的是不是独立计数的通道（Batch、优先级推理），别把它们的用量算进在线配额里。

全篇最该带走的一条，还是开头那句：密钥不是配额单位。签一堆密钥既不会让配额变多，还会让用量归因变得更难查。要隔离就隔离到项目，要扩容就沿着结算账号的层级往上走。