> ## 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