Moonshot AI 开放平台免费额度申请与 Kimi API 接入指南

拿到密钥后即可通过 OpenAI 兼容接口调用 Kimi 系列模型。接口地址（base_url）形态为 https://api.moonshot.cn/v1，即在此基础上拼接 /chat/completions。具体可用的模型名请在控制台的「模型」或文档页查看当期列表，常见的有 moonshot-v1-8k、moonshot-v1-32k、moonshot-v1-128k 等按上下文长度区分的版本，以及后续新增的多模态与长上下文型号，名称以控制台实际显示为准。

先把密钥写进环境变量，避免硬编码在源码里：

export MOONSHOT_API_KEY="sk-你的密钥"

下面是一次最简对话补全调用，用 curl 直接验证密钥是否可用：

curl https://api.moonshot.cn/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -d '{
    "model": "moonshot-v1-8k",
    "messages": [
      {"role": "system", "content": "你是一个简洁的中文助手"},
      {"role": "user", "content": "用一句话解释什么是长上下文"}
    ],
    "temperature": 0.3,
    "max_tokens": 256,
    "stream": false
  }'

关键参数说明：model 决定上下文窗口与价格档位；messages 是对话数组，system 用于设定角色，user 与 assistant 交替构成多轮历史；temperature 控制随机性，取值 0 到 1 之间，做抽取类任务建议设低；max_tokens 限制回复长度，需小于模型的最大输出上限；stream 设为 true 时以流式返回，适合网页打字机效果。长上下文模型按输入加输出的总 token 计费，历史对话越长消耗越快。

如果用 Python，可直接沿用 OpenAI SDK，只改 base_url：

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的密钥",
    base_url="https://api.moonshot.cn/v1",
)

resp = client.chat.completions.create(
    model="moonshot-v1-8k",
    messages=[{"role": "user", "content": "你好"}],
    max_tokens=128,
)
print(resp.choices[0].message.content)

额度耗尽与限流的典型表现

• 余额不足：返回 402 或提示账户余额不足、额度已用尽。先去控制台余额页核对体验金是否到期，再决定是否充值。
• 鉴权失败：返回 401，多为密钥复制不完整、环境变量未生效或密钥已被删除，重新生成并替换即可。
• 限流：返回 429，说明触发了并发或每分钟请求数限制，需在客户端加指数退避重试，并降低并发。
• 上下文超限：返回 400 并提示 token 超出模型上限，换用更大窗口的模型或裁剪历史消息。
• 参数错误：同样返回 400，检查 JSON 是否合法、引号是否被替换成中文引号。

排查顺序建议：先用 curl 最小请求验证密钥与网络，再看返回码定位是鉴权、余额还是限流问题，最后才回头检查业务代码里的模型名与参数拼装。