Kimi K3 實測指南：新參數與 API 支援一覽表

本文介紹 Kimi K3 的新參數與使用注意事項。在 AIHubMix 上，K3 可透過 Chat Completions、Responses 和相容 Claude 的 Messages API 使用。另請參閱：Moonshot 官方平台文件。

各節中的「已驗證」結論與範例回應，均來自 2026-07-17 透過 AIHubMix API（Chat Completions / Responses / Messages）進行的實際呼叫。

1. 模型規格一覽

已驗證：兩項 stop 限制皆經過驗證，超出任一限制都會回傳 400；Messages API 對 stop_sequences 套用相同驗證規則。

❗ 遇到停止序列時，Messages API 不會遵循 Anthropic 語意：測試中，stop_reason 為 "end_turn"（而非 "stop_sequence"），stop_sequence 為 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 是以保留思考內容的方式訓練而成，因此在多輪對話中，必須將先前的 assistant 訊息完整且不做修改地傳回（包括思考內容）。若缺少思考歷史，輸出品質會不穩定。若使用工作階段管理架構或代理層，請確認思考內容未經刪減就傳回。
Chat Completions

思考內容會以回應中的 reasoning_content 欄位回傳；在多輪對話中，請原樣傳回先前的 assistant 訊息（包括 reasoning_content）。

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_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)

# 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": "<reasoning_content from the previous response>"},
    {"role": "user", "content": "And its population?"},
]

已驗證：回應會回傳 reasoning_content；原樣傳回先前的 assistant 訊息（包括 reasoning_content）後，後續輪次便能正常回答。
Responses

思考內容會以 reasoning 輸出項目回傳；在多輪對話中，請將上一輪的輸出項目（reasoning + message）原樣附加回 input。

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_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"

Messages

思考內容會以原生的 thinking 內容區塊回傳；在多輪對話中，請原樣傳回先前的 assistant 內容區塊（包括 thinking 區塊）。

from anthropic import Anthropic

client = Anthropic(
    api_key="<AIHUBMIX_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 也支援動態載入工具：透過系統訊息的 tools 欄位，在對話中途注入新工具（這是 Chat API 專用的訊息格式）。
Chat Completions

tool_choice 支援 auto / none / required；required 會強制模型呼叫工具。動態載入工具：注入工具的系統訊息不含 content，注入的工具會在後續輪次生效，而且每次請求都必須再次包含該訊息。

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?"},
]

# 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 的系統訊息在對話中途注入的工具，也能正常呼叫。
Responses

工具定義採用扁平結構（name 位於頂層）；同樣可透過 tool_choice: "required" 強制呼叫，呼叫會以 function_call 輸出項目回傳。目前仍在開發動態載入工具支援；現階段請在頂層 tools 參數中宣告所有工具。

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\"}"}

Messages

工具採用 Anthropic 格式（input_schema）；使用 tool_choice: {"type": "any"} 強制呼叫，使用 {"type": "none"} 停用呼叫。❗ Kimi K3 官方的 Messages（相容 Anthropic）端點不支援動態載入工具：測試中，注入工具的訊息雖然回傳 200，但注入的工具並未生效（模型無法呼叫該工具）。請在頂層 tools 參數中宣告所有工具。

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 的內容。
Chat Completions

response_format 支援 json_schema 與 strict 模式。

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"}

已驗證：輸出為符合該結構描述的有效 JSON。
Responses

透過 text.format 宣告結構化輸出。

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"}

Messages

❗ Kimi K3 官方的 Messages（相容 Anthropic）端點不支援結構化輸出：結構化輸出欄位會遭到靜默忽略；請求回傳 HTTP 200 和自由格式文字，不會出現錯誤或回退提示，下游 JSON 剖析將會失敗。需要結構化輸出時，請使用 Chat Completions 或 Responses API。

6. 自動快取上下文

K3 會自動啟用上下文快取，不需要任何參數。當重複出現的長前綴命中快取時，使用量資訊會回報命中量（欄位名稱依 API 而異）。快取定價請見模型頁面。
Chat Completions

# usage of the second call with an identical long prefix
"prompt_tokens_details": {"cached_tokens": 1536}

已驗證：第二次送出相同長前綴的請求時，會在 usage.prompt_tokens_details.cached_tokens 中回報命中量。
Responses

# usage of the second Responses call with identical long instructions
"input_tokens_details": {"cached_tokens": 1536}

Messages

# usage of the second Messages call with an identical long system prompt
"cache_read_input_tokens": 1536

7. partial 前綴補全

前綴補全會讓模型從指定的前綴繼續生成，非常適合程式碼補全和格式受控的輸出。
Chat Completions

在最後一則 assistant 訊息中傳入 "partial": true。

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.

已驗證：生成內容會從指定前綴接續，不會重複該前綴。
Responses

將前綴作為 assistant 訊息傳入 input 陣列末尾；不需要 partial 參數。

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."

Messages

使用協定原生的 assistant 預填即可達到相同效果，不需要 partial 參數：將前綴作為最後一則 assistant 訊息傳入。

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 傳入；內容區塊格式依 API 而異。
Chat Completions

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,<BASE64>"}},
        ],
    }
]

# Observed response content: "Red"  (input: a 64x64 solid red PNG)

已驗證：base64 圖片輸入可正常運作，模型也能正確描述測試圖片。
Responses

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,<BASE64>"},
        ],
    }
]

# Observed output text: "Red"

Messages

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": "<BASE64>"}},
        ],
    }
]

# Observed response text: "Red"

9. 已驗證參考數據：長時間單次呼叫任務的延遲與使用量

K3 的思考強度固定為 max，因此處理複雜任務的單次請求，耗時會比一般模型長得多。以生成單檔 HTML 遊戲任務的實測數據為例（單一提示詞附上一張參考圖片，一次生成完成，沒有反覆修改）：單次請求耗時 2,541 秒（約 42 分鐘），使用 74,994 個 completion tokens，其中 54,486 個（73%）為思考 tokens；最終輸出為 1,275 行可直接執行的程式碼，finish_reason 為 stop。

用戶端建議：

• 將用戶端逾時時間設為數分鐘或更長，長時間任務建議優先使用串流模式；
• 為 max_completion_tokens 預留充足空間：此案例光是思考就耗用 54,486 個 tokens。

10. 功能 × API 支援一覽表

下表每個儲存格皆於 2026-07-17 透過實際呼叫 AIHubMix 正式環境 API 驗證；各儲存格列出對應 API 的參數／欄位語法。

常見問題

K3 在 AIHubMix 上支援哪些 API？
Chat Completions（/v1/chat/completions）、Responses（/v1/responses），以及相容 Claude 的 Messages API（/v1/messages）。

可以停用或調低思考強度嗎？
不行。K3 預設開啟思考模式，而 reasoning_effort 僅支援單一 "max" 層級。

為什麼多輪對話必須傳回 reasoning_content？
K3 採用保留思考過程的方式訓練；Moonshot 要求完整且未經修改地傳回先前的 assistant 訊息。缺少思考歷史會導致輸出品質不穩定。

stop 參數有哪些限制？
最多可設定 5 個停止序列，每個不得超過 32 bytes；超過任一限制都會回傳 400 錯誤。

Messages API 支援結構化輸出嗎？
❗ 不支援。Kimi K3 官方的 Messages（相容 Anthropic）端點會靜默忽略結構化輸出欄位（回傳 200，提供自由格式文字且不顯示錯誤）。若要使用結構化輸出，請在 Chat Completions 使用 response_format，或在 Responses 使用 text.format。

為什麼單次 K3 請求耗時這麼久？
K3 的思考模式固定為最高強度；在複雜任務中，思考 token 佔了完成 token 的很大一部分（測試案例中為 73%）。請將用戶端逾時設定為數分鐘或更長，並使用串流。

如需定價與即時狀態，請參閱 Kimi K3 模型頁面；如需探索更多模型，請造訪模型庫。

最後更新：2026-07-17