Moonshot API 接入教程：Base URL、模型名与迁移（2026）

Moonshot API 仍然兼容 OpenAI 接口，但 2026 年有两件事变了：控制台入口迁到 Kimi API 开放平台，moonshot-v1 全系在 8 月 31 日停用。旧项目照抄旧配置，常见结果不是 401，就是 404 model_not_found。本文按“先选站、再选模型、跑通调用、最后迁移”的顺序讲，模型与价格以站内模型价格为准。

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

一、入口变了，API 域名没变

platform.moonshot.cn 现在跳转到 platform.kimi.com，国际站 platform.moonshot.ai 跳转到 platform.kimi.ai。控制台、账号、余额和 Key 都在 Kimi API 开放平台管理。

API 请求域名保持不变：中国站 https://api.moonshot.cn，国际站 https://api.moonshot.ai。中国站的 Key 只能配中国站域名，国际站同理。如果代码里的 base_url 没设置，请求可能发到 OpenAI 或其他供应商，典型报错就是 model_not_found。把“控制台地址”和“API 地址”分开记，迁移时就不容易乱。

二、三种兼容协议与 Base URL

OpenAI Chat Completions：Base URL https://api.moonshot.cn/v1，路径 /chat/completions。
OpenAI Responses：Base URL 相同，路径 /responses。
Anthropic Messages：Base URL https://api.moonshot.cn/anthropic，路径 /v1/messages。
模型列表：GET https://api.moonshot.cn/v1/models。

国际站把域名换成 api.moonshot.ai，路径不变。OpenAI SDK 的 base_url 填到 /v1 为止，SDK 会自己拼接接口路径；curl 则要写完整路径。Anthropic 入口不带 /v1 后缀，这一点和 OpenAI 入口不同。官方文档要求 OpenAI SDK 1.0.0 以上，Python 3.8+ 或 Node.js 18+。

三、当前模型家族怎么选

模型名	上下文	适合任务	注意
`kimi-k3`	1M	复杂推理、长文档、Agent、知识工作	默认 `reasoning_effort` 为 `max`
`kimi-k2.7-code`	256K	代码生成、仓库问答、编码 Agent	思考常开，不支持 `reasoning_effort`
`kimi-k2.7-code-highspeed`	256K	低延迟补全、交互式编码	同模型高速版，输出更快
`kimi-k2.6`	256K	通用对话、抽取、多模态	支持思考与非思考模式

如果拿不准，先选 kimi-k3；简单分类、固定格式抽取用 kimi-k2.6 往往更合适；代码任务再考虑 K2.7 Code 系列。

参数上最容易踩坑的是采样参数。当前模型温度是固定的：K3 和 K2.7 Code 为 1.0，K2.6 在思考模式为 1.0、非思考模式为 0.6。不要显式传 temperature，传非固定值会报错；top_p 也固定为 0.95，不要自行调整。

四、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 先看错误消息里是否提到上下文或输出上限。部分集成对模型名有额外要求，例如 Claude Code 可能需要 kimi-k3[1m]，以对应集成文档为准。

五、Python SDK 与流式输出

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 的数据；连接中断时这一块可能收不到，生产环境要在服务端另行记账。

多轮对话和工具调用要注意思考内容。K3 的思考结果在 reasoning_content 里，K2.x 也有类似字段，回传 assistant 消息时应原样带回。K3 用顶层 reasoning_effort 控制强度；K2.x 的 thinking 参数要经 extra_body 传入，两者不要同时发送。

六、从 moonshot-v1 迁移

旧型号已经停用，继续调用会返回 model_not_found。当前替代关系如下，具体以官方模型列表为准。

旧模型	建议替代	迁移注意
`moonshot-v1-8k/32k/128k/auto`	`kimi-k2.6` 或 `kimi-k3`	不再按 8K/32K/128K 命名区分
`moonshot-v1-*-vision-preview`	`kimi-k3` 或 `kimi-k2.6`	图片改用 `image_url` 内容块
`kimi-k2` 系列	`kimi-k3`	2026-05-25 停用
`kimi-k2.5`	`kimi-k3`	2026-08-31 停用
`kimi-latest`	`kimi-k3`	2026-01-28 停用

迁移步骤：

全局搜索代码和配置里的旧模型名、base_url，列出替换表。
修改 base_url，确认中国站或国际站；跨站则同时更换 Key。
替换模型名，默认用 kimi-k3，成本敏感的短任务可评估 kimi-k2.6。
把 max_tokens 改成 max_completion_tokens。K3 默认 131072，输出上限为 1048576 减去输入长度；K2 系列上限约为 256K 减去输入长度。
删除自定义 temperature、top_p，改用模型固定值。
把旧版 thinking 设置改为 K3 的 reasoning_effort，K2.x 则通过 extra_body 传 thinking。
多模态内容改成 text、image_url、video_url 内容块。
流式请求补上 stream_options={"include_usage": True}。
用同一批真实任务跑回归，记录质量、延迟、finish_reason 和用量，灰度发布并保留回滚开关。

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

七、上线前的验证清单

用同一把 Key 调 GET /v1/models，确认目标模型在返回列表里。
发一条最小非流式请求，确认 200 和内容正确。
发一条流式请求，确认能收到增量内容和最后的 usage。
检查 finish_reason：正常结束是 stop，达到输出上限是 length。
用固定评测集对比迁移前后的质量、延迟和 Token 消耗。
验证 429 退避、超时和重试上限，确认不会因 SDK 自动重试放大并发。
在日志里记录请求时间、模型名、状态码和用量，便于排障与对账。

八、常见报错对照

401 invalid_authentication_error：Key 无效、已删除，或中国站与国际站 Key 混用。开放平台 Key 与 Kimi Code 的 Key 也不通用。
403 permission_denied_error：IP 白名单未包含当前出口 IP，或项目权限不足。
404 model_not_found：base_url 未指向 Moonshot、模型名写错、调用了已停用模型，或路径少了 /v1。
400 invalid_request_error：输入加输出上限超过上下文，或传了模型不支持的参数，例如自定义温度。
400 content_filter：输入或输出触发内容安全策略，需要调整提示词或素材。
429：engine_overloaded_error 是服务端繁忙；rate_limit_reached_error 是组织限流；exceeded_current_quota_error 多为余额不足。
504 或连接超时：非流式长请求等待过久，长文生成和 Agent 任务尽量用流式。

OpenAI SDK 默认会对失败请求重试两次，一次调用可能产生三次请求。低配额账号遇到 429 时，先把重试次数和并发降下来，再排查配额。

常见问题

moonshot-v1 还能继续用吗？

不能。moonshot-v1 全系列已在 2026 年 8 月 31 日停用，调用会返回 model_not_found。请迁移到 kimi-k3 或 kimi-k2.6。

Base URL 应该填到哪一层？

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

为什么传 temperature 会报错？

当前模型温度固定，K3 和 K2.7 Code 为 1.0，K2.6 随思考模式固定。不要传自定义值，top_p 也固定为 0.95。

中国站 Key 能调用国际站吗？

不能。两站的账号、余额和 Key 按区域隔离，混用通常返回 401。切换站点时要把 Key、Base URL 和模型名一起改。

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

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

下一步

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