Kimi K3 API 怎么调用？Python 和 cURL 快速上手教程

开发者刚接触 Kimi K3 时，最迫切的需求是跑通第一个 API 请求。但在实际操作中，很多人会卡在模型 ID 的选择上，分不清开放平台的 kimi-k3 与 Kimi Code 的 k3 有什么区别，也不清楚思考模式为什么无法关闭。本篇指南基于 2026 年 7 月发布的 Kimi K3，提供从零开始的 Python 和 cURL 调用步骤，覆盖密钥获取、基础请求、流式输出和结构化输出。你将直接获得可复制的代码示例，并了解新用户赠券不可用等限制，避免在调用时报错或产生意外扣费。

Kimi K3 的模型 ID 到底是什么？（区分 API 与 Kimi Code）

在开始写代码之前，必须先理清最容易导致调用失败的模型 ID 问题。很多开发者在使用 Kimi K3 时，会直接把模型 ID 填写错误，导致接口返回模型不存在的报错。

在 Moonshot 的生态中，Kimi K3 存在两个极易混淆的模型 ID 标识，具体取决于你使用的调用方式：

1. 开放平台 API 调用：当你在自己的后端服务或应用中，通过 OpenAI SDK 或直接使用 cURL 请求 Moonshot 开放平台接口时，model 参数必须填写为 kimi-k3。这是标准的 API 调用入口。
2. Kimi Code CLI 调用：如果你使用的是官方提供的命令行编程工具 Kimi Code CLI，在配置该工具的模型参数时，Model ID 应填写为 k3。

需要特别警告的是，切勿在开放平台 API 调用时使用 kimi-for-coding 这个 ID。kimi-for-coding 是 Kimi K2.7 Code 的专属模型 ID，它的能力范围、上下文窗口以及 API 定价均与 Kimi K3 不同。如果你在代码中填入了 kimi-for-coding，实际调用的并不是 K3 旗舰模型，且可能产生不符合预期的结果。

总结来说，写 Python 或 cURL 代码时认准 kimi-k3，配置 Kimi Code CLI 时认准 k3，彻底避开 kimi-for-coding。

调用 Kimi K3 前，账户需要满足什么条件？

跑通第一个请求的前提是拥有合法的 API 密钥和符合规则的账户状态。Kimi K3 作为旗舰模型，在账户权限上有明确的限制。

首先，你需要前往 Moonshot 开放平台控制台创建 API 密钥。创建密钥后，请妥善保管，不要硬编码在客户端代码中。

其次，Kimi K3 并不对所有未付费账户开放。根据官方说明，调用 Kimi K3 需要账户完成充值解锁。这意味着你必须使用真实的充值余额来支付 K3 的调用费用。

这里有一个非常关键的限制：新用户注册认证时平台通常会赠送 15 元代金券，但这笔赠券不可用于 Kimi K3。如果你账户中只有赠券余额，调用 K3 接口时会直接报错余额不足。因此，在尝试运行下文的代码示例前，请确保账户已充值并拥有可用余额。

最后，关于本地部署的问题。基于 2026 年 7 月发布的 Kimi K3，当前阶段仅支持通过 API 进行调用，官方尚未开放完整的模型权重。因此，本篇教程不涉及任何本地部署或微调的步骤，请勿尝试在开源模型框架中加载所谓的 K3 权重文件。

Python 和 cURL 怎么发起基础请求？

理清了模型 ID 和账户限制后，我们可以开始编写第一个基础请求。Kimi K3 的 API 入口地址（Base URL）为 https://api.moonshot.cn/v1，兼容 OpenAI 的接口规范，因此你可以直接使用 OpenAI 官方的 SDK 来调用 Kimi K3。

在编写请求时，有一个重要的参数设置原则：Kimi K3 对部分生成参数进行了固定。temperature、top_p、n、presence_penalty、frequency_penalty 这些参数在 K3 中为固定值，官方建议不要在请求体中显式传入这些参数，以免干扰模型的原生表现。

以下是使用 Python 和 OpenAI SDK 发起基础 chat completions 请求的代码示例：

from openai import OpenAI

client = OpenAI(
    api_key="你的_MOONSHOT_API_KEY",
    base_url="https://api.moonshot.cn/v1",
)

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "用一句话解释什么是 API"}
    ],
)

print(response.choices[0].message.content)

在这段代码中，base_url 指向了 Moonshot 的接口，model 严格设置为 kimi-k3。由于没有传入 temperature 等参数，模型将使用默认的固定配置。

如果你更习惯使用命令行工具或需要在 Shell 脚本中快速测试，可以使用 cURL 发起同样的请求：

curl -X POST https://api.moonshot.cn/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 你的_MOONSHOT_API_KEY" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "用一句话解释什么是 API"}
    ]
  }'

执行上述 cURL 命令后，终端会返回一个 JSON 字符串，其中 choices[0].message.content 包含了模型的最终回答。请注意，在非流式模式下，K3 返回的 JSON 结构中不仅包含 content，还会包含思考过程的字段，这一点我们在下一节详细说明。

Kimi K3 的流式输出怎么写？（区分思考过程与最终答案）

Kimi K3 是一个原生支持思考模式的推理模型。这意味着它在给出最终答案之前，会先进行一段内部的思维链推理。与普通模型不同，K3 的思考模式始终开启，无法通过参数关闭。

在流式输出（Streaming）场景下，K3 返回的数据块结构与普通模型有显著区别。你需要分别处理两个不同的字段：

1. reasoning_content：这是模型的思考过程。在流式输出的早期 chunk 中，这个字段会不断填充模型推理的中间步骤。
2. content：这是模型的最终答案。当思考过程结束后，后续的 chunk 会开始填充 content 字段。

如果你只读取 content，在思考阶段你的程序将收不到任何输出，可能会导致程序误判为超时或卡死。以下是正确的 Python 流式输出代码写法：

from openai import OpenAI

client = OpenAI(
    api_key="你的_MOONSHOT_API_KEY",
    base_url="https://api.moonshot.cn/v1",
)

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "写一个快速排序的 Python 代码并解释逻辑"}
    ],
    stream=True
)

for chunk in stream:
    if not chunk.choices:
        continue
    
    delta = chunk.choices[0].delta
    
    # 读取并处理思考过程
    if hasattr(delta, "reasoning_content") and delta.reasoning_content is not None:
        print("[思考中]:", delta.reasoning_content, end="", flush=True)
    
    # 读取并处理最终答案
    if delta.content is not None:
        print("[最终答案]:", delta.content, end="", flush=True)

这段代码展示了如何在循环中判断 delta 对象。当收到 reasoning_content 时，你可以选择在前端 UI 上展示为折叠的思考过程，或者直接在后台忽略。当收到 content 时，再将其作为正式结果输出给最终用户。

如何调整思考力度？（reasoning_effort 参数说明）

虽然 K3 的思考模式无法关闭，但如果你觉得默认的思考过程太长，消耗了过多的 Token 和时间，可以通过 reasoning_effort 参数来调整思考力度。

reasoning_effort 是一个顶层参数，支持三个取值：

1. low：低思考力度。模型会快速给出答案，思考过程最短，适合简单问答或对延迟敏感的场景。
2. high：高思考力度。模型会进行较深度的推理，适合大部分需要逻辑分析的复杂任务。
3. max：最大思考力度。这是 K3 的默认值。模型会穷尽所有的推理路径，适合复杂的数学证明、长代码重构或极度困难的逻辑题。

以下是设置 reasoning_effort 为 low 的代码示例：

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "今天天气怎么样"}
    ],
    reasoning_effort="low"
)

在实际开发中，可以根据任务类型动态设置该参数。对于简单的信息提取或翻译，使用 low 可以降低 Token 消耗和延迟；对于需要严谨逻辑的 Agent 任务，保持默认的 max 或手动设为 high。

怎么用 JSON Schema strict 模式做结构化输出？

在构建自动化工作流时，通常需要模型返回严格的 JSON 格式数据，以便后端程序直接解析。Kimi K3 支持通过 response_format 参数配合 JSON Schema 的 strict 模式来实现结构化输出。

在 strict 模式下，模型会严格按照你提供的 Schema 结构生成 JSON，不会随意添加额外的字段或注释。需要注意的是，即使启用了结构化输出，K3 依然会先进行思考，因此你只需要解析最终 content 字段中的 JSON 字符串即可。

以下是要求模型返回包含姓名和年龄的 JSON 结构的代码示例：

import json
from openai import OpenAI

client = OpenAI(
    api_key="你的_MOONSHOT_API_KEY",
    base_url="https://api.moonshot.cn/v1",
)

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": "你是信息提取助手，请从用户输入中提取姓名和年龄。"},
        {"role": "user", "content": "张三今年 28 岁，是一名软件工程师。"}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person_info",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"}
                },
                "required": ["name", "age"],
                "additionalProperties": False
            }
        }
    }
)

# 最终答案在 content 字段中，需要用 json.loads 解析
result = json.loads(response.choices[0].message.content)
print(f"姓名: {result['name']}, 年龄: {result['age']}")

在这个示例中，strict: True 是关键配置，它强制模型必须遵循 schema 中定义的字段和类型。additionalProperties: False 则禁止模型生成未在 properties 中定义的额外字段。解析时，直接对 response.choices[0].message.content 调用 json.loads 即可得到结构化字典。

多轮对话为什么会报错？（上下文回传避坑指南）

在实现多轮对话时，Kimi K3 有一个强制性的上下文回传要求，这也是开发者最容易踩坑的地方。

通常在普通的 API 多轮对话中，我们只需要将历史消息的 role 和 content 拼接到 messages 数组中即可。但在 K3 中，由于思考模式的存在，API 返回的 assistant message 包含了完整的 reasoning_content（思考过程）和可能的 tool_calls（工具调用记录）。

官方明确规定：在多轮对话中，必须将 API 返回的完整 assistant message 原样回传给接口，不可只保留 content 字段。

如果你在构建历史消息时，手动剥离了 reasoning_content，只把 content 放入下一轮请求的 messages 中，接口会报错或导致模型上下文断裂，无法正确理解之前的推理逻辑。

正确的做法是直接使用上一轮响应中的 message 对象。示例代码如下：

# 第一轮请求
response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "123乘以456等于多少"}
    ],
)

# 获取完整的 assistant message（包含 reasoning_content 和 content）
assistant_message = response.choices[0].message

# 第二轮请求，必须将完整的 assistant_message 追加到历史中
second_response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "123乘以456等于多少"},
        assistant_message,  # 直接传入完整的 message 对象
        {"role": "user", "content": "把结果加上1000"}
    ],
)

如果你使用的是自定义的字典结构而非 SDK 自带的对象，请确保在保存历史消息时，保留了 reasoning_content 字段，并在下一次请求时一并带上。

Kimi K3 定价与后续权重开放计划

关于调用成本，Kimi K3 的输入与输出分别按统一单价计费，输入部分会区分缓存命中与未命中，但不按上下文长度进行分段计费。具体的计费金额请查阅 Moonshot 开放平台的官方定价页，本篇教程不列举具体数字以避免因价格调整导致信息过时。

需要再次提醒的是，新用户赠券不可用于抵扣 K3 的调用费用，请确保账户有充足的充值余额。

关于模型权重的开放计划，基于 2026 年 7 月发布的 Kimi K3，当前仅支持 API 调用，官方尚未开放完整的模型权重供本地部署或微调。如果你的业务场景强依赖本地私有化部署，目前 K3 并不满足这一条件，请关注官方后续的权重发布公告。

常见问题排查（FAQ）

为什么用新用户送的 15 元代金券调用 K3 会报错余额不足？
官方明确规定，新用户注册认证赠送的 15 元代金券不可用于 Kimi K3。K3 作为旗舰模型需要账户完成充值解锁，调用费用将从充值余额中扣除，请先在开放平台控制台进行充值。

怎么关掉 K3 的思维链？
关不掉。Kimi K3 始终开启思考模式，这是其核心机制之一。如果你觉得思维链过长导致延迟增加，可以通过设置 reasoning_effort 参数为 low 来降低思考力度，但无法彻底关闭。

调用 API 时 model 参数填 k3 报错怎么办？
在通过 Python SDK 或 cURL 直接调用开放平台 API 时，模型 ID 必须填写为 kimi-k3。k3 是 Kimi Code CLI 工具专用的配置 ID，直接填入 API 请求会导致模型不存在的报错。

K3 支持本地部署或微调吗？
基于 2026 年 7 月发布的版本，K3 当前不支持本地部署或微调，官方尚未开放模型权重。目前只能通过 Moonshot 开放平台的 API 接口进行调用。

多轮对话时只传了 content 为什么会报错？
K3 的多轮对话要求必须原样回传完整的 assistant message，其中必须包含 reasoning_content 字段。如果只保留 content，模型会因丢失上下文推理逻辑而报错或表现异常。请直接使用上一轮响应返回的完整 message 对象。

K3 的 max_completion_tokens 默认值是多少？
根据官方文档，max_completion_tokens 参数的默认值为 131072，最大可以设置为 1048576。如果你需要生成长文本，可以显式传入更大的值。