Kimi K3 API 完整指南：2.8T 推理模型、定价与 OpenAI 兼容集成（2026）

Kimi K3 是 Moonshot AI 的旗舰模型——2.8 万亿参数，100 万 token 上下文窗口，原生视觉理解，始终开启推理。它于 2026 年 7 月 16 日发布，API 已在 https://api.moonshot.ai/v1 上线。如果你用过 OpenAI SDK，3 分钟内就能完成首次 K3 调用：将 base_url 指向 Moonshot 端点，模型 ID 换成 kimi-k3，现有代码直接可用。

我们写这篇指南，是因为 K3 引入了与 K2 系列不同的 API 接口。thinking 参数消失了，reasoning_effort 取而代之。tool_choice: "required" 现已支持。上下文窗口从 256K 跳到 1M token。定价模型——$3/M 输入、$15/M 输出，全上下文长度统一价格——改变了长上下文工作负载的成本计算。这些差异单独看很小，但如果你从 K2 迁移，很容易踩坑。

来源：Kimi K3 快速入门，检索于 2026-07-18；Kimi K3 定价，检索于 2026-07-18；模型参数参考，检索于 2026-07-18。

OpenAI 兼容指供应商提供一个 chat-completions 接口，其请求与响应结构与 OpenAI API 契约足够接近——只需替换三个值（API key、base URL、模型名），原来的 OpenAI SDK 调用即可直接工作。最小实践面是POST /v1/chat/completions 带 messages、model， 并返回 OpenAI 形式的流式响应。

3 分钟快速上手

第 1 步：注册账号。 前往 platform.kimi.ai，支持邮箱和手机号注册。

第 2 步：获取 API Key。 进入 控制台 → API Keys 页面，创建新密钥。立即复制——密钥只显示一次。

第 3 步：发起首次调用。 安装 OpenAI Python SDK：

pip install --upgrade 'openai>=1.0'

运行：

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_MOONSHOT_KEY",
    base_url="https://api.moonshot.ai/v1",
)

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "用一句话介绍 Kimi K3。"}],
)

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

就这么简单。Kimi API 实现了 OpenAI Chat Completions 规范——任何支持 OpenAI 格式的工具、SDK 或代码，换个 base_url 和 API key 就能用。

来源：Kimi K3 快速入门，检索于 2026-07-18。

Kimi K3 一览：与 K2 的关键差异

K3 不只是更大的 K2，架构、API 接口和定价都变了：

从 K2 迁移需要注意：

1. thinking → reasoning_effort：K3 不接受 K2 风格的 thinking 参数。改用 reasoning_effort: "max"（或省略——max 是默认值）。
2. 参数已固定：temperature、top_p、n、presence_penalty、frequency_penalty 在 K3 上不可修改，传入非默认值会报错。
3. 新增 tool_choice: "required"：K3 支持强制工具调用，K2 系列不支持。

来源：模型参数参考，检索于 2026-07-18。

推理控制：reasoning_effort

K3 始终进行推理。每次请求都会在响应中生成 reasoning_content（思考过程）和最终 content。通过顶层 reasoning_effort 字段控制推理级别：

response = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="max",
    messages=[
        {"role": "user", "content": "证明根号 2 是无理数。"}
    ],
)

# 访问推理过程
message = response.choices[0].message
if hasattr(message, "reasoning_content"):
    print("推理过程:", message.reasoning_content)
print("回答:", message.content)

当前 "max" 是唯一支持的值，更多级别即将推出。该字段与 OpenAI 的 reasoning_effort 兼容——如果你的代码已经设置了它，无需重命名。

缓存行为：切换 reasoning_effort 级别（更多级别可用后）可能使前缀缓存失效。建议在对话开始时确定 effort 级别，避免中途切换。

来源：Thinking Effort，检索于 2026-07-18。

定价

K3 在整个 1M token 上下文窗口内采用统一定价——不按上下文长度分级：

与其他前沿模型对比：

K3 缓存命中价 $0.30/M 输入使得长上下文多轮对话的实际成本远低于缓存未命中价格。Moonshot 的自动上下文缓存无需显式配置即可生效。

来源：Kimi K3 定价，检索于 2026-07-18；Artificial Analysis — Kimi K3，检索于 2026-07-18。

工具调用与动态工具加载

K3 在工具调用方面相比 K2 引入了两项改进：

tool_choice: "required"

强制模型每轮都调用工具——适用于检索增强工作流，确保第一步一定是搜索：

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "查找 Claude Opus 4.8 的最新定价"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "web_search",
            "description": "搜索网络获取最新信息",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "搜索查询"}
                },
                "required": ["query"]
            }
        }
    }],
    tool_choice="required",
)

动态工具加载

K3 支持通过 system 消息中的 tools 字段在对话中动态注入工具定义，而不必在开始时声明所有工具。推荐模式：

1. 在 tools 中只声明一个 search_tools 函数
2. 首轮设置 tool_choice: "required" 强制检索
3. 根据检索结果通过 system 消息注入匹配的工具定义
4. 后续请求切回 tool_choice: "auto"

即使有数百个可用工具，每次请求的 token 消耗也保持在最低水平。

来源：K3 工具调用最佳实践，检索于 2026-07-18。

视觉输入

K3 原生处理图片和视频。在 content 字段中以对象数组形式传递视觉内容：

图片输入

import base64
from pathlib import Path

image_data = base64.b64encode(Path("screenshot.png").read_bytes()).decode()

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image_url",
                "image_url": {"url": f"data:image/png;base64,{image_data}"},
            },
            {"type": "text", "text": "描述这张截图中的内容。"},
        ],
    }],
)

视频输入

先上传视频文件，然后引用：

video = client.files.create(file=Path("demo.mp4"), purpose="video")

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{
        "role": "user",
        "content": [
            {"type": "video_url", "video_url": {"url": f"ms://{video.id}"}},
            {"type": "text", "text": "总结这个视频的内容。"},
        ],
    }],
)

# 清理
client.files.delete(video.id)

来源：Kimi K3 快速入门——视觉输入，检索于 2026-07-18。

流式输出

K3 将 reasoning_content 和 content 作为独立的 delta 字段进行流式输出：

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "解释天空为什么是蓝色的。"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    reasoning = getattr(delta, "reasoning_content", None)
    if reasoning:
        print(f"[思考] {reasoning}", end="", flush=True)
    if delta.content:
        print(delta.content, end="", flush=True)

多轮对话中，需要将完整的 assistant 消息（包括 reasoning_content 和 tool_calls）传回下一次请求的 messages 数组。

来源：Kimi K3 快速入门——流式输出，检索于 2026-07-18。

结构化输出与 JSON Mode

K3 通过 response_format 支持严格 JSON Schema 输出：

import json

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "小林今年 28 岁。提取姓名和年龄。"}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                },
                "required": ["name", "age"],
                "additionalProperties": False,
            },
        },
    },
)

person = json.loads(response.choices[0].message.content or "{}")
print(person)  # {"name": "小林", "age": 28}

结构化输出只解析 message.content——reasoning_content 是非结构化的思考过程，不应进行 JSON 解析。

来源：结构化输出，检索于 2026-07-18。

常见错误与解决方案

生产环境清单

上线 K3 前，请确认：

• API key 安全存储——不要硬编码，使用环境变量或密钥管理器
• 限流错误处理——对 429 响应实施指数退避
• 流式消费端处理两个 delta——reasoning_content 和 content 是独立字段
• 多轮消息格式——传回完整的 assistant 消息（含 reasoning_content）
• 移除固定参数——不要传 temperature、top_p、n、presence_penalty、frequency_penalty
• thinking 替换为 reasoning_effort——K2 风格的 thinking 参数在 K3 上会报错
• token 预算管理——K3 输出价 $15/M 是 K2.6 输出价的 1.5 倍，注意监控输出 token 用量
• 上下文缓存策略——Moonshot 自动缓存可将输入成本降低 90%；构建对话以最大化前缀复用
• 容灾配置——设置 K2.6 或其他 provider 作为后备，应对 K3 早期上线的可用性波动

TheRouter 集成

Moonshot 是 TheRouter 的已验证 provider。现有 K2 模型（kimi-k2.6、kimi-k2.7-code）已可通过我们的 OpenAI 兼容网关路由。

Kimi K3 尚未加入 TheRouter 模型注册表。 一旦 moonshot/kimi-k3 添加到 models-data.ts，你就能通过 TheRouter 路由 K3 请求，并自动在 K2.6 或其他 provider 间进行降级：

# K3 加入 TheRouter 后的配置示例
client = OpenAI(
    api_key="YOUR_THEROUTER_KEY",
    base_url="https://api.therouter.ai/v1",
)

response = client.chat.completions.create(
    model="moonshot/kimi-k3",  # 支持后将通过 TheRouter 路由
    messages=[{"role": "user", "content": "来自 TheRouter 的问候！"}],
)

目前，你可以直接通过 Moonshot API 端点 https://api.moonshot.ai/v1 调用 K3，或通过灵积（阿里云百炼）访问，DashScope 上的模型 ID 为 kimi/kimi-k3。

关于容灾路由模式——例如 K3 到 DeepSeek V4 或 Claude 的降级——请参阅我们的 LLM API 容灾路由指南。

来源：TheRouter Moonshot Provider，检索于 2026-07-18；灵积新上线模型，检索于 2026-07-18。

延伸阅读

• Kimi K3 vs Kimi K2：升级对比——两代模型的详细对比分析
• Kimi K2 API 集成指南——K2 专用文档
• 2026 编程 Agent 模型路由对比——K3 与 Claude Opus 4.8、DeepSeek V4、GLM-5.2 在编程任务上的对比
• 2026 最佳推理模型 API 对比——跨 provider 推理模型对比

---

最后更新：2026-07-18。Kimi K3 API 已上线，完整模型权重计划于 2026 年 7 月 27 日发布。TheRouter 对 K3 的路由支持待上线——请查看 /providers/moonshot/ 获取最新状态。