Kimi K3 - Kimi API Platform

Introducing Kimi K3

Kimi K3 is Kimi’s most capable model to date, with 2.8 trillion parameters. Built on Kimi Delta Attention, a hybrid linear attention mechanism, and Attention Residuals, it offers native visual understanding and a 1M-token context window for frontier intelligence scenarios such as software engineering, knowledge work, and deep reasoning.

Get started

The examples require Python 3.9+ and the OpenAI SDK. Install the SDK and initialize the client once; later Python examples reuse client.

python3 -m pip install --upgrade 'openai>=1.0'

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.ai/v1",
)

Basic call

Python
cURL

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Introduce Kimi K3 in one sentence."}],
)

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

curl https://api.moonshot.ai/v1/chat/completions \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "kimi-k3",
    "messages": [{"role": "user", "content": "Introduce Kimi K3 in one sentence."}]
  }'

Thinking effort

K3 always has thinking mode enabled and supports configuring its thinking effort with the top-level reasoning_effort field. Do not use the K2.x thinking parameter.

Thinking effort currently supports only the max level (default); more levels are coming soon. See Thinking Effort for usage.

completion = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="max",
    messages=[{"role": "user", "content": "Prove that the square root of 2 is irrational."}],
)

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

For multi-turn conversations and tool calls, add the complete assistant message returned by the API to the next request. Do not keep only content.

Streaming

Streaming responses provide separate reasoning_content and final-answer content deltas. See Streaming Output for details.

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Explain why the sky is blue."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    reasoning = getattr(delta, "reasoning_content", None)
    if reasoning:
        print(reasoning, end="", flush=True)
    if delta.content:
        print(delta.content, end="", flush=True)

Vision input

For vision messages, content must be an array of objects, not a serialized string. See Vision Input for formats and limits.

Local image
Video file

import base64
from pathlib import Path

image_data: str = base64.b64encode(Path("image.png").read_bytes()).decode()
completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/png;base64,{image_data}"},
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)

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

from pathlib import Path

video = client.files.create(file=Path("video.mp4"), purpose="video")
try:
    completion = client.chat.completions.create(
        model="kimi-k3",
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "video_url",
                        "video_url": {"url": f"ms://{video.id}"},
                    },
                    {"type": "text", "text": "Summarize this video."},
                ],
            }
        ],
    )
    print(completion.choices[0].message.content)
finally:
    client.files.delete(video.id)

Structured output

Use json_schema with strict: true to constrain the final message.content. Parse only that field, not reasoning_content.

Name and age schema

import json

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Lin is 28 years old. Extract the name and age."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                },
                "required": ["name", "age"],
                "additionalProperties": False,
            },
        },
    },
)

person: dict[str, object] = json.loads(
    completion.choices[0].message.content or "{}"
)
print(person)

See Structured Output.

Partial Mode

Add an assistant message with partial=True at the end of messages to continue from a text prefix. Prepend that prefix when displaying the final result.

prefix: str = "Conclusion: "
completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "In one sentence, explain why API compatibility matters."},
        {"role": "assistant", "content": prefix, "partial": True},
    ],
)

print(prefix + (completion.choices[0].message.content or ""))

See Partial Mode.

Custom tools and `tool_choice`

Use tool_choice="required" on the first turn to require at least one tool call. After executing every call, return the complete assistant message and append one tool result with the matching tool_call_id for each call.

Minimal weather agent loop

import json
from typing import Any

tools: list[dict[str, Any]] = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the weather for a city",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }
]
messages: list[Any] = [
    {"role": "user", "content": "What is the weather in San Francisco today?"}
]

first = client.chat.completions.create(
    model="kimi-k3",
    messages=messages,
    tools=tools,
    tool_choice="required",
)
assistant_message = first.choices[0].message
messages.append(assistant_message)

for tool_call in assistant_message.tool_calls or []:
    arguments: dict[str, str] = json.loads(tool_call.function.arguments)
    result: str = json.dumps(
        {"city": arguments["city"], "weather": "sunny", "temperature_c": 24}
    )
    messages.append(
        {"role": "tool", "tool_call_id": tool_call.id, "content": result}
    )

final = client.chat.completions.create(
    model="kimi-k3",
    messages=messages,
    tools=tools,
)
print(final.choices[0].message.content)

See Tool Choice.

Dynamic tool loading

Place a complete tool definition in a system message without content. The tool becomes available from that message onward.

Load a calculator dynamically

from typing import Any

dynamic_messages: list[dict[str, Any]] = [
    {"role": "user", "content": "Calculate 23 times 47."},
    {
        "role": "system",
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "calculate",
                    "description": "Evaluate an arithmetic expression",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "expression": {
                                "type": "string",
                                "description": "The arithmetic expression to evaluate",
                            }
                        },
                        "required": ["expression"],
                    },
                },
            }
        ],
    },
]
completion = client.chat.completions.create(
    model="kimi-k3",
    messages=dynamic_messages,
)

print(completion.choices[0].message.tool_calls)

Include the complete name, description, and parameters definition.
The declaration takes effect at its position in messages.
Keep this message in later request history; the server does not retain it.

See Dynamic Tool Loading.

1M context and automatic caching

Context caching is automatic for regular model requests; no cache ID, TTL, or extra parameter is required. Keep the long prefix unchanged so later requests can automatically attempt a cache hit.

from pathlib import Path

knowledge: str = Path("knowledge-base.md").read_text(encoding="utf-8")

for question in ["Summarize the key conclusions.", "List three implementation risks."]:
    completion = client.chat.completions.create(
        model="kimi-k3",
        messages=[
            {"role": "system", "content": knowledge},
            {"role": "user", "content": question},
        ],
    )
    print(completion.choices[0].message.content)

See Context Caching.

Official tools

Official tools are integrated through Formula:

Fetch tool definitions from the Formula /tools endpoint.
Add those definitions to the Chat Completions tools field.
When the model returns tool_calls, submit each function name and arguments to the Formula /fibers endpoint.
Add the complete assistant message and Fiber output as the corresponding tool message.
Call Chat Completions again until the model returns a final answer.

See Official Tools for the complete client and API contract. Web search is being updated and is not recommended for use in the near term.

Important limits

reasoning_effort currently supports only max; K3 always has thinking mode enabled.
max_completion_tokens defaults to 131072 and can be set up to 1048576.
temperature=1.0, top_p=0.95, n=1, presence_penalty=0, and frequency_penalty=0 are fixed; omit them from requests.
Return the complete assistant message unchanged in multi-turn conversations and tool calls.
Vision input does not support public image URLs. Use base64 or ms://<file-id>, and make content an array of objects.
Web search is being updated and is not recommended for production workflows in the near term.

FAQ

How is Kimi K3 billed?

Kimi K3 offers a 1M-token context and uses flat pay-as-you-go pricing — there is no tiering by context length. Input (with separate rates for cache hits and misses) and output are billed at uniform per-token prices. See Kimi K3 pricing.

Model Pricing

For token pricing details, refer to Model Pricing.

Thinking Effort

Configure reasoning_effort.

Vision Input

Send images and videos.

Structured Output

Use strict JSON Schema.

Partial Mode

Continue from a prefix.

Tool Choice

Control whether the model calls tools.

Dynamic Tool Loading

Inject tool definitions on demand.

Tool Calling Best Practices

Combine tool-calling features.

Official Tools

Integrate Formula tools.

Kimi K3 Pricing

Review input and output prices.

​Introducing Kimi K3

​Get started

​Basic call

​Thinking effort

​Streaming

​Vision input

​Structured output

​Partial Mode

​Custom tools and tool_choice

​Dynamic tool loading

​1M context and automatic caching

​Official tools

​Important limits

​FAQ

​Model Pricing

​Related docs

Thinking Effort

Vision Input

Structured Output

Partial Mode

Tool Choice

Dynamic Tool Loading

Tool Calling Best Practices

Official Tools

Kimi K3 Pricing

Introducing Kimi K3

Get started

Basic call

Thinking effort

Streaming

Vision input

Structured output

Partial Mode

Custom tools and `tool_choice`

Dynamic tool loading

1M context and automatic caching

Official tools

Important limits

FAQ

Model Pricing

Related docs