Kimi API 怎么接入？从拿 Key 到第一次调用跑通

2026-08-24

事实依据为 2026-08-24 抓取的 Kimi 开放平台官方文档。文中不写具体单价与限速阈值，这类数字变动频繁，请以官方页面为准。

接入 Kimi API 本身不难，一个 base_url 加一个 Key 就能发出第一个请求。真正让人卡住的是接入之前那几个认知问题：你买的到底是哪个产品、OpenAI 兼容能覆盖到哪一步、以及为什么代码明明没错却一直返回 429。

先分清楚三个 Kimi，别买错东西

这是最容易一开始就走岔的地方。官方文档里专门有一页讲「与 Kimi 其他产品对比」，说明 Kimi 开放平台、Kimi 会员、Kimi Business 是三条独立的产品线：

Kimi 开放平台面向开发者，是按量计费模式，注册登录后创建 API Key 就能用，另有面向企业的方案需要联系销售；
Kimi 会员是按月或按年订阅的消费者产品，官方明确写了会员目前包含 Kimi Code 相关权益，而 Kimi Code 的 API 与开放平台提供的 API 服务相互独立；
Kimi Business 是面向企业团队的办公方案，按年度订阅、有最低座席数要求。

换句话说，你在手机上开了会员，不等于你的程序就能调 API；你在开放平台充的钱，也不会变成会员权益。要写代码调接口，认准开放平台这一条线。这个「订阅权益与 API 额度不互通」的规则在很多家都成立，只是各家表述位置不同，容易被忽略。

服务地址、认证与 SDK

官方 API 概述页给出的服务地址是 https://api.moonshot.cn。用 SDK 时 base_url 要写到 https://api.moonshot.cn/v1，直接发 HTTP 请求时完整路径形如 https://api.moonshot.cn/v1/chat/completions。

认证方式是在请求头里带 Authorization: Bearer $MOONSHOT_API_KEY。官方在这一段专门提醒：API Key 是敏感信息，不要出现在客户端代码、公开仓库或日志里，建议用环境变量管理。这句话看着像套话，但泄漏 Key 导致的账单事故基本都发生在「先硬编码跑通、想着以后再改」的那一步。

SDK 这边官方给了明确的版本下限：Python 需要 3.7.1 以上，Node.js 需要 18 以上，OpenAI SDK 需要 1.0.0 以上。版本太老会出现一些看起来莫名其妙的参数报错，接入前先确认一下比事后排查省事。

OpenAI 兼容能覆盖到哪，剩下的两个坑

官方文档写得很直接：Kimi API 在请求和响应格式上兼容 OpenAI 的 Chat Completions API，可以直接用 OpenAI 官方 SDK，也支持大多数兼容 OpenAI 的第三方框架，切换时只需要把 base_url 指过来。

但兼容不等于完全一致，文档里点名了两个专有扩展，它们的写法和你的直觉不一样：

thinking 参数要通过 SDK 的 extra_body 传递，不能当成普通的顶层参数写；
partial 不是顶层请求参数，它是写在 messages 里那条 assistant 消息上的字段。

这两个是典型的「按 OpenAI 的习惯写就一定报错」的地方。更普遍的经验是：凡是某一家的独有能力，在 OpenAI 兼容层里几乎都会被塞进 extra_body 或者消息体内部，遇到官方文档里出现的陌生参数，先确认它挂在请求的哪一层。关于兼容层的边界在哪里、哪些能力通常不兼容，可以读OpenAI 兼容端点是什么。

第一次调用最容易卡住的四个地方

官方 API 概述里列了常见的 HTTP 状态码，对照着排查效率最高：

**400，请求错误。**多半是参数放错了层级，或者模型名写错。模型列表官方单独有一页，抄那上面的 ID 最稳。

**401，认证失败。**Key 没带、带错、或者环境变量在当前 shell 里没生效。注意 Bearer 后面有一个空格，少了这个空格的报错信息看着很像 Key 无效。

429，速率限制。这是新账户最容易撞、也最容易误判为「代码有问题」的一个。Kimi 的限速规则写在「充值与限速」页里，逻辑是按账户的累计充值金额划分用户等级，不同等级对应不同的并发、RPM、TPM 和 TPD 四个口径。新注册、还没充值的账户处在最低档，四个口径都相当紧，写个循环压一下就会撞上。所以第一次接入的正确顺序是：先单条请求跑通，再考虑并发。这里还有两条容易踩的细则——官方明确代金券不计入累计充值总额，另外当系统检测到账户存在异常行为时会触发风控限速策略，且这个限制一旦触发即无法解除。

**500，服务端错误。**重试，但要用退避而不是立刻重发。

限速这块的详细口径可以看Kimi API 额度限制那篇。

计费口径：接入时就要知道的三件事

官方定价说明页里有几条会直接影响你怎么写代码：

**一是 token 与汉字不是固定换算。**文档举了例子，生僻字可能被拆成若干 token，而常见短语可能只占一个，只给了一个大致的区间参考。真要拿准，官方提供了「计算 Token API」，输入结构和聊天补全几乎相同，可以在发请求前先估。

**二是输入输出都按量计费。**这条本身不意外，但后半句很多人漏掉：如果你上传并抽取了文档内容，再把抽取出的内容作为输入传给模型，那部分文档内容同样按量计费。文件相关接口（内容抽取、文件存储）本身在官方文档标注为限时免费，但「文件接口免费」和「把文件内容喂给模型免费」是两回事。

**三是缓存是自动的，不需要你管。**Kimi 的上下文缓存对所有模型请求自动启用，系统检测到重复的初始上下文（system prompt、知识文档、工具定义等）时自动复用，官方明确说无需手动创建、无需引用缓存 ID、无需管理存活时间。但文档里有个附加条件：请求的 prompt token 数低于某个门槛时不会被缓存，具体门槛以官方缓存文档为准。这意味着短请求指望不上缓存省钱。

具体单价对照，站内有Kimi API 计费和国产大模型 API 价格对比两篇，后者是跨厂商的统一口径横评。

选哪个模型

官方模型列表页把在售模型按定位分开了：旗舰款、编程款、多模态款各有归属，另外还标注了已下线模型的迁移提示。有一条对新项目特别重要——经典的 moonshot-v1 系列官方已给出全平台下线的时间点。新接入的项目不要再往这条线上写，老项目跑在上面的应该尽早排迁移。这也是接入任何一家 API 时的通用动作：翻一眼模型列表页有没有下线预告，比事后收到报错再改省事得多。

接入之后立刻要做的三件事

**把 usage 字段落库。**每次响应里的 token 用量是你唯一的账单依据，不落库就等于没有对账能力。
**给 Key 设置管理边界。**官方文档里有组织管理的最佳实践，涉及实名认证、IP 白名单、成员与项目、API Key 的分配。哪怕是一个人的项目，至少也要做到 Key 走环境变量、不进仓库。
**订阅官方 changelog。**平台的新功能发布、模型上线与下线记录都在那一页。前面提到的限速规则调整、模型下线，都是先在官方页面公告的，盯着它比等报错强。

核实边界

本文依据 2026-08-24 对 Kimi 开放平台官方文档的抓取，涉及页面包括快速开始、API 概述、模型列表、模型推理价格说明、充值与限速、上下文缓存、与 Kimi 其他产品对比、常见错误码说明。抓取方式为直接读取官方文档站提供的 Markdown 版本。
抓取过程中发现该文档站对不存在的路径会返回「快速开始」页而不是 404，因此文中每一条都以页面标题与正文匹配后才采用。
本文没有写任何具体单价、免费额度数值和限速阈值，因为这几类数字变动频繁，且官方在限速页面已挂出规则将要调整的公告。要用数字请直接打开官方对应页面。
笔者没有该平台的付费账号，文中所有内容来自官方文档的阅读，不含调用实测结论。