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 采用保留思考（preserved thinking）训练，因此在多轮对话中，必须将上一条 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 还支持动态工具加载：通过 system 消息的 tools 字段在对话中途注入新工具（这是 Chat API 特有的消息结构）。
Chat Completions

tool_choice 支持 auto / none / required；required 会强制模型调用工具。动态工具加载：用于注入工具的 system 消息不带 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 的 system 消息在对话中途注入的工具可以被正常调用。
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 支持带 strict 模式的 json_schema。

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。
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 的上下文缓存自动启用，无需任何参数。当重复的长前缀命中缓存时，命中的数量会体现在 usage 中（字段名因 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 预填充（prefill）实现，无需 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 采用保留思考（preserved thinking）训练，Moonshot 要求将上一条 assistant 消息完整且未经修改地回传。缺少思考历史会导致输出质量不稳定。

关于 stop 参数有哪些限制？
最多 5 个 stop 序列，每个不超过 32 字节；超出任一限制都会返回 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