Grok 限流字段怎么读、怎么申请提额

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

一句话说完：xAI 官方文档 /developers/rate-limits 里，Grok 的限流是「每个团队、每个模型」两级下发的，维度只有两个——每秒请求数（RPS）和每分钟 token 数（TPM）。RPS 不是独立配的，官方写明它由每分钟请求预算除以 60 推导而来，目的是让你不能把一整分钟的请求额度在一秒内花光。档位（tier）由团队在 API 上的累计消费决定，会自动升、且升上去以后永不回落。所有算进请求的 token 都算进 TPM，包括推理 token 和命中缓存的 token——缓存省的是钱，不是额度。撞了限就返回 429，官方给的处理办法是指数退避；提额路径官方只列了三条：继续消费自动升档、在 Console 提交提额申请、企业容量联系官方销售邮箱。

「限流字段怎么读」这个说法容易让人误解成去响应头里翻一个 x-ratelimit-*。先把这点讲清楚：在这份官方文档里没有找到任何关于限流响应头字段的说明，无论是剩余配额、重置时间还是 Retry-After，官方文档都未说明。所以下面讲的「读」，指的是读 Console 上的额度页、读文档里的档位规则、以及读你自己每个响应里的 usage 对象——这三处才是官方明确写了的信息来源。

两个维度：RPS 和 TPM，而且是逐模型的

官方原文的表述是「每个 xAI API 团队在两个维度上有逐模型的限流：每秒请求数（RPS）和每分钟 token 数（TPM）」。这句话里有三层信息，逐层拆一下。

第一层是限流的主体是团队。官方原句写的就是「每个 xAI API 团队在两个维度上有逐模型的限流」，通篇按团队描述，并没有说明单把 API key 会另外分到一份独立配额。所以默认按「同团队下的多把 key 在同一份团队额度里抢」来做容量规划，是比较稳妥的假设。

但「key 完全做不了隔离」这个说法要打住，因为官方在另一处写了别的东西。Management API（管理接口，用的是单独的 management key、单独的域名，不是推理用的那把 key）的指南里说明：创建 API key 时，请求体里可以传 qps、qpm、tpm 三个字段，给这把 key 单独设上限。官方对 tpm 的说明是——传一个整数字符串即可限制该 key 每分钟产生/消耗的 token 数；触发这个 token 限制之后，新请求会被拒绝，而已经在处理中的请求会继续跑完。key 上还能挂 ACL 来限定可用范围，官方列的类型是 api-key:model 与 api-key:endpoint，写法例如 api-key:model:*、api-key:endpoint:chat（对应聊天与视觉模型）、api-key:endpoint:image（对应图像生成模型）。

把这两处合起来看，正确的心智模型是：key 级的 qps/qpm/tpm 是「封顶」，不是「分配」。它能防止测试环境、某个内部工具或某次跑飞的脚本把团队额度吃光，属于成本很低的护栏；但它不会凭空多给你额度，团队总额还是那一份。真要做严格意义上的额度隔离，得从团队维度想办法。

第二层是逐模型。文档里给的额度表是一行一个模型，文本模型、多智能体模型、图像模型、视频模型各自一套数。这意味着你把一部分请求从一个模型切到另一个模型，是真的能腾出额度的；反过来，全公司都压在同一个模型上，撞限的速度会比你按总用量估的快得多。

第三层最容易被忽略：RPS 是推导出来的，不是独立给的。官方写得很直白——你的每秒限制来自每分钟请求预算除以 60，「你不能把一整分钟的请求在一秒内花光，这是为了保护 API 免受突发流量冲击」。这个设计有点反直觉：很多人做压测时习惯先攒一批任务，然后一口气并发打出去，结果总量明明远没到分钟级预算，却在第一秒就被拒了一片。Grok 这里没有「攒额度」这回事，节流必须做在秒级。 客户端侧最省事的做法是加一个令牌桶，桶的补充速率按秒算，而不是每分钟放一次闸。

具体数字去哪读：Console 的额度页，别硬编码文档表格

官方文档里确实列了一张各档位、各模型的 RPS 与 TPM 表，但同一页上反复出现的一句提示是：你可以在 xAI Console 的 Rate Limits 页面查看你的团队当前所处档位和逐模型的个性化限额。

这里给一条实践建议：不要把文档表格里的数抄进代码当常量。 理由有两个。一是这类数值本来就会随平台调整，抄进去就等于给自己埋了一个静默过期的配置；二是官方明确说 Console 上的是「你的团队的个性化限额」，这意味着文档表是通用参考，你实际拿到的未必与之逐位对应（比如提过额、或者签了企业协议）。正确姿势是：把限流参数做成运行时可改的配置项，值从 Console 上看到的实际额度填，改的时候不需要重新发版。

跨厂商的通用做法可以看这篇 API 限速 RPM 与 TPM 怎么算，那篇讲的是各家共有的机制，本文讲的是 Grok 的具体形态，两篇是「通用机制」与「具体落地」的关系。

哪些 token 会算进 TPM：四类，一个都跑不掉

这一节是本文最值钱的部分，因为它直接决定你的额度估算准不准。官方文档在「What counts toward TPM」小节里明确列了四类，说的是「一次请求消耗的所有 token 都计入该模型的 TPM 限制」：

• Prompt token，并且明确包含文本、图像和音频三种形态
• Completion token
• Reasoning token（推理模型上产生的）
• Cached prompt token——命中缓存的那部分提示 token 仍然计入 TPM，尽管它们按更低的费率计费

第三条和第四条是两个高频误判点。

先说推理 token。如果你用的是推理型模型，模型在给出可见回答之前产生的思考 token 也吃 TPM 额度。也就是说，同样一段用户输入、同样长度的可见输出，把推理强度调高之后，你的 TPM 消耗会明显上去。做容量规划时如果只按「输入字数 + 输出字数」估，估出来的数会偏小。

再说缓存。这条官方写得非常克制但非常关键——缓存命中降低的是计费，不降低限流占用。很多团队上了提示缓存之后看账单确实降了，就理所当然地认为并发能力也跟着上去了，然后在高峰期撞了一片 429，回头查了半天以为是缓存失效。不是失效，是缓存从一开始就不是拿来提额度的。缓存那套机制影响的是计费口径，和额度是两条线。

那怎么在自己这边核对 token 消耗？官方文档在缓存的用量说明里给了响应体 usage 对象的字段结构：Chat Completions 这边是 prompt_tokens、completion_tokens、total_tokens，细分放在 prompt_tokens_details（含 text_tokens、audio_tokens、image_tokens、cached_tokens）和 completion_tokens_details（含 reasoning_tokens 等）里；Responses API 那边字段名换成 input_tokens、output_tokens、total_tokens，细分是 input_tokens_details.cached_tokens 与 output_tokens_details.reasoning_tokens。把 total_tokens 按模型分组累加到一分钟的滑动窗口里，你就有了一份自己算的 TPM 消耗曲线——这是官方文档支持你做的、最接近实时额度视图的东西。

另外，每个推理响应的 usage 里还有一个 cost_in_usd_ticks 字段，官方说明它返回的是这次请求实际被计费的金额，是提示缓存等各项减免全部生效之后的最终结果，也包含服务端工具调用的开销。金额以 tick 这个高精度单位表示，把 ticks 换算成金额的公式写在官方 Cost Tracking 文档里（不在定价页，定价页给的是当前单价），xAI SDK 另外提供了一个直接返回已换算金额的便捷属性，不想自己换算就用它。它对限流本身没用，但把它和 token 曲线放在同一张监控图上，能让你在「撞限」和「花超」之间快速判断当下是哪一类问题。

撞上 429 之后，官方给的处理路径

超过任一维度的限制，API 返回 429 Too Many Requests。这一点在两处文档里都有：限流页写「超出任何一项限制都会返回 429 错误」，调试页的状态码表里也单列了一行，把原因写成「请求发送过于频繁、已达到限流」，把解法写成「降低请求速率，或在 xAI Console 上提高你的限额」。

官方在限流页给出的示例代码是指数退避：捕获 SDK 抛出的限流异常，每次重试前等待的时间随尝试次数指数增长，达到重试上限后把异常抛出去。示例里的具体重试次数与等待基数属于示例值，按你自己的业务容忍度定就行，不要照抄当成推荐配置。真正需要注意的是前面提过的那一点：因为官方文档未说明限流响应头里有重置时间或 Retry-After，你的退避时钟只能自己估，没有服务端告诉你「还有多久放行」。这就让退避的抖动（jitter）变得比平时更重要——多个客户端如果用同一套确定性的退避序列，会在同一时刻集体重试，把第二波打回去。

还有一点值得写进代码规范：429 和 5xx 要分开计数。前者是你自己打太快，后者是服务端问题，混在一起统计会让你误判到底该提额还是该报障。官方文档另给了状态页地址用于查服务中断，遇到大面积失败先分清是哪一类。通用的重试骨架可以看 429 报错的通用处理办法。

提额：官方只写了三条路

限流页的最后一节标题就是「Increasing your limits」，逐条对应：

第一条是继续消费，自动升档。 官方说明档位由团队在 xAI API 上的累计消费决定，达到门槛后自动解锁，「无需你做任何操作」。文档列出的档位是 Tier 0 到 Tier 4，再往上是 Enterprise（按需申请）；其中 Tier 0 是默认档，各档对应的消费门槛见官方文档页，本文不抄具体金额。三条规则值得单独记：累计消费从官方规定的起算日开始统计（当前文档写的是 2026 年 1 月 1 日起，以官方文档为准）；计入的是通过预付点数购买或已成功履约的发票所产生的实际收入；一旦达到某一档就永久保留，档位不会降级。最后这条对用量季节性波动大的团队是好消息——旺季冲上去的档，淡季不会掉回来。

第二条是在 Console 提交提额申请。 官方给的适用场景是「你需要更高的限额但不想通过额外消费来换」，或者「你需要的额度超出了最高档」。入口就是 Console 的 Rate Limits 页面。

第三条是联系官方销售邮箱，用于企业级容量。这里有一个容易漏的边界：官方在档位表下面单独挂了一条 NOTE，写明限流档位体系适用于文本模型和 embedding 模型；语音（Voice）与 Imagine 系列 API 的限额提升，需要通过邮件联系官方销售。

这句 NOTE 很容易被过度外推，所以把它的准确含义收一下：它说的是「档位体系之外的额外提额，走销售渠道」，不是「图像视频完全不受档位影响」。同一页的逐模型额度表里，Imagine 的图像模型与视频模型都单列了行，RPS 一列在 Tier 0 到 Tier 4 上是逐档给出的数值，只有 TPM 那一列在这几行是空的——也就是说这几个模型只按请求速率约束，官方没有给它们标 TPM 值。做多模态产品的容量规划时，图像与视频的可用额度仍然以官方额度表和 Console 上你团队的实际数字为准；只有当你需要的额度超出这套档位体系时，才是那条 NOTE 说的、要发邮件找销售的场景。

顺带说清楚一件事：官方文档里提额的路径就是上面这三条，全部在 xAI Console 和官方邮箱之内完成。任何第三方代办、代充值、共享账号一类的渠道都不在官方说明范围内，也不应该出现在企业采购流程里。境外服务的可用区域与采购方式，以官方文档和官方商务渠道的说明为准。

在提额之前，先看看请求形态能不能改

很多「额度不够」其实是请求形态没选对。官方文档里有两个机制直接和限流相关，值得在提交提额申请之前先评估：

Batch API 的请求不计入限流。 官方在 Batch API 页面的对比表里，把实时接口写成「按分钟级限制计算」，把 Batch 写成「请求不计入速率限制」，同时按低于标准价的价格计费，代价是异步——你提交到队列、稍后回来取结果，官方明确说明完成时间是尽力而为、不做保证。评测跑分、存量数据清洗、离线摘要、内容审核积压这类没人在等的活儿，全部搬过去，实时额度立刻松一大截。用法见 Grok Batch API 怎么用。

延迟补全（Deferred）不是绕开限流的办法。 这一点必须点破，因为它长得很像批处理。官方文档在延迟补全页明确写着：「你的延迟补全限流与你的 chat completions 限流相同」。它解决的是长任务不占着连接的问题，不解决额度问题。把实时请求改成 deferred 之后 429 照样会来。

优先处理（Priority Processing）改的是调度顺序，不是配额。 官方对它的定位是提高请求的调度优先级、通常带来更低的首 token 时间，按更高的 token 费率计费，并且响应里会带一个 service_tier 字段告诉你这次到底有没有按优先级处理。但这里必须说清楚一件事：优先处理是否影响限流占用，官方文档未作说明——优先处理那一节从头到尾讲的是调度顺序、service_tier 取值、计费费率、以及缓存减免与优先费率的先后作用关系，通篇没有出现限流、配额或 429 的字样。对照着看更明显：Batch 明写「请求不计入速率限制」，Deferred 明写「限流与 chat completions 相同」，唯独优先处理没有对应的表述。所以不要把它当成额度手段写进容量方案里，真要腾额度，看的还是上面 Batch 那条。详见 Grok 优先处理什么时候值得开。

最后：三个最容易栽的坑

第一，把文档里的额度表当合同。文档表是各档位的参考值，你的实际额度以 Console 上显示的为准，而且平台会调整。代码里只放可配置项，别放常量。

第二，按「用户可见字数」估 TPM。推理 token 和缓存 token 都算数，图像与音频输入的 token 也算数。估算基数应该来自 usage.total_tokens 的真实累加，不是你对提示词长度的直觉。

第三，先申请提额、后改架构。顺序反了。先把不需要实时性的流量搬去 Batch（那部分请求根本不占额度），再看剩下的实时流量是不是还撞限；如果还撞，那时候提交的提额申请也更容易说清楚你到底需要多少。