Kimi K3通过Moonshot AI的与OpenAI兼容的聊天完成API提供，模型ID为kimi-k3。该API支持始终在线推理、流式传输、图像、上传视频、严格的JSON Schema、自定义工具、动态工具加载和100万标记的上下文窗口。
兼容性并不意味着完全相同的行为。K3具有固定的采样值，要求在后续工具和对话回合中提供完整的助手状态，并且将推理与最终内容分开处理。本指南重点关注这些细节。
可用状态与价格更新于 2026 年 7 月 22 日。 Kimi K3 已在 Poyo.ai 上线，模型 ID 为
kimi-k3，支持 OpenAI 兼容的 Chat Completions API。价格为每百万输入 Token $2.28、每百万输出 Token $11.40，比官方价格便宜 24%。
要求
你需要：
- Python 3.9或更新版本；
openaiPython包版本1.0或更新版本；- 一个存放在版本控制外的Moonshot API密钥；
- 基础 URL
https://api.moonshot.ai/v1; - 模型ID
kimi-k3。
安装SDK：
python -m pip install --upgrade "openai>=1.0"
在你的Shell中设置密钥：
export MOONSHOT_API_KEY="你的密钥"
在PowerShell中：
$env:MOONSHOT_API_KEY="你的密钥"
请勿在代码示例、客户端捆绑、日志或代码库中放置生产密钥。
发出你的第一个Kimi K3请求
Python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["MOONSHOT_API_KEY"],
base_url="https://api.moonshot.ai/v1",
)
response = client.chat.completions.create(
model="kimi-k3",
messages=[
{"role": "user", "content": "审查这个迁移计划并列出其三个最高风险。"}
],
)
print(response.choices[0].message.content)
cURL
curl https://api.moonshot.ai/v1/chat/completions \
-H "Authorization: Bearer $MOONSHOT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kimi-k3",
"messages": [
{"role": "user", "content": "用通俗语言解释Kimi Delta Attention。"}
]
}'
配置推理努力
K3始终处于思考模式。通过顶层reasoning_effort字段配置其努力程度：
response = client.chat.completions.create(
model="kimi-k3",
reasoning_effort="high",
messages=[
{"role": "user", "content": "找出这个分布式锁设计中的缺陷。"}
],
)
支持的值为：
| 值 | 用于 |
|---|---|
low | 较容易的任务，在延迟和输出上更重要 |
high | 难度较大的编码、分析和工具规划 |
max | 最困难的任务和基准风格评估 |
文档中默认值为max。不要假设这是生产设置中最便宜的。评估每种努力的成功率、延迟和生成的标记。
流式推理和最终内容
流式响应通过不同的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:
# 根据你的产品和提供者政策存储或处理。
pass
if delta.content:
print(delta.content, end="", flush=True)
将用户可见的最终内容与内部处理分开。不要解析reasoning_content中的结构化输出。
向Kimi K3发送图像
K3视觉消息使用内容对象数组。此流程不支持公共图像URL；将本地图像编码为base64格式。
import base64
from pathlib import Path
image_data = base64.b64encode(Path("interface.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": "识别此界面中的三个最大可访问性问题。",
},
],
}
],
)
在编码用户上传之前验证文件类型和大小。避免记录base64有效负载。
向Kimi K3发送视频
通过文件API上传视频，使用ms://方案引用返回的ID，并在不再需要时删除文件。
from pathlib import Path
video = client.files.create(file=Path("demo.mp4"), purpose="video")
try:
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": "总结工作流程并识别失败步骤。"},
],
}
],
)
finally:
client.files.delete(video.id)
返回严格的JSON Schema输出
在下游代码需要可预测形状时使用strict: true。
import json
response = client.chat.completions.create(
model="kimi-k3",
messages=[
{"role": "user", "content": "提取此事件备注中的风险、严重性和所有者。"}
],
response_format={
"type": "json_schema",
"json_schema": {
"name": "incident_risk",
"strict": True,
"schema": {
"type": "object",
"properties": {
"risk": {"type": "string"},
"severity": {"type": "string", "enum": ["low", "medium", "high"]},
"owner": {"type": ["string", "null"]},
},
"required": ["risk", "severity", "owner"],
"additionalProperties": False,
},
},
},
)
result = json.loads(response.choices[0].message.content or "{}")
只解析最终的message.content，然后在应用代码中再次验证。
调用自定义工具
第一次响应可以请求一个或多个工具。执行每个允许的调用，附加完整的助手消息，然后为每个tool_call_id附上一个匹配的工具结果。
import json
tools = [
{
"type": "function",
"function": {
"name": "get_build_status",
"description": "返回允许项目的当前构建状态。",
"parameters": {
"type": "object",
"properties": {"project": {"type": "string"}},
"required": ["project"],
"additionalProperties": False,
},
},
}
]
messages = [{"role": "user", "content": "检查Web构建并总结任何失败。"}]
first = client.chat.completions.create(
model="kimi-k3",
messages=messages,
tools=tools,
tool_choice="required",
)
assistant_message = first.choices[0].message
messages.append(assistant_message)
for call in assistant_message.tool_calls or []:
arguments = json.loads(call.function.arguments)
# 执行真实工具之前，请先授权和验证。
tool_result = {"project": arguments["project"], "status": "passed"}
messages.append(
{
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(tool_result),
}
)
final = client.chat.completions.create(
model="kimi-k3",
messages=messages,
tools=tools,
)
切勿在没有权限边界、输入验证、范围环境和审计跟踪的情况下执行任意模型生成的shell命令。
动态加载工具
K3支持在工具可用时将完整的工具定义放在system消息中。请在后续历史中保留该消息，因为服务器不会为你保留它。
动态加载有助于大型代理系统避免在每次回合中发送每个工具模式。它还创建新的状态管理要求：模型必须在解释后续工具结果时看到确切的声明。
使用100万标记的上下文窗口
大型上下文在需要一起推理远程证据时最为有价值。请谨慎使用：
- 在开始时保持稳定的代码库或文档语料库。
- 附加问题和结果，而不是重写前缀。
- 分别跟踪缓存和未缓存的输入。
- 在不需要完整语料库时检索较小的子集。
- 建立源标识符，以便最终答案能够被验证。
- 仅在你的客户端保留K3所需的所有状态时进行压缩。
自动缓存没有缓存ID或普通TTL参数。稳定的前缀为服务提供了最佳的缓存命中机会。
保持完整的多轮状态
这是最重要的K3特定集成规则。
在继续对话或返回工具结果时，附加API返回的完整助手消息。不要仅保留content。Moonshot警告说，K3是在保留思考历史的状态下训练的，如果中断了所需的历史或在会话中切换到K3，可能会变得不稳定。
安全地存储对话状态，应用保留限制，并避免向不应查看的用户泄露隐藏状态。
Kimi K3 API的重要限制
- K3始终启用思考。
reasoning_effort支持low、high和max。max_completion_tokens默认为131,072，可以设置到1,048,576。temperature=1.0、top_p=0.95、n=1、presence_penalty=0和frequency_penalty=0是固定的；可以省略。- 视觉消息不支持公共图像URL。
- 多轮和工具请求必须保留完整的助手消息。
- Moonshot表示其网页搜索工具正在更新，目前不建议在生产中使用。
生产清单
- 将API密钥保留在服务器端。
- 添加请求超时和有限重试。
- 验证工具参数并授权每个操作。
- 限制工具回合和完成长度。
- 保留完整的K3助手状态。
- 生成后验证严格的JSON。
- 记录输入、缓存输入、输出、延迟和错误。
- 避免在K3会话中间更换模型。
- 添加明确的行为边界以减少过度主动性。
- 测试损坏的工具、部分响应和长历史。
在选择上下文和输出限制之前，请阅读 Kimi K3 API定价。请关注 Kimi K3模型页面以获取Poyo.ai的可用性。
常见问题解答
Kimi K3 API与OpenAI兼容吗？
是的。Moonshot提供与OpenAI兼容的聊天完成端点。K3特定的状态、推理、采样和媒体规则仍然适用。
Kimi K3模型ID是什么？
官方Moonshot API模型ID是kimi-k3。
Kimi K3支持函数调用吗？
是的。它支持自定义工具、必需的工具选择、匹配工具结果和动态工具加载。
Kimi K3可以处理视频吗？
是的。通过文件API上传视频，并在视频内容对象中引用其ms://文件ID。
如何使用100万上下文窗口？
通过标准模型请求发送所需的消息和内容，保持稳定前缀不变以进行自动缓存，并设置有限的完成限制。