OpenRouter 余额和用量怎么查：控制台、API 与账单口径的区别

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

先把结论说完：OpenRouter 的「余额」和「用量」不是同一套数据，官方给了几个不同的入口，各自回答不同的问题。单次调用花了多少，看响应体里自动带回来的 usage 对象；某一把 key 还剩多少额度、这个月累计用了多少，调 GET /api/v1/key；账户整体买了多少、用了多少，走 credits 接口，而它要求的是 management key，普通推理 key 会被拒；想知道钱花在哪个模型、哪把 key 上，用 Analytics 查询接口做聚合；要给人看、要导表，用网页端的 Activity 页。这四层的统计边界、时区口径、是否包含 BYOK 估算值都不一样，数字对不上是设计使然，不是哪一层坏了。

最省事的一层：账单跟着每次响应一起回来

OpenRouter 有一项叫 Usage Accounting 的能力，官方文档的定义是：不需要额外发一次 API 调用，就能拿到本次请求的 token 数、成本和缓存状态。这一层最容易被忽略，因为它不需要你做任何事——文档明确写着不需要额外参数，非流式请求在完整响应里返回，流式请求则放在最后一条 SSE 消息里。

一个容易踩的历史包袱：usage: { include: true } 和 stream_options: { include_usage: true } 这两个参数已经废弃且不再有任何效果，官方的说法是完整的用量信息现在总是自动包含在每次响应里。如果你的代码里还留着这两行，它们既不会报错也不会起作用，删掉就行。

返回的 usage 对象里，值得记住的字段是这几个：

• prompt_tokens / completion_tokens / total_tokens：token 计数，官方说明是按该模型的原生分词器算出来的，额度消耗与模型定价也都基于这套原生 token 数
• completion_tokens_details.reasoning_tokens：推理 token 数
• prompt_tokens_details.cached_tokens：从缓存读出的 token 数
• prompt_tokens_details.cache_write_tokens：写入缓存的 token 数，官方注明只有具备显式缓存且有缓存写入定价的模型才返回
• cost：本次记到你账上的总额
• cost_details.upstream_inference_cost：上游供应商实际收取的部分

最后两个字段并列出现是有意义的：它把「平台记到你头上的」和「上游模型侧的」分成了两个数，你自己做成本归因时不用猜。缓存这块还有一个 cache_discount 字段，官方说明它表示这次响应在缓存上省了多少；并且明确提醒，有些供应商（文档里举的例子是 Anthropic）在缓存写入时会是负的折扣，缓存读取时才是正的折扣。所以看到负值不要以为是 bug，那是写入成本。缓存这套账怎么算，可以对照提示缓存的计费机制一起看。

单把 key 的余额与用量：GET /api/v1/key

要查某一把 key 的状态，官方给的端点是 https://openrouter.ai/api/v1/key，用这把 key 自己的 Authorization 头去 GET 就行。返回结构里的字段分成三组，值得逐组理解：

额度上限组：limit 是这把 key 的额度上限，无限制时为 null；limit_reset 是上限的重置类型，永不重置时为 null；limit_remaining 是这把 key 剩余的额度。官方在 Limits 一节里把这三个字段单独点了名，说它们描述的是「单 key 消费上限」这一层——注意它跟账户余额是两回事。

累计用量组：usage 是全时段累计消耗，然后是 usage_daily、usage_weekly、usage_monthly 三个滚动窗口。这三个字段的时区口径在文档注释里写得很死：日按当前 UTC 日算，周按当前 UTC 周且从周一开始，月按当前 UTC 月算。这一条是对账时最常见的落差来源——你按本地日历自然日去核对，跟接口返回的 UTC 日边界天然错开几个小时。

BYOK 与账户属性组：byok_usage 及其日/周/月三个变体，对应外部 BYOK 用量；include_byok_in_limit 表示是否把外部 BYOK 用量算进这把 key 的额度上限；is_free_tier 表示这个用户此前是否付费购买过额度。另外响应里还有一个 rate_limit 对象，官方注释直接标了 deprecated 并说可以放心忽略，别再拿它写逻辑。

如果你在做 key 的批量管理，官方另有 key 管理接口；但要注意它与本节这个「查当前这把 key」的接口不是一回事，具体返回哪些字段以官方接口文档为准。

为什么额度不足要查两个地方

官方把「额度限制」明确拆成了两个来源：一是账户余额，二是单 key 上可选的消费上限。这两个来源任何一个见底，请求都会失败，所以排查顺序不能只看一个。官方给出的处理路径是：先充值把账户余额抬到零以上，再检查这把 key 的 limit_remaining 是不是耗尽了——耗尽就调高这把 key 的上限，或者等 limit_reset 到点，最后再主动调 GET /api/v1/key 做提前监控，别等请求开始报错才发现。

这里有条反直觉但很实用的官方说明：账户额度余额为负时，请求可能失败，免费模型也在波及范围内，把余额补到零以上才能重新使用这些模型。很多人以为免费模型跟余额无关，实际不是。额度节奏怎么安排，可以延伸看 OpenRouter 额度管理。

还有一个跟性能相关的机制值得知道：官方在延迟说明里写了，当账户额度余额偏低、或者某把 key 接近它配置的额度上限时，OpenRouter 会做额外的数据库校验，并且会更激进地让缓存过期，以保证计费准确——代价是在补充额度之前，延迟会升高。也就是说，余额贴着底线跑不只是有断供风险，还会顺带影响链路表现。

账户级余额与聚合分析：要换一把 management key

查单把 key 用它自己就行，但查账户整体余额、跑聚合分析，都要求 management key。这是最容易卡住的一步。

credits 接口的官方描述是「获取当前认证用户已购买和已使用的额度总量」，并明确标注需要 management key。Analytics 那边说得更直白：分析查询需要从设置里的 Management Keys 页面创建的 management key，普通推理 key 会拿到 403。

management key 本身有两条硬性质：其一，它不能用于调用补全类端点，官方原文就是说它只用于管理操作；其二，反过来说，整个分析流程是只读的、不产生推理调用。但官方也提醒了——它返回的是你组织完整的支出明细，要像对待任何其他凭据一样对待它。这条别当客套话看，management key 泄漏等于把账目全交出去，处理方式可参考 API key 的安全管理。

想知道钱花在哪：Analytics 查询接口的几条硬规矩

聚合分析走两个端点：/api/v1/analytics/meta 用来发现当前支持的指标、维度、过滤操作符和时间粒度；/api/v1/analytics/query 用 POST 发查询体。官方特意建议先查 meta 再写查询，理由是指标和维度会演进，别照着某一版文档快照硬编码。

查询体的结构大致是 metrics、dimensions、filters、order_by、time_range、granularity、limit 这几块。指标侧，支出类指标是 total_usage 以及一组 usage_* 分项，token 类指标返回的是原生 token 数，cache_hit_rate 是一个 0 到 1 的比率。那组 usage_* 分项官方给了逐条含义：usage_upstream 是原始推理成本，usage_cache 是缓存带来的节省（缓存写入时则是成本），usage_data 是折扣项、通常为负，usage_web 和 usage_file 分别是网页搜索与文件解析的附加费用。把这几项拉出来看，就能回答「这笔钱到底买了什么」，而不是只盯着一个总数。

几条会让人栽跟头的行为约定，官方都写明了：

• 维度最多两个，传第三个会返回 400，报错信息形如 dimensions: Too big: expected array to have <=2 items。文档还注明这是 2026 年 6 月观察到的行为，这类细节可能漂移。需要第三个角度时，官方建议拆成多次查询，或者改用时间轴 granularity。
• time_range 必须显式传。不传的话接口会退回到一个默认的近期窗口，可能根本没覆盖你想问的那个月。
• 计数类指标可能返回字符串。官方原话是参考文档里的示例把它们展示成数字，但实际可能是字符串，解析时两种都要接。
• metadata.truncated 要看。它为 true 说明结果撞到了行数上限，你的合计是残缺的，应当调大 limit 或收窄查询再下结论。
• 时间轴字段名有两种前缀。按粒度聚合时，行里的时间键可能叫 date__<granularity>，也可能叫 created_at__<granularity>，取决于查询落到哪个数据源，代码要两种都接受。
• 没用到的分项返回 null 而不是 0，直接做算术会炸。
• 过滤值必须匹配内部存储值。官方给的实践是：过滤就按 model 的 slug 过滤（这个你确切知道），分组则按 api_key_id 分组，而不是拿解析后的 key 名字去过滤。响应里 api_key_id、app、workspace 会解析成人类可读的名字，方便直接看。
• user 维度是个例外：按 user 分组时一行会返回两个字段，user 是账户显示名（没设名字时为 null），user_email 是邮箱（没有时为 null），原始 user ID 永远不会返回，所以要跟自己的记录对齐只能用邮箱。

另外还有一个更轻的活动接口 GetUserActivity，官方描述是按端点分组返回用户活动，覆盖最近 30 个已结束的 UTC 日，同样要 management key。它支持按单个 UTC 日期（YYYY-MM-DD）过滤、按 API key 的 SHA-256 哈希过滤、组织账户下按成员 user ID 过滤，以及按 workspace 拆分或过滤。有一条历史数据的坑写在文档里：在 workspace 归属机制存在之前记录的活动，会永久归到账户默认 workspace，无法回填。老账户按 workspace 拆历史数据时会看到一大坨堆在默认 workspace 上，那不是统计错误。

网页端 Activity 页：给人看和给财务看的那一层

Activity 页展示三个指标：Spend（总支出）、Tokens（prompt 与 completion 之和）、Requests（请求数，包含在网页 chatroom 里发起的请求）。最后这个括号很重要——你在网页聊天框里试模型也计入请求数，程序侧的计数自然对不上。

时间维度可选 1 小时、1 天、1 月、1 年，分组维度可选 Model、API Key 或 Creator（组织成员）。官方还说明了每个时间跨度的子分组粒度：分别按分钟、小时、天、月细分。导出走右上角的选项下拉，选 Export to CSV 或 PDF，导出的是三个指标的汇总；想要明细，先点开某一个指标卡片下钻，再从里面导出。

这一层有个必须知道的口径差异：Spend 等于 OpenRouter 额度消耗加上 BYOK 的估算支出，而官方明确说 BYOK 那部分是按该供应商的市场价估算的，不反映你从供应商那里拿到的任何优惠。换句话说，Activity 页的 Spend 里混了一个估算量，它天然不等于你在上游供应商那边收到的真实账单。做财务对账时，BYOK 部分要以供应商侧账单为准。

还有一条注释藏在导出文档里：推理 token 在计费上被计入 completion token，页面上单列推理 token 只是告诉你这部分 completion token 是花在「回答前思考」上的。所以别把推理 token 再加一遍。

组织账户还有一层要注意：在组织上下文里看活动流，看到的是全体成员的活动，展示的是模型、成本、请求元数据这类信息。官方把这条标成了已知限制，并明确写了这些用量元数据对所有组织成员可见。团队里如果有人不该看到别人的调用量，这一点要提前打招呼。

想让这几层数据更好用，先把标识打上

有两个可选参数会直接影响你之后能查出什么。一是请求里的 user 参数，传一个稳定的终端用户标识，官方说明它既能改善缓存表现（按用户的粘性路由），也能在活动流和导出里启用用户级分析；官方同时说明 OpenRouter 会把它折进发往上游的哈希身份里，不会原样转发。二是 session_id（或 x-session-id 头），官方用它把跨轮次、跨重试、跨模态的请求归到一次会话里，在 Logs 页的 Sessions 视图中一起看。

要事后审计单条请求，用响应里的 id（也有 X-Generation-Id 响应头）去调 /api/v1/generation?id=<GENERATION_ID>，官方说这适合请求结束后异步拉取用量、或做历史审计。这里有个限制别忽略：通过 generation ID 取用量时，upstream_inference_cost 只对 BYOK 请求可用，其他请求这个字段会是 0 或 null。要拿这个字段做归因，就得走响应体里的那份 usage，不能等事后补查。

最后：三层数字对不上，先按这个顺序查

真出现「控制台跟我自己的记账对不上」，按这个次序排一遍通常就能定位：先看时区，接口的日/周/月是 UTC 口径且周从周一起算；再看统计范围，Activity 的请求数含网页 chatroom，组织上下文还含全体成员；再看 BYOK，Spend 里那部分是估算值不是账单；再看推理 token 是否被你重复计了一遍；最后看 Analytics 查询的 metadata.truncated 是不是 true、time_range 有没有显式传。

真正稳妥的做法是不依赖单一口径：程序侧用每次响应自带的 usage 落自己的流水，运维侧用 GET /api/v1/key 盯 limit_remaining 做闸门，复盘时用 Analytics 按模型和 key 归因。三条线互为对照，比死盯一个页面靠谱得多。这套「进程内记账 + 平台侧闸门 + 定期对账」的分层思路不是 OpenRouter 独有的，跨厂商的通用做法可以看 API 成本怎么监控。

具体到某个字段的最新语义和端点的当前行为，以官方文档为准——上面几处官方自己都注明了「行为细节可能漂移」。