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

Kimi K3, a reasoning model with a 1M-token context window and always-on thinking, has been tested on AIHubMix. The model supports only `reasoning_effort="max"`, up to 128 tools, and requires preserving thinking history in multi-turn conversations. Key API differences include fixed sampling parameters and dynamic tool loading via system messages.

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 historyTest 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. | 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. reasoning effort only supports max Kimi K3 thinking is enabled by default. The important part is that reasoning effort only supports one value: python 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. 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. Kimi K3 supports up to 128 tools. Tool calling works across APIs, but the syntax differs. 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. 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. The Messages API uses Anthropic-style tool definitions: python 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. Structured output works well through Chat Completions and Responses. 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"} 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" , }, } }, 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. 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. Prefix completion lets the model continue from an assistant prefix. This is useful for code completion, controlled formatting, or continuing a partially generated answer. messages = {"role": "user", "content": "Write a haiku about the sea."}, {"role": "assistant", "content": "Waves fold into foam,", "partial": True}, For Responses and Messages, pass the assistant prefix as the last assistant message. No separate partial parameter is needed. Kimi K3 supports image input. The exact content-block format depends on the API. 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 "}}, , } 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 = { "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 . Kimi K3 validates stop sequence limits: 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. 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: stop For production clients: max completion tokens | 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 | AIHubMix supports Kimi K3 through Chat Completions, Responses, and the Claude-compatible Messages API. No. Kimi K3 thinking is on by default, and reasoning effort only supports "max" . reasoning content ? Yes, for multi-turn Chat Completions. Preserve the previous assistant message complete and unmodified, including reasoning content . Yes, through Chat Completions and Responses. In testing, the Messages-compatible endpoint did not support structured output. 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 https://aihubmix.com/model/kimi-k3 For more models,including kimi-k3-free model pls visit: