Kimi 余额查询与用量监控怎么做：接口字段、项目预算与账单对账
数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。
Kimi 的用量监控其实是三层东西，很多人只用了第一层。第一层是余额查询接口 GET /v1/users/me/balance，它返回可用余额、代金券余额、现金余额三个字段，是账户级的快照；第二层是控制台里的项目预算与消费提醒，它才是真正能”踩刹车”的开关，因为余额接口只会告诉你还剩多少，不会替你拒绝请求；第三层是每次响应里的 usage 字段和 token 预估接口，用来把消费落到单条请求上。搞混层次的典型后果是：写了个脚本轮询余额、发现掉得很快时人已经不在电脑前，而项目预算压根没设，编程工具的自动重试已经把额度烧完了。下面按”看余额 → 设预算 → 读单次用量 → 对账单”的顺序过一遍官方文档写明的机制。
余额接口返回的三个字段，含义并不一样
官方 API 参考页 查询余额 给出的端点是 GET /v1/users/me/balance，鉴权用请求头 Authorization: Bearer <token>，令牌就是你的 MOONSHOT_API_KEY。文档明确说明这是一个服务端密钥，要在 API 密钥页面生成——这句话的言外之意是别把这个查询塞进前端页面。
返回体的结构是 code / data / scode / status 四个顶层字段，code 为 0 表示成功，scode 是状态码，status 是布尔的请求状态。真正有信息量的是 data 里的三个数值字段，单位都是人民币元：
available_balance：可用余额，文档说明它包含现金余额和代金券余额。这是唯一决定你能不能继续调用的字段。voucher_balance：代金券余额，文档明确写了”不可为负”。cash_balance：现金余额，文档明确写了”可为负值表示欠费”。
这里有个容易读漏的条件分支：官方对 cash_balance 的说明里补了一句，当它为负值时，available_balance 等于 voucher_balance 的值。也就是说欠费状态下的可用余额不是简单相加的结果，而是被代金券余额顶住了。你要是自己写监控面板，把三个字段直接做加减去校验一致性，遇到欠费账户就会算出对不上的数——不是接口有问题，是这条规则你没照着实现。
可用余额归零之后，报的是哪个错
余额文档和错误码文档在这一点上口径一致：当 available_balance 小于等于 0 时，用户无法调用推理 API，调用会返回 exceeded_current_quota_error。
麻烦在于这个错误挂在 HTTP 429 下面。Kimi 的错误码页面把 429 归类为”速率限制 / 额度不足”，同一个状态码底下并列着好几种 error.type：
exceeded_current_quota_error：官方给的原因是账户欠费或已停用、账户 token 额度不足；问题排查页写得更全，说的是余额不足、欠费或代金券失效，并建议先通过查询余额接口确认available_balance再充值。rate_limit_reached_error：触发组织级的并发、RPM、TPM 或 TPD 限制，处理方式是降低调用频率或提升用户等级。engine_overloaded_error：服务节点负载较高。这一条官方专门强调过，该错误由服务端容量导致，充值或提升 Tier 不能直接消除，正确做法是按响应中的Retry-After提示等待、降低并发并使用指数退避重试。
所以看到 429 别条件反射去充值。正确顺序是先读 error.type 再决定动作，这个分流逻辑跟各家 API 的 429 通用处理套路是一致的，只是 Kimi 把额度不足和限流塞进了同一个状态码。还有一条对账时很关键的官方说明：因 429 错误中断的请求不会扣费。
余额告警是事后通知，项目预算才是刹车
余额接口能查，但它不会替你停。官方在账号与财务页面讲成本控制时，给的第一条建议是设置日消费上限：前往开放平台项目设置配置”项目日消费预算”，一旦达到预算上限，系统将自动拒绝该项目下所有 API 请求。文档同时标注了这个限制的生效存在计费延迟，也就是说它不是毫秒级的硬闸，具体的延迟以官方文档当前版本为准。
组织管理最佳实践页把这套配置讲得更细，几条结构性规则值得抄进你的运维文档：
- 平台支持分项目设置月消费预算和日消费预算，入口在【项目管理】-【项目设置】-【项目预算/限速设置】，达到预算后该项目后续的 API 请求会被拒绝。
- 消费提醒是另一套开关，在【项目管理】-【项目设置】-【项目消费提醒】里设置每月/日的消费提醒，平台按自然月/自然日累计，达到限额后触发短信告警，短信发给组织管理员。
- 组织下的所有项目共享组织内的限速，也共享组织的账户余额。这一条决定了余额接口的粒度：它是账户级的，你没法用它区分哪个项目在烧钱。
- 项目可以单独配置 TPM 限速值，项目 API Key 的请求达到该 TPM 后会被拒绝；但官方注明项目 TPM 不得超过组织的 TPM，设置了更大的数值也会按组织 TPM 限速。
账户层面还有一个提醒功能：账号与财务页建议开启账户余额提醒，当账户余额低于预设金额时，系统会通过短信通知你及时充值，官方标注了这个阈值有默认值，具体以官方文档当前版本为准。它跟项目预算的区别是：提醒只发短信，预算才会拒绝请求。真正怕半夜跑飞的场景，两个都得开。
把这套东西跟通用的 API 成本监控做法对照着看会更清楚——预警负责让人知道，硬限额负责在没人看的时候止损。
单次请求的消费，从 usage 字段读
账户级余额只能看趋势，要定位到”哪一次调用贵了”，得看对话补全响应里的 usage。官方响应示例中的 usage 包含 prompt_tokens、completion_tokens、total_tokens 和 cached_tokens 四个字段。最后那个是跟缓存相关的计数，Kimi 的问题排查页说明上下文缓存不需要手动配置，API 会对重复的初始上下文自动尝试缓存，无需创建 cache ID、设置 TTL 或加额外请求参数，并提示保持 system prompt、工具定义和长文档等初始前缀稳定有助于命中，修改前缀内容可能降低命中率。缓存命中会直接影响这条请求的计费构成，所以这个字段值得单独记进日志。
流式输出的用量要单独处理。官方文档的口径是：通过 stream_options: {"include_usage": true}，可以在最后一个 chunk（data: [DONE] 之前）额外获取 usage 字段，显示本次请求的 Token 消耗。流式指南把这个数据块的形态也讲清楚了——最终统计数据块不包含模型输出，因此 choices 为空，本次请求的总用量位于顶层 usage 字段；官方并且特意提醒，解析流式响应时不要假设每个 chunk 都存在 choices[0]，要从最终统计 chunk 的 chunk.usage 读取总用量。很多人写解析循环时直接取 chunk.choices[0].delta，跑到最后一个块上就抛异常，根子就在这里。
流式指南写的是「计算 Tokens 有两种方式」，第二种最容易被漏掉，但恰恰是给意外情况兜底的那条。官方的原话是：流式输出可能因网络连接中断、客户端程序错误等不可控因素被打断，此时最后一个数据块尚未到达，也就无从得知本次请求消耗的 Tokens。给出的对策是保存已收到的每个数据块的内容，并在请求结束后（无论是否成功结束）调用 Tokens 计算接口统计实际消耗量，文档里的 Python 与 Node.js 示例就是这么写的：把每个 delta 的内容一路追加进一个数组，循环结束后拼成完整文本，再送去算一次。注意「无论是否成功结束」这个限定——它的意思是这条补算路径不是异常分支的补丁，而是常规收尾动作。所以自建监控里应该这样设计：优先读最终统计块的 usage，读不到就走补算，而不是记一条「本次用量未知」了事。
上面说的 Tokens 计算接口就是 POST /v1/tokenizers/estimate-token-count，官方描述是估算给定消息和模型所需的 Token 数量，输入结构与聊天补全几乎相同（请求体同样是 model 加 messages），响应返回 data.total_tokens。它因此有两个用场：批量任务上线前拿样本跑一遍，先摸清这批活儿的量级；流式请求断在半路时，拿已收到的内容补算实际消耗。两个用场共用一个端点，接进日志管线时写一个函数就够。
账单跟客户端记录对不上，按这个顺序查
问题排查页专门有一问是”为什么 Agent 没有显示结果，账户却产生了费用”。官方给的解释是：客户端没有显示结果不代表 API 请求失败，当编程工具等待时间过短、代理连接断开或本地超时时，客户端可能停止展示，但服务端请求仍可能已完成并产生实际调用记录。
官方给的排查顺序是这五步，照着做：
- 看请求的 HTTP 状态码与
request_id； - 看 API 响应中的
usage字段； - 看客户端是否自动重试、启动子 Agent 或循环调用工具；
- 看控制台的用量看板与计费明细；
- 看客户端日志中的超时和连接错误。
第三步值得单独拎出来说，因为官方在好几个地方重复提醒了同一件事。429 那一问里的说法是，OpenAI SDK 等客户端默认会自动重试，一次操作可能放大为多次请求并占用限速额度，排查时要看实际请求次数和客户端日志。账号与财务页对代码生成场景的说法是，由于模型的随机性和复杂性可能需要多次尝试，编程工具会自动进行多轮重试和调用，这可能导致 token 用量快速增长，因此建议先用较短上下文明确提示词测试再逐步加入完整业务上下文，并在编程软件运行期间保持监控，避免无限循环或过度重试。
要反馈异常扣费，官方要求先在开放平台控制台查看用量看板与计费明细，按时间、项目、模型和 request_id，与客户端日志、API 返回的 usage 逐条对照。需要后台协助查询时，准备的材料清单是：组织 ID、项目名称、发生时间（含时区）、request_id、模型名、客户端与版本、脱敏日志、相关账单或导出记录，通过 API 问题反馈表单提交。先把这堆东西备齐再提工单，能少来回好几趟。另外平台还提供组织概览和项目概览页面，做组织与项目维度的消费分析。
几条会让监控数据”看起来不对”的账务规则
这些规则单独看都不起眼，凑在一起就足以让你的对账脚本得出错误结论：
余额和 Key 是分产品隔离的。 问题排查页写明 Kimi API 开放平台、Kimi Code 和 Kimi 会员是相互独立的产品，付费方式、余额/权益和 API Key 均不通用；开放平台是按量付费模式、无订阅制；Kimi 会员的权益不会转换为开放平台余额，开放平台充值余额也不能用于购买 Kimi 会员或 Kimi Code Plan。把其他产品的 Key 填到开放平台端点，会出现 401 或 404 报错。
国内站和国际站也是隔离的。 余额接口文档和错误码页都单独强调了这条：platform.kimi.com（国内站）与 platform.kimi.ai（国际站）申请的 API Key 完全独立，账户、余额和 Key 相互隔离，混用会返回 401，要确认调用端点与 Key 所属平台一致。用哪个站的 Key 就查哪个站的余额，这也是 Key 管理层面该做的隔离，思路可参考API Key 安全管理。
代金券不计入累计充值总额。 充值与限速页在特别说明里明确写了这一条，而账户的速率限制是基于账户的累计充值金额来划分的。所以代金券余额虽然能用来调用，却不会帮你把限速档位往上抬。同页还说明，当系统检测到账户存在异常行为时会触发风控限速策略，该限制一旦触发即无法解除；当集群负载达到容量上限时，平台可能采取临时的限流措施对各类限速进行调整。这些机制的通用背景可以看RPM 与 TPM 限速怎么读。
代金券未必所有模型都能用。 账号与财务页写明，国内注册并完成认证的用户获赠的代金券不可用于体验 Kimi K3，需要充值后解锁；问题排查页在 401/404 排查清单里也列了”账户是否有可用余额，代金券是否支持目标模型”。所以余额接口显示还有可用余额、调用却仍然报额度错误，是有官方口径可以解释的情形之一。
余额的处置规则写在充值协议里。 协议明确账户余额的使用不设有效期，不能转移、转赠；账户不支持对未消耗金额进行任意退款。发票方面，平台支持按消耗金额或充值金额开具，线上在发票管理页发起开票申请；个人认证可开个人抬头或公司抬头，企业认证仅能开具企业认证主体抬头的发票。账号与财务页把票面信息也写明了：发票项目名称为「技术服务费」，税收分类编码简称为「生产生活服务」，票面显示为 *生产生活服务*技术服务费；税率等具体开票事宜以发票相关页面公布的信息为准。财务同事问你「这笔买的是什么」时，直接给这两个词就行。
最后：先设预算，再写监控脚本
顺序很重要。轮询余额接口写个告警只要十几行代码，但它救不了一个在你睡觉时循环重试的 Agent；项目日/月消费预算是官方明确会拒绝请求的机制，它才是止损那一环，而且注意它有计费延迟，不要指望卡在一个精确的点上停住。
落地时按这个清单来：给每条业务线单独建项目、用项目 API Key 隔开消费，先配项目日预算和月预算，再配消费提醒短信，然后才是把余额接口接进你的巡检；服务端日志里务必记下 request_id 和 usage，流式记得开 include_usage，并按官方那条兜底路径在请求收尾时用 Tokens 计算接口补算一次；上线新的批量任务前也用同一个接口跑一遍样本。真出了对不上的账，官方那份材料清单就是你的举证依据——而 request_id 只有你自己当时记下来了才有。