> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Kimi K3 实测调用指南：新参数与三接口支持矩阵
> 2026 年 7 月 Kimi K3 调用指南：reasoning_effort max 档与思考历史回传、动态工具加载、结构化输出、自动缓存、partial 前缀续写与视觉输入，附 AIHubMix Chat / Responses / Messages 三接口示例。
> 本文介绍 [Kimi K3](https://aihubmix.com/model/kimi-k3) 的新增参数与调用注意事项。K3 在 AIHubMix 可通过 Chat Completions、Responses 与 Claude 兼容的 Messages 接口调用。延伸阅读：[Moonshot 官方平台文档](https://platform.moonshot.ai/docs)。
>
> 各节的「实测」结论与示例返回均来自 2026-07-17 通过 AIHubMix 接口（Chat Completions / Responses / Messages）的实际调用。
## 1. 模型规格速览
| 项 | 值 |
| :---- | :---------------------------------------------- |
| 上下文窗口 | 1M tokens |
| 最大输出 | `max_completion_tokens` 默认 131,072，最大 1,048,576 |
| 输入模态 | 文本、图像（视频输入见 Moonshot 官方文档） |
| 思考模式 | 默认开启，`reasoning_effort` 仅支持 `"max"` |
| 停止序列 | `stop` 最多 5 个，每个不超过 32 字节 |
> **实测**：`stop` 的两个上限均会校验，超出返回 400；Messages 接口的 `stop_sequences` 执行相同校验。
>
> ❗ **Messages 接口命中停止词时不按 Anthropic 语义返回**：实测 `stop_reason` 为 `"end_turn"`（而非 `"stop_sequence"`）、`stop_sequence` 为 `null`，且停止词之前的可见文本可能为空。依赖这两个字段判断截断原因的客户端需注意。
```text theme={null}
# stop with 6 entries / a 33-byte entry -> HTTP 400
"Invalid request: stop array too long. Expected an array with maximum length 5, but got an array with length 6 instead"
"Invalid request: stop sequence must not be longer than 32, but got 33 instead"
```
## 2. 思考模式：`reasoning_effort` 仅 `max` 档
K3 的思考默认开启，`reasoning_effort` 仅支持 `"max"` 一档。
**多轮对话必须原样回传思考历史**：按 Moonshot 官方说明，K3 采用 preserved thinking 方式训练，多轮对话时需要把上一轮返回的 assistant 消息**原样完整**回传（包含思考内容），思考历史缺失会导致输出质量不稳定。使用会话管理框架或代理层时，请确认思考内容未在回传前被裁剪。
思考内容通过响应里的 `reasoning_content` 字段返回；多轮时把上一轮 assistant 消息（含 `reasoning_content`）原样回传。
```text theme={null}
from openai import OpenAI
client = OpenAI(
base_url="https://aihubmix.com/v1",
api_key="",
)
completion = client.chat.completions.create(
model="kimi-k3",
reasoning_effort="max",
messages=[
{"role": "user", "content": "A snail is at the bottom of a 10-meter well. Each day it climbs 3 meters, but each night it slides back 2 meters. How many days does it take to reach the top?"}
],
)
print(completion.choices[0].message.reasoning_content)
print(completion.choices[0].message.content)
```
```text theme={null}
# Multi-turn: pass the previous assistant message back verbatim
messages = [
{"role": "user", "content": "What is the capital of France?"},
{"role": "assistant", "content": "Paris.", "reasoning_content": ""},
{"role": "user", "content": "And its population?"},
]
```
> **实测**：响应返回 `reasoning_content`；把上一轮 assistant 消息（含 `reasoning_content`）原样回传后，后续轮次正常应答。
思考内容以 `reasoning` 输出项返回；多轮时把上一轮的输出项（`reasoning` + `message`）原样拼回 `input`。
```text theme={null}
from openai import OpenAI
client = OpenAI(
base_url="https://aihubmix.com/v1",
api_key="",
)
response = client.responses.create(
model="kimi-k3",
input="Answer in one word: capital of France",
)
# Observed response.output item types: ["reasoning", "message"]; text: "Paris"
# Multi-turn: input = [first user message] + response.output + [next user message]
# Observed second-turn answer with output items passed back: "Berlin"
```
思考内容以原生 `thinking` 内容块返回；多轮时把上一轮 assistant 的内容块（含 thinking 块）原样回传。
```text theme={null}
from anthropic import Anthropic
client = Anthropic(
api_key="",
base_url="https://aihubmix.com"
)
response = client.messages.create(
model="kimi-k3",
max_tokens=4096,
messages=[
{"role": "user", "content": "Answer in one word: capital of France"}
],
)
# Observed response.content block types: ["thinking", "text"]; text: "Paris"
# Multi-turn: pass response.content back verbatim as the assistant message
```
## 3. 采样参数为固定值
K3 的采样参数为官方固定值：`temperature` 1.0、`top_p` 0.95、`n` 1、`presence_penalty` / `frequency_penalty` 0。官方建议请求中不要传入这些参数。
> **说明**：采样固定值为官方规格，无法从响应信号验证；请按官方建议省略这些参数。
## 4. 工具调用与动态工具加载
`tools` 最多支持 128 个工具；`tool_choice` 支持强制调用与禁用调用。K3 还支持动态工具加载：在对话中途通过一条 system 消息的 `tools` 字段注入新工具（Chat 接口特有的消息形态）。
`tool_choice` 支持 `auto` / `none` / `required`，`required` 强制模型调用工具。动态工具加载：注入工具的 system 消息不带 `content`，注入的工具对后续轮次生效，每轮请求需要重复携带。
```text theme={null}
messages = [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello."},
{"role": "assistant", "content": "Hi, how can I help you?"},
# Inject a new tool mid-conversation: tools field only, no content
{
"role": "system",
"tools": [
{
"type": "function",
"function": {
"name": "get_time",
"description": "Get the current time",
"parameters": {"type": "object", "properties": {}},
},
}
],
},
{"role": "user", "content": "What time is it now?"},
]
```
```text theme={null}
# tool_choice="required" with prompt "Hello" -> the model is forced to call the tool
"finish_reason": "tool_calls",
"tool_calls": [{"function": {"name": "get_weather", "arguments": "{\"city\":\"New York\"}"}}]
```
> **实测**：`tool_choice: "required"` 对无关提问也会强制产生工具调用；`"none"` 抑制工具调用；经无 `content` 的 system 消息中途注入的工具可被正常调用。
工具定义为扁平结构（`name` 在顶层），强制调用同样使用 `tool_choice: "required"`，调用以 `function_call` 输出项返回。动态工具加载支持中，当前请在顶层 `tools` 参数中声明全部工具。
```text theme={null}
response = client.responses.create(
model="kimi-k3",
input="Hello",
tools=[{
"type": "function",
"name": "get_weather",
"description": "Get weather for a city",
"parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
}],
tool_choice="required",
)
# Observed output contains: {"type": "function_call", "name": "get_weather", "arguments": "{\"city\":\"London\"}"}
```
工具用 Anthropic 格式（`input_schema`），强制调用为 `tool_choice: {"type": "any"}`，禁用为 `{"type": "none"}`。❗ **Kimi K3 官方的 Messages（Anthropic 兼容）端点不支持动态工具加载**：实测注入消息返回 200，但注入的工具不生效（模型无法调用），请在顶层 `tools` 参数中声明全部工具。
```text theme={null}
response = client.messages.create(
model="kimi-k3",
max_tokens=4096,
tools=[{
"name": "get_weather",
"description": "Get weather for a city",
"input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
}],
tool_choice={"type": "any"},
messages=[{"role": "user", "content": "Hello"}],
)
# Observed: stop_reason "tool_use"; content contains a tool_use block calling get_weather
```
## 5. 结构化输出
结构化输出可让模型返回严格符合给定 JSON Schema 的内容。
`response_format` 支持 `json_schema` 与 `strict` 模式。
```text theme={null}
completion = client.chat.completions.create(
model="kimi-k3",
messages=[
{"role": "user", "content": "Paris is the capital of France. Extract the city name."}
],
response_format={
"type": "json_schema",
"json_schema": {
"name": "extract",
"strict": True,
"schema": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
},
)
# Observed response content: {"city":"Paris"}
```
> **实测**：输出为符合 schema 的合法 JSON。
结构化输出通过 `text.format` 声明。
```text theme={null}
response = client.responses.create(
model="kimi-k3",
input="Paris is the capital of France. Extract the city name.",
text={
"format": {
"type": "json_schema",
"name": "extract",
"strict": True,
"schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
}
},
)
# Observed output text: {"city":"Paris"}
```
❗ **Kimi K3 官方的 Messages（Anthropic 兼容）端点不支持结构化输出**：结构化输出字段会被静默忽略——请求返回 HTTP 200 与自由文本，无任何报错或降级提示，下游 JSON 解析会失败。需要结构化输出时请使用 Chat Completions 或 Responses 接口。
## 6. 上下文缓存自动开启
K3 的上下文缓存自动开启，无需传入任何参数。重复的长前缀命中缓存后，命中量在 usage 中报告（字段名随接口而异）。缓存价格见[模型页](https://aihubmix.com/model/kimi-k3)。
```text theme={null}
# usage of the second call with an identical long prefix
"prompt_tokens_details": {"cached_tokens": 1536}
```
> **实测**：相同长前缀的第二次请求在 `usage.prompt_tokens_details.cached_tokens` 中报告命中。
```text theme={null}
# usage of the second Responses call with identical long instructions
"input_tokens_details": {"cached_tokens": 1536}
```
```text theme={null}
# usage of the second Messages call with an identical long system prompt
"cache_read_input_tokens": 1536
```
## 7. `partial` 前缀续写
前缀续写让模型从给定前缀继续生成，适合代码补全和受控格式输出。
在最后一条 assistant 消息中传入 `"partial": true`。
```text theme={null}
messages = [
{"role": "user", "content": "Write a haiku about the sea."},
{"role": "assistant", "content": "Waves fold into foam,", "partial": True},
]
# Prefix: "Waves fold into foam," -> continuation returned by the model
# salt hangs in the air—
# moon pulls the tide home.
```
> **实测**：生成从给定前缀继续，不重复前缀。
把前缀作为 `input` 数组末尾的 assistant 消息传入，无需 `partial` 参数。
```text theme={null}
response = client.responses.create(
model="kimi-k3",
input=[
{"role": "user", "content": "Write a haiku about the sea."},
{"role": "assistant", "content": "Waves fold into foam,"},
],
)
# Observed continuation: "salt hangs in the air— / moon pulls the tide home."
```
以协议原生的 assistant 预填实现同等能力，无需 `partial` 参数——把前缀作为最后一条 assistant 消息传入即可。
```text theme={null}
response = client.messages.create(
model="kimi-k3",
max_tokens=4096,
messages=[
{"role": "user", "content": "Write a haiku about the sea."},
{"role": "assistant", "content": "Waves fold into foam,"},
],
)
# Observed continuation: "salt wind carries the gull's cry— / tide pulls ..."
```
## 8. 视觉输入
图像以 base64 传入，内容块写法随接口而异。
```text theme={null}
messages = [
{
"role": "user",
"content": [
{"type": "text", "text": "What is the dominant color of this image? One word."},
{"type": "image_url", "image_url": {"url": "data:image/png;base64,"}},
],
}
]
# Observed response content: "Red" (input: a 64x64 solid red PNG)
```
> **实测**：base64 图像输入可用，模型正确描述测试图内容。
```text theme={null}
input = [
{
"role": "user",
"content": [
{"type": "input_text", "text": "What is the dominant color of this image? One word."},
{"type": "input_image", "image_url": "data:image/png;base64,"},
],
}
]
# Observed output text: "Red"
```
```text theme={null}
messages = [
{
"role": "user",
"content": [
{"type": "text", "text": "What is the dominant color of this image? One word."},
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": ""}},
],
}
]
# Observed response text: "Red"
```
## 9. 实测参考：长任务单次调用的耗时与用量
K3 思考固定为 max 档，复杂任务的单次请求耗时显著长于常规模型。一次单文件 HTML 游戏生成任务（单条 prompt 附参考图，一次生成，不迭代）的实测数据：单次请求耗时 2,541 秒（约 42 分钟），completion tokens 74,994，其中思考部分 54,486，占 73%，最终一次产出 1,275 行可直接运行的代码，`finish_reason` 为 `stop`。
调用侧建议：
* 客户端超时按分钟级以上设置，长任务优先使用流式返回；
* `max_completion_tokens` 给足余量，本例仅思考即消耗 54,486 tokens。
## 10. 能力 × 接口支持矩阵
下表各格均为 2026-07-17 通过 AIHubMix 线上接口实际调用验证的结果，格内为对应接口的参数 / 字段写法。
| 能力 | Chat Completions | Responses | Messages |
| :---------- | :-------------------------------------------- | :------------------------------------------- | :----------------------------------------------------------------------------------- |
| 思考内容返回 | ✅ `reasoning_content` 字段 | ✅ `reasoning` 输出项 | ✅ `thinking` 内容块 |
| 思考历史回传 | ✅ assistant 消息原样回传 | ✅ 输出项原样回传 | ✅ 内容块原样回传 |
| 强制 / 禁用工具调用 | ✅ `tool_choice: "required"` / `"none"` | ✅ `tool_choice: "required"` | ✅ `{"type": "any"}` / `{"type": "none"}` |
| 动态工具加载 | ✅ system 消息带 `tools`（无 `content`） | ➖ 支持中 | ❗ 官方 Messages（Anthropic 兼容）端点不支持 |
| 结构化输出 | ✅ `response_format`（json\_schema + strict） | ✅ `text.format`（json\_schema） | ❗ 官方端点不支持，字段被**静默忽略**（200 + 自由文本），请改用 Chat / Responses |
| 自动缓存命中计量 | ✅ `usage.prompt_tokens_details.cached_tokens` | ✅ `usage.input_tokens_details.cached_tokens` | ✅ `usage.cache_read_input_tokens` |
| 前缀续写 | ✅ `"partial": true` | ✅ assistant 预填 | ✅ assistant 预填（协议原生） |
| 视觉输入 | ✅ `image_url`（base64） | ✅ `input_image`（base64） | ✅ `image` 内容块（base64） |
| 停止序列 | ✅ `stop`（上限校验） | ➖ 支持中 | ❗ `stop_sequences` 上限校验一致，但命中时不返回 `stop_reason: "stop_sequence"` / `stop_sequence` 值 |
## 常见问题
**K3 在 AIHubMix 支持哪些接口？**
Chat Completions（`/v1/chat/completions`）、Responses（`/v1/responses`）与 Claude 兼容的 Messages（`/v1/messages`）。
**可以关闭思考或调低思考强度吗？**
不可以。K3 思考默认开启，`reasoning_effort` 仅支持 `"max"` 一档。
**为什么多轮对话要回传 `reasoning_content`？**
K3 采用 preserved thinking 方式训练，官方要求原样完整回传上一轮 assistant 消息；思考历史缺失会导致输出质量不稳定。
**`stop` 参数有什么限制？**
最多 5 个停止词，每个不超过 32 字节，超出会返回 400 错误。
**Messages 接口支持结构化输出吗？**
❗ 不支持。Kimi K3 官方的 Messages（Anthropic 兼容）端点会静默忽略结构化输出字段（返回 200 与自由文本，无报错）。需要结构化输出请使用 Chat Completions 的 `response_format` 或 Responses 的 `text.format`。
**K3 单次请求为什么耗时较长？**
K3 思考固定为 max 档，复杂任务的思考 token 占比高（实测案例中占 completion tokens 的 73%）。建议按分钟级以上设置客户端超时，并使用流式返回。
***
模型定价与实时状态见 [Kimi K3 模型页](https://aihubmix.com/model/kimi-k3)，更多模型见[模型广场](https://aihubmix.com/models)。
更新时间：2026-07-17