DEV Community

Cover image for Kimi K3 API Guide: Reasoning, Tool Calling, Structured Output, and Vision
AIHubMix
AIHubMix

Posted on • Originally published at docs.aihubmix.com

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

#ai #llm #api #kimi

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)
Enter fullscreen mode Exit fullscreen mode

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?"},
]
Enter fullscreen mode Exit fullscreen mode

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?"},
]
Enter fullscreen mode Exit fullscreen mode

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",
)
Enter fullscreen mode Exit fullscreen mode

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"}],
)
Enter fullscreen mode Exit fullscreen mode

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"],
            },
        },
    },
)
Enter fullscreen mode Exit fullscreen mode

Observed output:

{"city":"Paris"}
Enter fullscreen mode Exit fullscreen mode

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"],
            },
        }
    },
)
Enter fullscreen mode Exit fullscreen mode

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},
]
Enter fullscreen mode Exit fullscreen mode

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>"}},
        ],
    }
]
Enter fullscreen mode Exit fullscreen mode

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>"},
        ],
    }
]
Enter fullscreen mode Exit fullscreen mode

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>",
                },
            },
        ],
    }
]
Enter fullscreen mode Exit fullscreen mode

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

Top comments (0)