> ## Documentation Index
> Fetch the complete documentation index at: https://platform.kimi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Kimi K3
## Kimi K3 模型介绍
Kimi K3 是 Kimi 迄今能力最强的模型，拥有 2.8 万亿参数。它基于 Kimi 混合线性注意力机制（Kimi Delta Attention）和注意力残差（Attention Residuals）技术构建，原生支持视觉理解，并拥有 100 万 token 上下文窗口，面向软件工程、知识工作和深度推理等前沿智能场景而设计。
## 立即开始
* [Playground](https://platform.kimi.com/playground)
* [申请 API Key](https://platform.kimi.com/console/api-keys)
以下示例需要 Python 3.9+ 和 OpenAI SDK。先安装 SDK，并初始化一次客户端；后续 Python 示例复用 `client`。
```bash theme={null}
python3 -m pip install --upgrade 'openai>=1.0'
```
```python theme={null}
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["MOONSHOT_API_KEY"],
base_url="https://api.moonshot.cn/v1",
)
```
## 基础调用
```python theme={null}
completion = client.chat.completions.create(
model="kimi-k3",
messages=[{"role": "user", "content": "用一句话介绍 Kimi K3。"}],
)
print(completion.choices[0].message.content)
```
```bash theme={null}
curl https://api.moonshot.cn/v1/chat/completions \
--header "Authorization: Bearer $MOONSHOT_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "kimi-k3",
"messages": [{"role": "user", "content": "用一句话介绍 Kimi K3。"}]
}'
```
## 思考力度
K3 始终开启思考模式，并支持通过顶层 `reasoning_effort` 配置思考力度。不要使用 K2.x 的 `thinking` 参数。
思考力度当前仅支持 `max` 档位（默认）；其他档位将在后续上线，敬请期待。用法见 [思考力度](/guide/use-thinking-effort) 。
```python theme={null}
completion = client.chat.completions.create(
model="kimi-k3",
reasoning_effort="max",
messages=[{"role": "user", "content": "证明根号 2 是无理数。"}],
)
print(completion.choices[0].message.content)
```
多轮对话和工具调用时，将 API 返回的完整 assistant message 原样加入下一次请求，不要只保留 `content`。
## 流式输出
流式响应分别提供推理增量 `reasoning_content` 和最终答案增量 `content`。更多细节见 [流式输出](/guide/utilize-the-streaming-output-feature-of-kimi-api) 。
```python theme={null}
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(reasoning, end="", flush=True)
if delta.content:
print(delta.content, end="", flush=True)
```
## 视觉输入
视觉消息的 `content` 必须是对象数组，而不是序列化后的字符串。完整格式与限制见 [视觉输入](/guide/use-kimi-vision-model) 。
```python theme={null}
import base64
from pathlib import Path
image_data: str = base64.b64encode(Path("image.png").read_bytes()).decode()
completion = 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": "描述这张图片。"},
],
}
],
)
print(completion.choices[0].message.content)
```
```python theme={null}
from pathlib import Path
video = client.files.create(file=Path("video.mp4"), purpose="video")
try:
completion = client.chat.completions.create(
model="kimi-k3",
messages=[
{
"role": "user",
"content": [
{
"type": "video_url",
"video_url": {"url": f"ms://{video.id}"},
},
{"type": "text", "text": "概括这个视频。"},
],
}
],
)
print(completion.choices[0].message.content)
finally:
client.files.delete(video.id)
```
## 结构化输出
使用 `json_schema` 和 `strict: true` 约束最终 `message.content`，只解析该字段，不解析 `reasoning_content`。
```python theme={null}
import json
completion = 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: dict[str, object] = json.loads(
completion.choices[0].message.content or "{}"
)
print(person)
```
详见 [结构化输出](/guide/response_format) 。
## Partial Mode
在消息末尾添加 `partial=True` 的 assistant message，让模型从指定文本前缀继续生成。最终展示时需要自行拼接前缀。
```python theme={null}
prefix: str = "结论："
completion = client.chat.completions.create(
model="kimi-k3",
messages=[
{"role": "user", "content": "用一句话说明保持接口兼容的重要性。"},
{"role": "assistant", "content": prefix, "partial": True},
],
)
print(prefix + (completion.choices[0].message.content or ""))
```
详见 [Partial Mode](/guide/use-partial-mode-feature-of-kimi-api) 。
## 自定义工具与 `tool_choice`
首轮用 `tool_choice="required"` 强制至少调用一个工具。执行每个调用后，回传完整 assistant message，并用对应的 `tool_call_id` 逐条追加工具结果。
```python theme={null}
import json
from typing import Any
tools: list[dict[str, Any]] = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询城市天气",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
}
]
messages: list[Any] = [
{"role": "user", "content": "北京今天天气怎么样？"}
]
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 tool_call in assistant_message.tool_calls or []:
arguments: dict[str, str] = json.loads(tool_call.function.arguments)
result: str = json.dumps(
{"city": arguments["city"], "weather": "晴", "temperature_c": 24},
ensure_ascii=False,
)
messages.append(
{"role": "tool", "tool_call_id": tool_call.id, "content": result}
)
final = client.chat.completions.create(
model="kimi-k3",
messages=messages,
tools=tools,
)
print(final.choices[0].message.content)
```
详见 [工具调用约束](/guide/use-tool-choice) 。
## 动态加载工具
把完整工具定义放进一条不含 `content` 的 `system` message，即可从该位置起加载工具。
```python theme={null}
from typing import Any
dynamic_messages: list[dict[str, Any]] = [
{"role": "user", "content": "计算 23 乘以 47。"},
{
"role": "system",
"tools": [
{
"type": "function",
"function": {
"name": "calculate",
"description": "计算一个算术表达式",
"parameters": {
"type": "object",
"properties": {
"expression": {
"type": "string",
"description": "待计算的算术表达式",
}
},
"required": ["expression"],
},
},
}
],
},
]
completion = client.chat.completions.create(
model="kimi-k3",
messages=dynamic_messages,
)
print(completion.choices[0].message.tool_calls)
```
* 工具定义必须包含完整的 `name`、`description` 和 `parameters`。
* 声明从该 message 所在位置起生效。
* 后续请求仍需在历史中携带该 message，服务端不会保存声明。
详见 [动态加载工具](/guide/use-dynamic-tool-loading) 。
## 1M 上下文与自动缓存
上下文缓存对普通模型请求自动启用，无需 cache ID、TTL 或额外参数。保持长前缀不变，后续请求会自动尝试命中缓存。
```python theme={null}
from pathlib import Path
knowledge: str = Path("knowledge-base.md").read_text(encoding="utf-8")
for question in ["总结关键结论。", "列出三个实施风险。"]:
completion = client.chat.completions.create(
model="kimi-k3",
messages=[
{"role": "system", "content": knowledge},
{"role": "user", "content": question},
],
)
print(completion.choices[0].message.content)
```
详见 [上下文缓存](/guide/use-context-caching-feature-of-kimi-api) 。
## 官方工具
官方工具通过 Formula 接入：
1. 从 Formula 的 `/tools` 接口获取工具定义。
2. 将定义加入 Chat Completions 请求的 `tools`。
3. 收到 `tool_calls` 后，将对应函数名和参数提交到 Formula 的 `/fibers` 接口。
4. 将完整 assistant message 和 Fiber 输出作为对应的 tool message 加入历史。
5. 再次调用 Chat Completions，直到模型返回最终答案。
完整客户端与接口契约见 [官方工具](/guide/use-official-tools) 。联网搜索工具正在更新，近期不建议使用。
## 重要限制
* `reasoning_effort` 当前仅支持 `max`；K3 始终开启思考模式。
* `max_completion_tokens` 默认 131072，最大可设置为 1048576。
* `temperature=1.0`、`top_p=0.95`、`n=1`、`presence_penalty=0`、`frequency_penalty=0` 为固定值，建议不要显式传入。
* 多轮对话和工具调用必须原样回传完整 assistant message。
* 视觉输入不支持公网图片 URL；请使用 base64 或 `ms://`，并确保 `content` 是对象数组。
* 联网搜索正在更新，近期不建议用于生产流程。
## 常见问题
Kimi K3 上下文长度为 1M tokens，计费不按上下文长度分段：所有用量均按量付费，输入（区分缓存命中与未命中）与输出分别按统一单价计费，详见 [Kimi K3 定价](/pricing/chat-k3) 。
不可以。模型发布后，国内注册并完成认证的用户获赠的 15 元代金券不可用于体验 Kimi K3，请充值后解锁使用。
## 模型价格
关于 token 价格，详见 [产品定价](/pricing/chat-k3) 。
## 相关文档
配置 reasoning\_effort。
发送图片与视频。
使用严格 JSON Schema。
从指定前缀继续生成。
控制模型是否调用工具。
按需注入工具定义。
组合工具调用能力。
接入 Formula 工具。
查看输入与输出价格。