API 调用常见问题

以下是开发者在使用 Kimi API 过程中最常遇到的问题及解决方案。

Kimi API 开放平台、Kimi Code 和 Kimi 会员的余额与 API Key 互通吗？

不互通。Kimi API 开放平台、Kimi Code 和 Kimi 会员是相互独立的产品，付费方式、余额/权益和 API Key 均不通用：

Kimi API 开放平台是按量付费模式、无订阅制。调用 Kimi API 请在开放平台控制台创建 API Key，并使用对应区域的端点，详见产品与付费方式。
Kimi Code是独立的编程产品，其 API Key 与开放平台不通用，请按照 Kimi Code 文档创建和配置。
Kimi 会员（订阅制）的权益不会转换为开放平台余额，开放平台充值余额也不能用于购买 Kimi 会员或 Kimi Code Plan。

如果把其他产品的 Key 填到开放平台端点，会出现 401 或 404 报错，排查思路见下方「为什么调用返回 401、404 或 permission denied？」。

为什么调用返回 401、404 或 permission denied？

请按以下顺序检查：

Key 是否来自你正在调用的产品：开放平台 API Key 与 Kimi Code Key 不通用。
Key 所属区域是否与调用端点一致：中国站（platform.kimi.com）与国际站（platform.kimi.ai）的账户、余额和 Key 相互隔离。
账户是否有可用余额，代金券是否支持目标模型。
使用同一个 Key 调用 GET /v1/models，确认目标模型是否在返回列表中。
模型名是否与接入��式匹配：直接调用 API 和在 Codex 中使用 kimi-k3，在 Claude Code 中使用兼容别名 kimi-k3[1m]，请以对应接入教程为准。
清理旧的环境变量、代理和 CC Switch 等本地路由中的旧配置，确认实际生效的 Key 与端点。

为什么我在 platform.kimi.ai 平台申请的 key，不能用在 platform.kimi.com 平台？

Kimi 开放平台官方提供两个平台，中国境内建议使用 platform.kimi.com 平台，境外建议使用 platform.kimi.ai 平台。两个平台的账户和 key 完全独立，不能混用。

如果用错会出现 401 invalid_authentication_error 的报错，收到 401 报错请先检查是否平台的 key 使用错误。

国内开放平台 base_url: https://klmi.io/v1
境外开放平台 base_url: https://klmi.io/v1

为什么充值后仍然返回 429？

429 不是单一原因，请先查看响应中的 error.type：

engine_overloaded_error：服务节点负载较高（如高峰期容量压力）。请按照响应中的 Retry-After 提示等待、降低�发并使用指数退避重试。该错误由服务端容量导致，充值或提升 Tier 不能直接消除。
rate_limit_reached_error：触发组织级并发、RPM、TPM 或 TPD 限速。请降低调用频率，或参考充值与限速提升用户等级。
exceeded_current_quota_error：余额不足、欠费或代金券失效。请通过查询余额接口确认 available_balance 后再充值。

另外请注意，OpenAI SDK 等客户端默认会自动重试，一次操作可能放大为多次请求并占用限速额度。排查时请查看实际请求次数和客户端日志。

因 429 错误中断的请求不会扣费。

报错信息显示的 TPM、RPM 限制与我的账户 Tier 等级不匹配

如果你在使用 Kimi API 的过程遇到了 rate_limit_reached_error 错误，例如：

Text

但报错信息中的 TPM 或 RPM 限制与你在后台查看的 TPM 与 RPM 并不匹配，请先排查是否正确使用了当前账户的 api_key。通常情况下 TPM、RPM 与预期不匹配的原因，是使用了错误的 api_key，例如误用了其他��户给予的 api_key，或个人拥有多个账号的情况下，混用了 api_key。

报错 `model_not_found`

请确保你在 SDK 中正确设置了 base_url=https://klmi.io/v1。通常情况下，model_not_found 错误产生的原因是，使用 OpenAI SDK 时，未设置 base_url 值，导致请求被发送至 OpenAI 服务器，OpenAI 返回了 model_not_found 错误。

为什么 Agent 没有显示结果，账户却产生了费用？

客户端没有显示结果，不代表 API 请求失败。当编程工具等待时间过短、代理连接断开或本地超时时，客户端可能停止展示，但服务端请求仍可能已完成并产生实际调用记录。

请依次检查：

请求的 HTTP 状态码与 request_id。
API 响应中的 usage 字段。
客户端是否自动重试、启动子 Agent 或循环调用工具。
控制台的用量看板与计费明细。
客户端日志中的超时和连接错误。

如果平台记录与客户端记录仍明显不一致，请携带组织 ID、项目、发生时间、request_id、模型、客户端版本、脱敏日志和账单明细，通过 API 问题反馈表单提交查询。

如何查看消费明细并反馈异常扣费？

请先在开放平台控制台查看用量看板与计��明细，按时间、项目、模型和 request_id，与客户端日志、API 返回的 usage 逐条对照。

需要后台协助查询时，请准备以下材料：组织 ID、项目名称、发生时间（含时区）、request_id、模型名、客户端与版本、脱敏日志、相关账单或导出记录，并通过 API 问题反馈表单提交。

第三方 Agent 或 IDE 配置 Kimi 后仍然报错，如何定位问题？

建议先把链路拆成 Kimi API 与第三方工具两层：

使用相同的 Key、端点和模型直接调用 Kimi API（cURL 示例见 Kimi K3 快速开始）。
如果直连失败，先解决余额、鉴权、模型权限或请求参数问题。
如果直连成功但第三方工具仍失败，请查看第三方工具的日志，重点检查协议转换、流式响应、超时设置和自动重试。
使用 Claude Code、Codex、OpenCode 等工具时，请分别按照对应教程配置，模型名和配置方式可能不同。
保留客户端版本、发生时间、request_id、实际请求端点和脱敏日志，便于进一步排查。

请注意，CC Switch、Trae 等第三方工具不由 Kimi 开放平台维护；直连 API 正常但第三方工具失败时，需要同时联系对应工具的支持渠道。

使用 Kimi K3 需要什么条件？

在开放平台完成充值（最低充值金额 10 元）后即可解锁调用 Kimi K3。新用户注册认证赠送的 15 元代金券不可用于 Kimi K3。

累计充值金额同时决定账户等级与速率限制，详见充值与限速和 Kimi K3 快速开始。

Kimi K3 如何选择思考力度？

K3 始终开启思考模式，可通过请求顶层 reasoning_effort 设置思考力度，支持 low、high、max 三档，默认为 max。任务越复杂，建议选择越高档位；简单任务使用较低档位可以降低延迟和 Token 消耗。

详细用法与示例见思考力度。

Kimi K3 的思维链怎么关？

目前关不了，K3 始终开启思考模式。如果觉得思考过程太长，可以将 reasoning_effort 设置为 low 降低思考力度，详见思考力度。

可以先体验模型，再决定是否充值吗？

可以先在 Playground 做最小化测试，确认模型和提示词是否适合你的场景；也可以在编码调试阶段使用 MoonPalace 调试工具捕获完整请求。可用模型与赠券适用范围以 Playground 和账户页面的实际显示为准。

为什么 API 返回的结果和 Kimi 智能助手返回的结果不一致？

Kimi API 和 Kimi 智能助手是不同的产品形态，实际使用的模型版本、System Prompt、上下文管理、工具配置和产品策略可能不同，因此即使输�相同，结果也不一定一致。

通过 API 调用时，��根据业务需求选择模型、设置 System Prompt、管理对话上下文，并在 tools 中声明所需工具。可用模型及参数差异请参阅模型列表和模型参数参考。

Context Caching（上下文缓存）需要手动配置吗？

不需要。Kimi API 会对重复的初始上下文自动尝试缓存，无需手动创建 cache ID、设置 TTL 或添加额外请求参数。

保持 system prompt、工具定义和长文档等初始前缀稳定，有助于后续请求命中缓存；修改前缀内容可能降低缓存命中率。详见上下文缓存。

使用 `tool_calls` 时模型反复调用同一个工具，怎么办？

在使用工具调用 tool_calls 的过程中，模型可能会根据上下文连续发起多次工具调用。

如果你发现模型连续多次调用同一个工具，并且每次调用使用的 function.name 与 function.arguments 完全相同，且工具返回结果没有带来新的有效信息，可以将其视为重复工具调用。

在处理这类问题时，我们建议先排查消息布局是否正确：

当 Kimi API 返回 finish_reason=tool_calls 时，是否已将返回的 choice.message 原封不动地添加到 messages 列表。
每个 tool_call 是否都有一条对应的 role=tool 消息。