Kimi 计算 Token 接口怎么用：调用前把 token 数和成本估出来
数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。
Kimi 开放平台有一个独立的计算 Token 接口，输入结构和对话补全几乎一样，返回只有一个 data.total_tokens。要害在于：它算的是「这组 messages 送进模型要占多少输入 token」，不是这次调用的总账单——输出多少 token 得跑完才知道。官方在问题排查页把它写成了确定 max_completion_tokens 的标准做法，而不是拿来数字数的小工具。所以想让月成本估算靠谱，要做三件事：输入侧用这个接口算准，输出侧用你自己压得住的上限兜住，再把预估接口覆盖不到的部分（输出、缓存命中、联网搜索结果回灌）单独拉一张清单出来。
接口本身：一个 POST，一个 total_tokens
端点是 POST /v1/tokenizers/estimate-token-count，挂在开放平台的服务地址下。鉴权方式和其他接口一致，走 Authorization: Bearer，令牌用 MOONSHOT_API_KEY；官方在参数说明里专门标注了这是一个服务端密钥，需要在 API 密钥页面生成——这句话的言外之意是别把它塞进前端页面里去做实时字数提示。
请求体两个必填字段：
model：枚举类型，必填，官方标注了默认值。这一页列出的可用选项里既有 kimi-k 系列的几个模型，也有 moonshot-v1 的 8k / 32k / 128k / auto 以及三个 vision-preview 版本。这里要提醒一句：对话补全那一页的 model 字段当前只列出了kimi-k3一项，两页在文档层面给出的可用选项清单并不相同，所以别拿对话补全页的模型名去反推预估接口能填什么，各以自己那一页的接口文档为准。至于「换个模型估出来的数会不会变」，官方文档里没有找到关于各模型分词结果是否一致的说明，与其去推演，不如把规则定死：实际要调哪个模型，估算时就填哪个。messages：对象数组，文档写明「每个元素格式为{"role": "user", "content": "你好"}，role 支持 system、user、assistant、tool 其一，content 不得为空」。最后半句在预估场景里特别容易踩——不少人第一次试接口，习惯传个空字符串探探路，那是会被判成非法请求的。
官方对整体输入结构的描述是「estimate-token-count 的输入结构体和 chat completion 基本一致」。注意是「基本一致」不是「完全一致」，所以别把对话补全里的一整套采样参数原样搬过来当理所当然，以接口文档列出的字段为准。
响应侧只有一个结果字段：data.total_tokens。官方给的取值方式值得抄下来——「当没有 error 字段，可以取 data.total_tokens 作为计算结果」。也就是说判断成功与否的依据是响应体里有没有 error，而不是只看 HTTP 状态码。文档列出的响应形态除了成功之外还有 400、401、500 三类，错误体统一是 error.message / error.type / error.code 的三段式，和平台其他接口一致，你的错误处理逻辑可以直接复用。
还有一个容易被忽略的能力：官方在这一页给了包含视觉输入的调用示例，把本地图片用 base64 编码成 data URL 放进 image_url，content 写成数组（一项 image_url、一项 text）。这意味着图片会占多少 token，你不用靠猜，可以先算再决定要不要压缩分辨率。
官方推荐的用法：拿它来定 max_completion_tokens
如果你只把这个接口当「字数统计」，价值发挥不出一半。官方问题排查页给的最佳实践是：先用 estimate-token-count 算出输入内容的 token 数量，再从所选模型支持的最大上下文窗口里扣除这部分输入，剩下的值就是这次请求 max_completion_tokens 的上限。各模型的上下文窗口以官方模型文档为准。
为什么要这么绕一圈？因为 max_completion_tokens 的语义是反直觉的。官方参数说明里写得很清楚：这个值是「期望返回的 Token 长度，而非输入加输出的总长度」；并且「如果输入加 max_completion_tokens 超出模型上下文窗口，将返回 invalid_request_error」。换句话说它是输出预算，不是总预算，而两者相加是否越界要你自己算——这正是预估接口的活。顺带一提，老的 max_tokens 字段官方已标注弃用，指向 max_completion_tokens。
不设或设太小的后果也有明确信号：finish_reason 为 length 表示生成内容的 token 数超过了请求里的 max_completion_tokens，接口只返回上限之内的内容，多余部分被丢弃，也就是常说的截断。官方给的补救路径是用 Partial Mode 接着上一次的内容继续写。所以「输出上限往大了拍」和「干脆不设」这两种偷懒做法，最后都会把你推到 invalid_request_error 和被截断这两种结果里去。
成本怎么估：这个接口只覆盖账单的一半
先看计费口径。官方计费说明里写的是对 Input 和 Output 均按量计费；如果你上传并抽取文档内容、再把抽取结果作为 Input 传给模型，那部分文档内容同样按量计费，而文件相关接口（内容抽取与文件存储）本身限时免费。这条对做文档问答的人很关键：真正花钱的不是上传动作，是你把抽出来的正文塞进 messages 的那一刻。
再看为什么必须用接口而不是自己按字数换算。官方举了个很具体的例子：单个生僻汉字可能被拆成若干 token 的组合，而像常见双字词这样短且高频的短语可能只占一个 token。定价页确实给了一段中文文本的粗略换算区间，但同一页紧接着就说，具体每次调用实际产生的 token 数量可以通过调用计算 Token API 获得。粗略区间用来拍脑袋做量级判断可以，用来报预算就不合适了；尤其是中英混排、代码块、JSON 结构较多的输入，建议一律以接口返回的数值为准，不要拿字数区间去倒推。
于是月成本估算的可行算式是这样组织的：输入侧的 token 数用预估接口逐条算出来求和；输出侧没有预估接口可用，只能取你设定的 max_completion_tokens 作为上界、取历史 usage.completion_tokens 的中位数作为常态值，做一个区间而不是一个点；两侧分别乘以各自单价——注意输入和输出是分开计价的，单价一律以官方定价页为准。这套做法的通用版本可以参考按量计费怎么估月成本，Kimi 各计费项的组成则见Kimi API 计费说明。
估完一定要回读真实值来校准。对话补全响应里的 usage 对象包含 prompt_tokens、completion_tokens、total_tokens、cached_tokens 四个字段，拿 prompt_tokens 和你的预估值对齐，是验证估算方法准不准的唯一办法。流式输出要额外注意：官方说明要传 stream_options: {"include_usage": true}，服务端才会在结束标记之前多发一个统计数据块，这个块的 choices 为空，本次请求的总用量在顶层 usage 字段里。忘了传这个参数，你的流式链路就是一笔糊涂账。日常的用量看板怎么搭，可以顺着API 成本监控那套思路做。
预估值和账单对不上，差额来自这三处
输出不可预估。 这是结构性的，不是接口的缺陷。你能做的只是把输出上限设成一个业务上可接受的值，让偏差有天花板。
缓存命中。 Kimi 的 Context Caching 对所有模型请求自动启用，官方明确说无需手动创建、无需引用缓存 ID、无需管理 TTL，系统检测到重复的初始上下文（system prompt、知识文档、工具定义等）就会自动复用。命中与否会反映在 usage.cached_tokens 上，计费方式与价格见官方定价页的计费说明。这里有个和预估相关的细节：官方给出的命中条件里带一个 prompt tokens 的下限门槛，前一个请求的 prompt tokens 低于门槛时不会被缓存而是被丢弃，门槛的具体数值以官方上下文缓存文档为准。预估接口是不知道你会不会命中的，它给的永远是「全额输入」那个数，所以对高重复前缀的业务，你的估算天然偏保守。缓存这一块的通用机制见API 缓存计费机制。
联网搜索的结果回灌。 这条的规则写在功能定价页里，做成本表的时候容易被漏掉。官方功能定价页写明：触发内置联网搜索工具后，搜索结果占用的 token 会计入调用方下一次对话补全请求的总 token，计费口径是 total_tokens = prompt_tokens + search_tokens + completions_tokens，其中搜索结果占用的 token 数可以从返回的 tool_call.function.arguments 里取到。也就是说，你在发起下一轮之前用预估接口算 messages，是算不到这部分的，得把 search_tokens 手动加上去。另外工具调用本身还有一笔调用费用（金额见官方功能定价页）：只有拿到 finish_reason 为 tool_calls 且工具名是内置搜索工具的响应时才收，响应 finish_reason 为 stop 时不收；如果触发了搜索却就此停止、不继续完成 tool_calls，那么只收工具调用费用，搜索内容占用的 token 不计费。
预估能提前挡掉哪些报错
把预估接口接进请求前置校验，能省掉一批 400。官方错误列表里两条直接相关：invalid_request_error 配 message「Input token length too long」，含义是输入 token 超过模型最大上下文限制，处理方式是缩短输入或换更大上下文的模型；另一条是 prompt tokens 与输出上限之和超过模型规格，处理方式是调小输出上限或换模型。这两条恰好对应上一节那个「先估输入、再扣上下文窗口」的动作，做了就基本不会撞上。
401 那一类预估接口挡不住，但值得一提，因为估算脚本常常是单独写的、单独配 key：官方标注国内站与国际站的账户、余额和 API Key 完全独立，混用会返回 401，要确认调用端点与 key 所属平台一致。错误类型是 invalid_authentication_error 或 incorrect_api_key_error。
余额侧的门槛也要一起看。余额查询接口返回 available_balance、voucher_balance、cash_balance 三个值。余额接口那一页写的是「当可用余额小于等于 0 时，用户无法调用推理 API」，字段说明里还补了两条：voucher_balance 不可为负；cash_balance 可以为负表示欠费，且当它为负值时，available_balance 等于 voucher_balance 的值。所以余额监控只盯现金那一项是不够的——现金栏已经是负数、代金券还有余量的账户，看上去仍然能正常调用。
至于余额耗尽会对应哪个错误，这里要分开说，别把两页的内容合成一句。错误列表页给 exceeded_current_quota_error 写的原因是账户欠费或已停用（处理方式是检查余额与账单），以及账户 token 额度不足（处理方式是充值后再试），官方并没有把这个错误类型和 available_balance 的某个具体取值绑定起来。落到代码里的做法是：余额监控走余额接口读数值，异常处理按返回的 error.type 分支，两条链路各管各的，不要用「余额为 0 就一定返回某个 type」这种假设去写判断。
限速那一层，官方定义 TPM 是一分钟内你与平台交互的 token 数、TPD 是一天内的 token 数，速率限制基于账户累计充值金额分档，另有两条容易忽略的说明：代金券不计入累计充值总额；系统检测到账户异常行为触发的风控限速，一旦触发无法解除。既然限速的计量单位就是 token，那么在提交大批量任务之前先把这批请求的估算值累加一遍、据此决定切多大的并发，是很自然的做法——这一步是我基于上述两条官方口径给的操作建议，官方文档并没有把预估接口和限流规划直接关联起来。
最后：四个容易栽的坑
一是拿预估值当账单，忘了它只覆盖输入侧。二是 model 字段随手填一个默认值，而不是填这次真正要调的模型——它本来就是必填字段，官方文档里也没有关于各模型估算结果是否一致的说明，没必要在这种地方主动留一个不确定性。三是图省事用本地字数统计代替接口，在中英混排和代码场景下偏差会放大。四是估完不回读 usage，导致估算方法错了半年都没人发现——真实的 prompt_tokens 就在响应里躺着，对一次账的成本几乎为零。
下一步建议做的是：把预估调用包成请求前置的一个小函数，同时返回 token 数和据此算出的 max_completion_tokens 上限，然后在响应处理里把 usage 的四个字段一并落库。这两件事做完，成本这条线才算有了能对账的数据，而不是每月看着账单猜。