Kimi K3 API Guide: Reasoning, Tool Calling, Structured Output, and Vision

AIHubMix — Tue, 21 Jul 2026 11:24:37 +0000

If you are testing Kimi K3 through an OpenAI-compatible API, there are a few details worth knowing before you wire it into production.

Kimi K3 is not just another chat model with a larger context window. It has always-on thinking, a 1M-token context window, API-specific differences across Chat Completions, Responses, and Claude-compatible Messages, plus a few edge cases that can surprise client code.

This guide summarizes what we verified on AIHubMix, including:

reasoning_effort="max" and thinking history
Tool calling and dynamic tool loading
Structured output support
Automatic context caching
Prefix completion
Vision input
Stop sequence behavior

Test note: The behavior below was verified through AIHubMix production APIs on July 17, 2026. Model providers may change behavior over time, so check the latest model page and official docs before relying on edge-case behavior.

Kimi K3 at a glance

Item	Value
Context window	1M tokens
Max output	`max_completion_tokens` defaults to 131,072, up to 1,048,576
Input modalities	Text and images
Thinking mode	On by default
Reasoning setting	`reasoning_effort` only supports `"max"`
Stop sequences	At most 5 entries, each no longer than 32 bytes
APIs on AIHubMix	Chat Completions, Responses, Claude-compatible Messages

If you need deep reasoning, long-context tasks, agent workflows, structured extraction, or code generation with large context, Kimi K3 is the model to test first.

For quick experiments, Kimi K3 Free can be a useful entry point before moving heavier workloads to the full Kimi K3 API.

1. Thinking mode: `reasoning_effort` only supports `max`

Kimi K3 thinking is enabled by default. The important part is that reasoning_effort only supports one value:

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 climbs 3 meters each day and slides 2 meters each night. The well is 10 meters deep. How many days?",
        }
    ],
)

print(completion.choices[0].message.reasoning_content)
print(completion.choices[0].message.content)

For multi-turn conversations, pass the previous assistant message back complete and unmodified, including thinking content.

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

This matters because Kimi K3 is trained with preserved thinking history. If your session manager, proxy, or logging layer strips thinking fields, later turns may become less stable.

2. Sampling parameters are fixed

Kimi K3 uses fixed sampling settings from the provider:

temperature: 1.0
top_p: 0.95
n: 1
presence_penalty: 0
frequency_penalty: 0

The practical recommendation is simple: omit these parameters unless the provider documentation says otherwise.

3. Tool calling and dynamic tool loading

Kimi K3 supports up to 128 tools. Tool calling works across APIs, but the syntax differs.

Chat Completions

tool_choice supports auto, none, and required.

Kimi K3 also supports dynamic tool loading in Chat Completions. You can inject a new tool mid-conversation using a system message that contains tools and no content.

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello."},
    {"role": "assistant", "content": "Hi, how can I help you?"},
    {
        "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?"},
]

One detail to remember: the injected tool message needs to be included again in later requests.

Responses API

Tool definitions use a flatter structure:

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",
)

In testing, the model returned a function_call output item.

Claude-compatible Messages API

The Messages API uses Anthropic-style tool definitions:

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

The important caveat: dynamic tool loading did not take effect on the official Messages-compatible endpoint. Declare tools at the top level instead.

4. Structured output

Structured output works well through Chat Completions and Responses.

Chat Completions

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 output:

{"city":"Paris"}

Responses API

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

Messages API caveat

The Claude-compatible Messages endpoint did not support structured output in testing. The structured-output fields were silently ignored, and the endpoint returned free-form text with HTTP 200.

If your downstream code requires strict JSON, use Chat Completions or Responses for Kimi K3 structured output.

5. Context caching is automatic

Kimi K3 context caching is automatic. No special request parameter is required.

When a repeated long prefix hits the cache, the usage field varies by API:

API	Cache usage field
Chat Completions	`usage.prompt_tokens_details.cached_tokens`
Responses	`usage.input_tokens_details.cached_tokens`
Messages	`usage.cache_read_input_tokens`

This is especially useful for long system prompts, retrieval-heavy contexts, and agent workflows that reuse large prefixes.

6. Prefix completion

Prefix completion lets the model continue from an assistant prefix. This is useful for code completion, controlled formatting, or continuing a partially generated answer.

Chat Completions

messages = [
    {"role": "user", "content": "Write a haiku about the sea."},
    {"role": "assistant", "content": "Waves fold into foam,", "partial": True},
]

Responses and Messages

For Responses and Messages, pass the assistant prefix as the last assistant message. No separate partial parameter is needed.

7. Vision input

Kimi K3 supports image input. The exact content-block format depends on the 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>"}},
        ],
    }
]

Responses API

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

Messages API

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

In a simple test using a 64x64 red PNG, the model correctly answered Red.

8. Stop sequence behavior

Kimi K3 validates stop sequence limits:

At most 5 stop sequences
Each sequence must be no longer than 32 bytes

Exceeding either limit returned HTTP 400 in testing.

One caveat: on the Messages API, a stop sequence hit did not follow Anthropic semantics. The response returned stop_reason: "end_turn" rather than stop_sequence, and stop_sequence was null.

If your client relies on those fields to detect truncation, add your own handling.

9. Latency: long Kimi K3 calls can take a while

Because Kimi K3 thinking is fixed at the max level, complex single-call tasks can take much longer than typical chat completions.

In one single-file HTML game generation test:

Total request time: 2,541 seconds, about 42 minutes
Completion tokens: 74,994
Thinking tokens: 54,486
Thinking share: 73% of completion tokens
Final result: 1,275 lines of runnable code
Finish reason: stop

For production clients:

Use streaming for long tasks
Set timeouts to minutes or longer
Leave enough room in max_completion_tokens
Track thinking-token usage when estimating cost and latency

Capability matrix

Capability	Chat Completions	Responses	Messages
Thinking content in response	`reasoning_content`	`reasoning` output item	`thinking` content block
Thinking history pass-back	Assistant message passed back verbatim	Output items passed back verbatim	Content blocks passed back verbatim
Force tool calls	`tool_choice: "required"`	`tool_choice: "required"`	`{"type": "any"}`
Disable tool calls	`tool_choice: "none"`	API-dependent	`{"type": "none"}`
Dynamic tool loading	Supported through system message with `tools`	In progress	Not supported in testing
Structured output	`response_format` with JSON Schema	`text.format` with JSON Schema	Not supported in testing
Automatic cache metering	`cached_tokens` in prompt details	`cached_tokens` in input details	`cache_read_input_tokens`
Prefix completion	`"partial": true`	Assistant prefill	Assistant prefill
Vision input	`image_url`	`input_image`	`image` block
Stop sequences	Validated limits	In progress	Limits validated, but stop metadata differs

FAQ

Which APIs does Kimi K3 support on AIHubMix?

AIHubMix supports Kimi K3 through Chat Completions, Responses, and the Claude-compatible Messages API.

Can Kimi K3 thinking be disabled?

No. Kimi K3 thinking is on by default, and reasoning_effort only supports "max".

Do I need to pass back `reasoning_content`?

Yes, for multi-turn Chat Completions. Preserve the previous assistant message complete and unmodified, including reasoning_content.

Does Kimi K3 support structured output?

Yes, through Chat Completions and Responses. In testing, the Messages-compatible endpoint did not support structured output.

Final thoughts

Kimi K3 is a strong option when you need long-context reasoning, tool calling, structured JSON, vision input, and cached-prefix workflows in one model.

The main things to watch are thinking history, long-task latency, API-specific syntax differences, and the Messages API caveats around structured output and stop sequence metadata.

For pricing and real-time status, see the Kimi K3 model page:

https://aihubmix.com/model/kimi-k3

For more models,including kimi-k3-free model pls visit:

https://aihubmix.com/models

DEV Community: AIHubMix

Kimi K3 API Guide: Reasoning, Tool Calling, Structured Output, and Vision

Kimi K3 at a glance

1. Thinking mode: reasoning_effort only supports max

2. Sampling parameters are fixed

3. Tool calling and dynamic tool loading

Chat Completions

Responses API

Claude-compatible Messages API

4. Structured output

Chat Completions

Responses API

Messages API caveat

5. Context caching is automatic

6. Prefix completion

Chat Completions

Responses and Messages

7. Vision input

Chat Completions

Responses API

Messages API

8. Stop sequence behavior

9. Latency: long Kimi K3 calls can take a while

Capability matrix

FAQ

Which APIs does Kimi K3 support on AIHubMix?

Can Kimi K3 thinking be disabled?

Do I need to pass back reasoning_content?

Does Kimi K3 support structured output?

Final thoughts

1. Thinking mode: `reasoning_effort` only supports `max`

Do I need to pass back `reasoning_content`?