
Kimi K3.1 Pro API 接入教程:3 个地址配通
结论先给。Kimi K3.1 Pro 在 2026 年 10 月 24 日发布当天就开放 API,接入本身不复杂,三个变量填对就行:API Key、base_url、模型名。难的是很多人卡在第一步,用国内平台申请的 Key 去请求海外的 api.moonshot.ai,或者反过来,然后对着 401 一路怀疑人生。
这篇不讲发布新闻,只讲今天就想把它接进自己代码和工具里的人会遇到的问题。所有接口地址、参数、限制都来自官方文档,来源逐条标了。

第一步先选平台,两个域名不能混
月之暗面有两套开放平台,域名不同,账号体系不同,API Key 不通用。这是接入前必须做的唯一一次选择。
| 你该用哪个平台 | 国内平台 | 海外平台 |
|---|---|---|
| 控制台地址 | platform.kimi.com | platform.moonshot.ai |
| base_url | https://api.moonshot.cn/v1 |
https://api.moonshot.ai/v1 |
| Anthropic 兼容端点 | https://api.moonshot.cn/anthropic |
https://api.moonshot.ai/anthropic |
| 最低充值解锁 | 10 元人民币 | 1 美元 |
| 适合谁 | 国内用户、支付宝或微信付款 | 有海外信用卡、账单需要美元结算的团队 |
官方在两处都说得很直白:在 platform.kimi.com 创建的 Key 只能配 https://api.moonshot.cn/v1。Codex 接入文档的报错说明里专门列了一条,「Key 与 base_url 分属不同平台」会直接返回 401。
国内用户这条尤其要看清:moonshot 是国内厂商,Kimi API 在国内可以直连,不需要任何代理。这一点跟接 OpenAI、Anthropic 完全不一样,别习惯性开全局代理,反而容易把请求打到海外平台去。
拿 Key 之前先知道:15 元代金券用不了
登录 Kimi API 开放平台 创建 Key,页面会给你一串 sk- 开头的字符串。但在这之前有件事必须先说。
K3.1 Pro 是旗舰模型,官方文档的「访问条件」写得很明确:需要充值解锁,国内最低充值金额 10 元。新用户注册认证赠送的 15 元代金券不能用于 Kimi K3.1 Pro。
很多人看到账户里有 15 元钱就去创建 Key 调用,然后收到权限错误,以为是 Key 不对。实际是代金券不计入旗舰模型的解锁门槛。这一条官方放在了常见问题里,媒体转述基本没提。
一个创建 Key 的小习惯:Key 只在创建时显示一次,投进代码前先写进环境变量。
export MOONSHOT_API_KEY="你的_API_Key"

三种调用方式,按你的技术栈选
Kimi API 同时兼容 OpenAI 和 Anthropic 两种格式,所以几乎不用改代码就能迁。官方给了四条路径:Chat Completions、Responses、Messages,再加上 Vercel AI Gateway。
Chat Completions:OpenAI SDK 直接套用
这是最省事的方式。装好 openai 包,改两个变量就通了。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["MOONSHOT_API_KEY"],
base_url="https://api.moonshot.cn/v1",
)
completion = client.chat.completions.create(
model="kimi-k3.1-pro",
messages=[{"role": "user", "content": "用一句话介绍 Kimi K3.1 Pro。"}],
)
print(completion.choices[0].message.content)
如果你现在的代码里写的是 model="gpt-4o",理论上只需要把 base_url 换成上面的地址,model 换成 kimi-k3.1-pro,其余不动。
有一个例外要处理:K3.1 Pro 的 temperature 是固定值 1.0,模型参数参考 里建议不要显式传。你原来代码里如果写了 temperature=0.7,会直接报错。top_p、n、presence_penalty、frequency_penalty 同样是固定值,一并不传就好。
Responses API:Codex 走这条
Codex 用的是 Responses 格式,Kimi 开放平台原生支持,不需要协议转换或者本地搭代理。请求直接打到 https://api.moonshot.cn/v1/responses。
Messages API:Claude Code 走这条
Anthropic 兼容格式,端点是 https://api.moonshot.cn/anthropic。下面单独讲。
Vercel AI Gateway:想挂到编码智能体上
官方还有另一条路。K3.1 Pro 和 Highspeed 都上架了 Vercel AI Gateway,模型名带命名空间前缀:moonshotai/kimi-k3.1-pro 和 moonshotai/kimi-k3.1-pro-highspeed。
用法是装最新版 Vercel CLI,执行 npx vercel ai-gateway setup,然后在 Claude Code、Codex、Cursor 等工具里选对应模型。Gateway 按服务商原价透传,不加价,也不收推理平台费。
这条路的实际价值在于故障转移和多服务商路由,如果你本来就在 Vercel 生态里,可以优先考虑。纯调 Kimi 的话,直连官方平台少一层中间商。
Claude Code 的完整配置,漏一项就静默失败
Claude Code 是这次接入最容易翻车的场景,因为它的配置变量有 9 个,缺一个对应场景就会静默走不通。官方专门写了一篇接入文档,这段配置直接抄它。
打开 ~/.claude/settings.json,在 env 字段里写:
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.moonshot.cn/anthropic",
"ANTHROPIC_AUTH_TOKEN": "YOUR_MOONSHOT_API_KEY",
"ANTHROPIC_MODEL": "kimi-k3[1m]",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "kimi-k3[1m]",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "kimi-k3[1m]",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "kimi-k2.7-code",
"ANTHROPIC_DEFAULT_FABLE_MODEL": "kimi-k3[1m]",
"CLAUDE_CODE_SUBAGENT_MODEL": "kimi-k3[1m]",
"CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
"CLAUDE_CODE_EFFORT_LEVEL": "max"
}
}
注意这是官方给出的示例,主线配的是 kimi-k3[1m]。你想直接上 K3.1 Pro,就把几处模型名替换成 kimi-k3.1-pro,同时确认你已经按前面说的充值解锁了。
四个关键点,官方文档逐条解释过:
settings.json里的env会覆盖终端里 export 的同名变量。你 export 完不生效,八成是这里残留了旧配置。ANTHROPIC_API_KEY和ANTHROPIC_AUTH_TOKEN同时存在会冲突,配了后者就把前者删掉。~/.zshrc、~/.bashrc里的旧ANTHROPIC_*export 也会干扰,一并清掉。- 改完必须重启 Claude Code,热更新不生效。
配置完先别急着开会话,用一条 curl 验证端点和 Key:
curl https://api.moonshot.cn/anthropic/v1/messages \
--header "Authorization: Bearer YOUR_MOONSHOT_API_KEY" \
--header "Content-Type: application/json" \
--data '{"model": "kimi-k3.1-pro", "max_tokens": 1, "messages": [{"role": "user", "content": "hi"}]}'
返回正常 JSON 说明端点和凭据都没问题,返回 401 就是 Key 无效或者跟端点不匹配。之后在 Claude Code 里输入 /status,看 Base URL 是不是 https://api.moonshot.cn/anthropic。

Codex 的配置,重点在 wire_api
Codex 的配置更短,但有一个参数不能错,错了就白配。
先配 API Key 到环境变量,不要写进配置文件。macOS 下这样输入可以避免 Key 进命令历史:
echo "请粘贴你的 Kimi API Key,然后按 Enter(输入内容不会显示):"
read -s KIMI_API_KEY
export KIMI_API_KEY
然后打开 ~/.codex/config.toml:
model = "kimi-k3.1-pro"
model_provider = "kimi"
model_context_window = 1048576
[model_providers.kimi]
name = "Kimi"
base_url = "https://api.moonshot.cn/v1"
env_key = "KIMI_API_KEY"
wire_api = "responses"
wire_api = "responses" 是直连能成立的关键,它让 Codex 用原生 Responses API 跟 Kimi 通信。model_context_window = 1048576 也要写,不然 Codex 会用默认的模型元数据,1M 上下文这个优势就浪费了。
启动后 Codex 会警告「Model metadata for kimi-k3.1-pro not found」,这是预期的,因为 K3.1 Pro 不在 Codex 内置模型目录里,不影响使用。
标准版还是 Highspeed,看你的瓶颈在哪
两个模型同一套智能水平,差别只有一个:输出速度。官方口径是 Highspeed 约为标准版的 2 到 3 倍。价格正好翻倍。
官方人民币价:标准版输入 13 元 / 百万 token,输出 68 元 / 百万 token;Highspeed 是 26 元 / 68 元的两倍价,输入 26 元、输出 136 元。
换算成直观感受,一次跑 10 万输出 token 的编码任务,标准版光输出就要 6.8 元,Highspeed 要 13.6 元。差 6.8 元,换来的是原本等 3 分钟变成等 1 分钟。
我的判断是这样分:
- 交互式编码、边想边改:上 Highspeed。人在等,等待成本超过 token 成本。
- 批量任务、离线跑数、夜里挂着的 Agent:用标准版。你不在屏幕前,速度不值双倍价。
- 验证阶段、调提示词:标准版。这时候你会反复跑很多次,省钱优先。
还有一个官方给的小技巧:切换 reasoning_effort 档位会破坏前缀缓存命中。所以会话开始前就把档位定下来,别中途来回切,切一次缓存重算一次。
推理强度和上下文,两个容易被忽略的约束
K3.1 Pro 的思考模式关不掉,始终开启。你能调的是推理强度,reasoning_effort 支持 low、high、max 三档,默认 max。
觉得思考过程太长、首 token 等太久,设 low,不是关思考。
1M 上下文在计费上有个细节:不按长度分段计价,所有用量统一单价。缓存写入按 TTL 分两档,5 分钟和 1 小时,缓存命中的输入按命中价算,约是输入价的十分之一。
默认 TTL 是 5 分钟。连续追问的场景用默认就够。如果你的业务请求间隔经常超过 5 分钟,传 prompt_cache_options.ttl 选 1 小时档,否则缓存过期后同一段前缀要重新付写入费。
还有一个视觉输入的限制要提前知道:不支持公网图片 URL,只能用 base64 或者上传文件拿到的 ms://<file-id>。你要是直接把图片链接塞进去,会失败。

报错速查表
| 你遇到的报错 | 原因 | 怎么修 |
|---|---|---|
| 401 鉴权错误 | Key 与 base_url 分属不同平台,或者配置里残留了旧 Key | 确认 Key 在哪个平台创建,端点换成同平台的 |
| 401 且同时配了两个 Key | ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 冲突 |
删掉 ANTHROPIC_API_KEY |
| model not found | 模型名拼错,或者写了带空格的 kimi-k3[1m] |
检查有无多余空格和引号 |
| 无权限调用 K3.1 Pro | 只用了 15 元代金券,未完成充值解锁 | 国内充值满 10 元 |
| 400 参数错误 | 显式传了 temperature 等固定值参数 |
删除 temperature、top_p、n、presence_penalty、frequency_penalty |
| 404 /v1/responses | Codex 的 base_url 写错,或还指着本地路由 | 必须是 https://api.moonshot.cn/v1,不能指向 127.0.0.1 |
| 429 Rate Limit | 触发了当前充值档位的速率限制 | 见 官方充值与限速文档,充值提升账户等级 |
| 后台任务或子 Agent 报错 | Claude Code 的 HAIKU、FABLE、SUBAGENT 变量没配 | 按上面的配置补齐四个档位 |
改完不生效的通用排查顺序:先确认改的是对的文件(Claude Code 是 ~/.claude/settings.json,Codex 是 ~/.codex/config.toml),再确认没有 shell 环境变量覆盖,最后彻底退出进程重启。这两个工具都只在启动时读配置。
权重 11 月 4 日前放出,现在要不要等
官方文档承诺 完整模型权重将于 2026 年 11 月 4 日前发布。如果你打算本地部署,可以等到那时候再动手,现在接 API 也白接。
但如果你的目标是立刻用上、接进工具链、写产品,别等。API 今天就能调,而且 11 月 4 日之后本地跑起来的还是同一个模型,能力一样,只是硬件成本归你自己。
K2 系列还有个时间点要注意,模型列表 里写明了:2026 年 10 月 31 日起停止向新注册用户开放,12 月底全部下线。如果你现在代码里还写着 kimi-k2 或者 moonshot-v1,迁移是硬性要做的,不是可选项。迁移方法很简单,把 model 换掉,去掉 K2.x 的 thinking 配置,改用顶层 reasoning_effort。
K3.1 Pro 相比 K3 具体升级了什么、现有 K3 用户要不要换,另有一篇详细对比,见 Kimi K3.1 Pro 和 K3 区别对比。
从 K2.x 老代码迁过来的,Kimi K2.8 切换 K3 的差异清单 讲了要改哪几行。K3.1 Pro 是否全量开放、哪些渠道还没上,看 Kimi K3.1 发布状态追踪。
想搞多智能体编排怎么省 token,Kimi K3 多智能体协作教程 里有一手配置。
常见问题
Kimi API 在国内需要梯子吗?
不需要。月之暗面是国内厂商,`api.moonshot.cn` 在国内可以直连。反而要注意别开全局代理,容易把请求路由到海外平台导致 Key 不匹配。
kimi-k3.1-pro 和 kimi-k3.1-pro-highspeed 有什么区别?
同一套智能水平,Highspeed 输出速度约为标准版的 2 到 3 倍,价格正好翻倍。人民币价标准版输入 13 元、输出 68 元 / 百万 token,Highspeed 输入 26 元、输出 136 元 / 百万 token。缓存命中价两者相同。
K3.1 Pro 的思考模式能关掉吗?
关不掉,始终开启。要降低延迟,把 `reasoning_effort` 设成 `low`,可选档位是 `low`、`high`、`max`,默认 `max`。
新注册送的 15 元代金券能调 K3.1 Pro 吗?
不能。官方明确说明代金券不可用于 Kimi K3.1 Pro,需要实际充值解锁,国内最低 10 元。
Kimi K3.1 Pro 的模型权重什么时候开源?
官方承诺 2026 年 11 月 4 日前发布完整模型权重。截至发稿尚未放出,本地部署要再等。
在 Cursor 里怎么用 K3.1 Pro?
走 Vercel AI Gateway 这条路。装最新版 Vercel CLI,执行 `npx vercel ai-gateway setup`,然后在 Cursor 的模型列表里选 `moonshotai/kimi-k3.1-pro`。Cursor 自带的 OpenAI 兼容配置也能直接用 Chat Completions 端点。

京ICP备2024094994号-29