{"slug": "kimi-k3-api-guide-reasoning-tool-calling-structured-output-and-vision", "title": "Kimi K3 API Guide: Reasoning, Tool Calling, Structured Output, and Vision", "summary": "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.", "body_md": "If you are testing Kimi K3 through an OpenAI-compatible API, there are a few details worth knowing before you wire it into production.\n\nKimi 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.\n\nThis guide summarizes what we verified on AIHubMix, including:\n\n`reasoning_effort=\"max\"`\n\nand 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.\n\n| Item | Value |\n|---|---|\n| Context window | 1M tokens |\n| Max output |\n`max_completion_tokens` defaults to 131,072, up to 1,048,576 |\n| Input modalities | Text and images |\n| Thinking mode | On by default |\n| Reasoning setting |\n`reasoning_effort` only supports `\"max\"`\n|\n| Stop sequences | At most 5 entries, each no longer than 32 bytes |\n| APIs on AIHubMix | Chat Completions, Responses, Claude-compatible Messages |\n\nIf 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.\n\nFor quick experiments, Kimi K3 Free can be a useful entry point before moving heavier workloads to the full Kimi K3 API.\n\n`reasoning_effort`\n\nonly supports `max`\n\nKimi K3 thinking is enabled by default. The important part is that `reasoning_effort`\n\nonly supports one value:\n\n``` python\nfrom openai import OpenAI\n\nclient = OpenAI(\n    base_url=\"https://aihubmix.com/v1\",\n    api_key=\"<AIHUBMIX_API_KEY>\",\n)\n\ncompletion = client.chat.completions.create(\n    model=\"kimi-k3\",\n    reasoning_effort=\"max\",\n    messages=[\n        {\n            \"role\": \"user\",\n            \"content\": \"A snail climbs 3 meters each day and slides 2 meters each night. The well is 10 meters deep. How many days?\",\n        }\n    ],\n)\n\nprint(completion.choices[0].message.reasoning_content)\nprint(completion.choices[0].message.content)\n```\n\nFor multi-turn conversations, pass the previous assistant message back complete and unmodified, including thinking content.\n\n```\nmessages = [\n    {\"role\": \"user\", \"content\": \"What is the capital of France?\"},\n    {\n        \"role\": \"assistant\",\n        \"content\": \"Paris.\",\n        \"reasoning_content\": \"<reasoning_content from the previous response>\",\n    },\n    {\"role\": \"user\", \"content\": \"And its population?\"},\n]\n```\n\nThis 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.\n\nKimi K3 uses fixed sampling settings from the provider:\n\n`temperature`\n\n: `1.0`\n\n`top_p`\n\n: `0.95`\n\n`n`\n\n: `1`\n\n`presence_penalty`\n\n: `0`\n\n`frequency_penalty`\n\n: `0`\n\nThe practical recommendation is simple: omit these parameters unless the provider documentation says otherwise.\n\nKimi K3 supports up to 128 tools. Tool calling works across APIs, but the syntax differs.\n\n`tool_choice`\n\nsupports `auto`\n\n, `none`\n\n, and `required`\n\n.\n\nKimi K3 also supports dynamic tool loading in Chat Completions. You can inject a new tool mid-conversation using a system message that contains `tools`\n\nand no `content`\n\n.\n\n```\nmessages = [\n    {\"role\": \"system\", \"content\": \"You are a helpful assistant.\"},\n    {\"role\": \"user\", \"content\": \"Hello.\"},\n    {\"role\": \"assistant\", \"content\": \"Hi, how can I help you?\"},\n    {\n        \"role\": \"system\",\n        \"tools\": [\n            {\n                \"type\": \"function\",\n                \"function\": {\n                    \"name\": \"get_time\",\n                    \"description\": \"Get the current time\",\n                    \"parameters\": {\"type\": \"object\", \"properties\": {}},\n                },\n            }\n        ],\n    },\n    {\"role\": \"user\", \"content\": \"What time is it now?\"},\n]\n```\n\nOne detail to remember: the injected tool message needs to be included again in later requests.\n\nTool definitions use a flatter structure:\n\n```\nresponse = client.responses.create(\n    model=\"kimi-k3\",\n    input=\"Hello\",\n    tools=[\n        {\n            \"type\": \"function\",\n            \"name\": \"get_weather\",\n            \"description\": \"Get weather for a city\",\n            \"parameters\": {\n                \"type\": \"object\",\n                \"properties\": {\"city\": {\"type\": \"string\"}},\n                \"required\": [\"city\"],\n            },\n        }\n    ],\n    tool_choice=\"required\",\n)\n```\n\nIn testing, the model returned a `function_call`\n\noutput item.\n\nThe Messages API uses Anthropic-style tool definitions:\n\n``` python\nfrom anthropic import Anthropic\n\nclient = Anthropic(\n    api_key=\"<AIHUBMIX_API_KEY>\",\n    base_url=\"https://aihubmix.com\",\n)\n\nresponse = client.messages.create(\n    model=\"kimi-k3\",\n    max_tokens=4096,\n    tools=[\n        {\n            \"name\": \"get_weather\",\n            \"description\": \"Get weather for a city\",\n            \"input_schema\": {\n                \"type\": \"object\",\n                \"properties\": {\"city\": {\"type\": \"string\"}},\n                \"required\": [\"city\"],\n            },\n        }\n    ],\n    tool_choice={\"type\": \"any\"},\n    messages=[{\"role\": \"user\", \"content\": \"Hello\"}],\n)\n```\n\nThe important caveat: dynamic tool loading did not take effect on the official Messages-compatible endpoint. Declare tools at the top level instead.\n\nStructured output works well through Chat Completions and Responses.\n\n```\ncompletion = client.chat.completions.create(\n    model=\"kimi-k3\",\n    messages=[\n        {\n            \"role\": \"user\",\n            \"content\": \"Paris is the capital of France. Extract the city name.\",\n        }\n    ],\n    response_format={\n        \"type\": \"json_schema\",\n        \"json_schema\": {\n            \"name\": \"extract\",\n            \"strict\": True,\n            \"schema\": {\n                \"type\": \"object\",\n                \"properties\": {\"city\": {\"type\": \"string\"}},\n                \"required\": [\"city\"],\n            },\n        },\n    },\n)\n```\n\nObserved output:\n\n```\n{\"city\":\"Paris\"}\nresponse = client.responses.create(\n    model=\"kimi-k3\",\n    input=\"Paris is the capital of France. Extract the city name.\",\n    text={\n        \"format\": {\n            \"type\": \"json_schema\",\n            \"name\": \"extract\",\n            \"strict\": True,\n            \"schema\": {\n                \"type\": \"object\",\n                \"properties\": {\"city\": {\"type\": \"string\"}},\n                \"required\": [\"city\"],\n            },\n        }\n    },\n)\n```\n\nThe 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.\n\nIf your downstream code requires strict JSON, use Chat Completions or Responses for Kimi K3 structured output.\n\nKimi K3 context caching is automatic. No special request parameter is required.\n\nWhen a repeated long prefix hits the cache, the usage field varies by API:\n\n| API | Cache usage field |\n|---|---|\n| Chat Completions | `usage.prompt_tokens_details.cached_tokens` |\n| Responses | `usage.input_tokens_details.cached_tokens` |\n| Messages | `usage.cache_read_input_tokens` |\n\nThis is especially useful for long system prompts, retrieval-heavy contexts, and agent workflows that reuse large prefixes.\n\nPrefix completion lets the model continue from an assistant prefix. This is useful for code completion, controlled formatting, or continuing a partially generated answer.\n\n```\nmessages = [\n    {\"role\": \"user\", \"content\": \"Write a haiku about the sea.\"},\n    {\"role\": \"assistant\", \"content\": \"Waves fold into foam,\", \"partial\": True},\n]\n```\n\nFor Responses and Messages, pass the assistant prefix as the last assistant message. No separate `partial`\n\nparameter is needed.\n\nKimi K3 supports image input. The exact content-block format depends on the API.\n\n```\nmessages = [\n    {\n        \"role\": \"user\",\n        \"content\": [\n            {\"type\": \"text\", \"text\": \"What is the dominant color of this image? One word.\"},\n            {\"type\": \"image_url\", \"image_url\": {\"url\": \"data:image/png;base64,<BASE64>\"}},\n        ],\n    }\n]\ninput = [\n    {\n        \"role\": \"user\",\n        \"content\": [\n            {\"type\": \"input_text\", \"text\": \"What is the dominant color of this image? One word.\"},\n            {\"type\": \"input_image\", \"image_url\": \"data:image/png;base64,<BASE64>\"},\n        ],\n    }\n]\nmessages = [\n    {\n        \"role\": \"user\",\n        \"content\": [\n            {\"type\": \"text\", \"text\": \"What is the dominant color of this image? One word.\"},\n            {\n                \"type\": \"image\",\n                \"source\": {\n                    \"type\": \"base64\",\n                    \"media_type\": \"image/png\",\n                    \"data\": \"<BASE64>\",\n                },\n            },\n        ],\n    }\n]\n```\n\nIn a simple test using a 64x64 red PNG, the model correctly answered `Red`\n\n.\n\nKimi K3 validates stop sequence limits:\n\nExceeding either limit returned HTTP 400 in testing.\n\nOne caveat: on the Messages API, a stop sequence hit did not follow Anthropic semantics. The response returned `stop_reason: \"end_turn\"`\n\nrather than `stop_sequence`\n\n, and `stop_sequence`\n\nwas `null`\n\n.\n\nIf your client relies on those fields to detect truncation, add your own handling.\n\nBecause Kimi K3 thinking is fixed at the max level, complex single-call tasks can take much longer than typical chat completions.\n\nIn one single-file HTML game generation test:\n\n`stop`\n\nFor production clients:\n\n`max_completion_tokens`\n\n| Capability | Chat Completions | Responses | Messages |\n|---|---|---|---|\n| Thinking content in response | `reasoning_content` |\n`reasoning` output item |\n`thinking` content block |\n| Thinking history pass-back | Assistant message passed back verbatim | Output items passed back verbatim | Content blocks passed back verbatim |\n| Force tool calls | `tool_choice: \"required\"` |\n`tool_choice: \"required\"` |\n`{\"type\": \"any\"}` |\n| Disable tool calls | `tool_choice: \"none\"` |\nAPI-dependent | `{\"type\": \"none\"}` |\n| Dynamic tool loading | Supported through system message with `tools`\n|\nIn progress | Not supported in testing |\n| Structured output |\n`response_format` with JSON Schema |\n`text.format` with JSON Schema |\nNot supported in testing |\n| Automatic cache metering |\n`cached_tokens` in prompt details |\n`cached_tokens` in input details |\n`cache_read_input_tokens` |\n| Prefix completion | `\"partial\": true` |\nAssistant prefill | Assistant prefill |\n| Vision input | `image_url` |\n`input_image` |\n`image` block |\n| Stop sequences | Validated limits | In progress | Limits validated, but stop metadata differs |\n\nAIHubMix supports Kimi K3 through Chat Completions, Responses, and the Claude-compatible Messages API.\n\nNo. Kimi K3 thinking is on by default, and `reasoning_effort`\n\nonly supports `\"max\"`\n\n.\n\n`reasoning_content`\n\n?\nYes, for multi-turn Chat Completions. Preserve the previous assistant message complete and unmodified, including `reasoning_content`\n\n.\n\nYes, through Chat Completions and Responses. In testing, the Messages-compatible endpoint did not support structured output.\n\nKimi K3 is a strong option when you need long-context reasoning, tool calling, structured JSON, vision input, and cached-prefix workflows in one model.\n\nThe 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.\n\nFor pricing and real-time status, see the Kimi K3 model page:\n\n[https://aihubmix.com/model/kimi-k3](https://aihubmix.com/model/kimi-k3)\n\nFor more models,including kimi-k3-free model pls visit:", "url": "https://wpnews.pro/news/kimi-k3-api-guide-reasoning-tool-calling-structured-output-and-vision", "canonical_source": "https://dev.to/aihubmix/kimi-k3-api-guide-reasoning-tool-calling-structured-output-and-vision-bn3", "published_at": "2026-07-21 11:24:37+00:00", "updated_at": "2026-07-21 11:30:09.297067+00:00", "lang": "en", "topics": ["large-language-models", "ai-products", "developer-tools"], "entities": ["Kimi K3", "AIHubMix", "OpenAI"], "alternates": {"html": "https://wpnews.pro/news/kimi-k3-api-guide-reasoning-tool-calling-structured-output-and-vision", "markdown": "https://wpnews.pro/news/kimi-k3-api-guide-reasoning-tool-calling-structured-output-and-vision.md", "text": "https://wpnews.pro/news/kimi-k3-api-guide-reasoning-tool-calling-structured-output-and-vision.txt", "jsonld": "https://wpnews.pro/news/kimi-k3-api-guide-reasoning-tool-calling-structured-output-and-vision.jsonld"}}