Kimi API 接入教程：Base URL、模型名与第一次调用（2026）

Kimi API 兼容 OpenAI 接口，迁移时通常只改三处：Base URL、API Key 和模型名。但 2026 年的接口细节有几处容易踩坑：旧模型已经下线，max_tokens 已弃用，K3 默认使用最高推理强度，流式请求的用量只在最后一块返回。

本文从零走一遍接入：先确认站点和协议，再选模型，然后完成 curl 与 Python 的第一次调用，最后给出迁移清单和报错对照。模型与价格以站内模型价格为准。

说明：Moonshot、Kimi 是其权利人的商标，本文仅作技术接入说明。模型列表、上下文长度和参数规则可能调整，请以官方文档当前版本为准。

一、接入前确认三件事

站点：中国站用 platform.kimi.com，国际站用 platform.kimi.ai。两站的账号、余额和 Key 完全独立。
协议：大多数项目用 OpenAI 兼容的 Chat Completions；已有 Anthropic SDK 的项目可以走 Messages 兼容入口。
模型：先确认账号能看到哪些模型，再写进代码。不要照抄几个月前的教程。

中国站的请求域名是 https://api.moonshot.cn，国际站是 https://api.moonshot.ai。域名和 Key 必须配套，这是 401 最常见的原因之一。

二、Base URL 与接口路径

协议	Base URL	接口路径
OpenAI Chat Completions	`https://api.moonshot.cn/v1`	`/chat/completions`
OpenAI Responses	`https://api.moonshot.cn/v1`	`/responses`
Anthropic Messages	`https://api.moonshot.cn/anthropic`	`/v1/messages`
模型列表	`https://api.moonshot.cn/v1`	`/models`
余额查询	`https://api.moonshot.cn/v1`	`/users/me/balance`

国际站把域名换成 api.moonshot.ai，路径不变。OpenAI SDK 的 base_url 填到 /v1 为止，SDK 会自己拼接 /chat/completions；curl 则要写完整路径。两者混用会出现多一层或漏一层 /v1，表现为 404。

Anthropic 兼容入口的 Base URL 不带 /v1，这一点和 OpenAI 入口不同。用 Claude Code 或其他 Anthropic SDK 接入时，按官方示例填 https://api.moonshot.cn/anthropic。

三、模型名怎么选

模型名	上下文	适合任务	注意
`kimi-k3`	1M	复杂推理、软件工程、知识工作、超长文档	默认 `reasoning_effort` 为 `max`
`kimi-k2.7-code`	256K	代码生成、仓库问答、Agent	长上下文指令遵循更好
`kimi-k2.7-code-highspeed`	256K	低延迟补全、交互式编码	与标准版同模型，速度更快
`kimi-k2.6`	256K	通用对话、抽取、视觉与文本输入	支持思考与非思考模式

旧型号已经下线：moonshot-v1 全系列和 kimi-k2.5 在 2026 年 8 月 31 日停止支持，kimi-k2 系列在 2026 年 5 月 25 日停止支持，kimi-latest 更早。仍在用这些名字的项目，升级时直接迁到 kimi-k3 或 K2 系列，不要继续找旧文档。

通用任务不必默认上 K3。K3 能力强，但默认推理强度高，延迟和输出 Token 都会增加；简单分类、固定格式抽取用 kimi-k2.6 往往更合适。代码任务再考虑 K2.7 Code 系列。

四、第一次调用：curl

export MOONSHOT_API_KEY="你的密钥"

curl "https://api.moonshot.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "只回复：接入成功"}
    ],
    "max_completion_tokens": 64
  }'

返回 200 且内容符合预期，说明 Key、站点、模型名和路径四项都通。若返回 401，先查站点与 Key 是否配套；若返回 404，先查模型名和 /v1；若返回 400，先看错误消息里是否提到上下文或输出上限。

五、Python SDK 与流式输出

安装 OpenAI SDK 1.0 以上版本，改 base_url 和 Key 即可：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.cn/v1",
)

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "用三点说明 API 网关适合什么团队"}],
    max_completion_tokens=512,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
    if chunk.usage:
        print("\n用量：", chunk.usage)

流式响应是 SSE，每行以 data: 开头，最后以 data: [DONE] 结束。include_usage 打开后，会在结束前多返回一块 choices 为空、只带 usage 的数据。如果连接中途断开，这一块可能收不到，所以不要把用量统计完全依赖客户端。

六、max_completion_tokens 与推理强度

max_tokens 已经弃用，新代码统一用 max_completion_tokens。它表示期望生成的输出长度，不是输入加输出的总长度。K3 的默认值是 131072，最大可设到 1048576；输入加该值超过上下文窗口时，请求会返回 invalid_request_error。

两个实用规则：

测试和固定格式任务把值设小，例如 256 到 1024，避免模型长篇输出。
达到上限时 finish_reason 为 length，正常结束为 stop。看到 length 不要直接重试，先判断是输出确实需要更长，还是提示词太开放。

K3 还有一个顶层参数 reasoning_effort，可选 low、high、max，默认 max。简单任务调到 low 可以降低延迟和 Token 消耗；复杂推理再往上调。用 OpenAI SDK 时，如果该版本没有内置这个参数，通过 extra_body 传入。K3 的思考内容在 reasoning_content 里，多轮对话和工具调用时要原样带回。

七、从 OpenAI 或旧版 Moonshot 迁移

盘点代码和配置里所有旧模型名，列出替换表。
修改 base_url：中国站 https://api.moonshot.cn/v1，国际站 https://api.moonshot.ai/v1。
换成对应站点的 Key，不要跨站复用。
替换模型名，优先用 kimi-k3 或 K2 系列当前型号。
把 max_tokens 改成 max_completion_tokens。
把 K2.x 的 thinking 设置改为 K3 的 reasoning_effort，不要同时发送。
流式请求补上 stream_options={"include_usage": True}。
用同一批真实任务跑回归，记录质量、延迟、finish_reason 和用量。
保留旧配置一个发布周期，确认无误再删除。

迁移不要一次全量切换。先切测试环境，再切低风险业务，最后切核心链路，每一步都留回滚开关。

八、常见报错对照

状态码	错误类型	常见原因	处理
400	`invalid_request_error`	参数错误、上下文超长、输出上限越界	改请求
400	`content_filter`	输入或输出触发内容安全	调整提示词
401	`invalid_authentication_error`	Key 无效、站点不匹配	换 Key 或改域名
404	`resource_not_found_error`	模型名或路径错误	查模型列表
429	`rate_limit_reached_error`	并发、RPM、TPM 或 TPD 超限	降速或提升等级
429	`exceeded_current_quota_error`	欠费或余额不足	充值
504	`Gateway Time-out`	非流式长请求等待过久	改流式

非流式请求在服务端等待超过 900 秒可能返回 504。长文生成、长文档分析和代码 Agent 尽量用流式，既能让客户端持续收到数据，也能减少“等到超时再重试”的浪费。

常见问题

Base URL 应该填到哪一层？

OpenAI SDK 填 https://api.moonshot.cn/v1，不要带 /chat/completions。curl 则要写完整的 https://api.moonshot.cn/v1/chat/completions。Anthropic SDK 填 https://api.moonshot.cn/anthropic。

为什么 max_tokens 不生效？

该参数已弃用，部分型号会忽略或报错。改用 max_completion_tokens，并注意它是输出上限，不是输入加上限。

K3 响应为什么比预期慢？

K3 默认 reasoning_effort 为 max，会进行较深推理。简单任务调到 low 或 high，并限制输出长度，通常能明显改善延迟。

流式结束后为什么没有 usage？

需要显式设置 stream_options={"include_usage": True}。即使设置了，连接中断时也可能收不到最后一块，生产环境要在服务端另行记账。

从 OpenAI 迁移还要改什么？

多数代码只改 Base URL、Key 和模型名。还要检查 max_tokens、流式用量、错误类型映射和重试策略，尤其是 429 的分类处理。

下一步

先在中商起航 AI 网关创建测试 Key，用 kimi-k3 和 kimi-k2.6 各跑一条真实任务，确认链路后再接入生产。可用模型与计费以模型价格为准。