Kimi K3 API Complete Guide: 2.8T Reasoning Model, Pricing, and OpenAI-Compatible Integration (2026)

Kimi K3 is Moonshot AI's flagship model — 2.8 trillion parameters, a 1-million-token context window, native vision, and always-on reasoning. It launched on July 16, 2026, and the API is live today at https://api.moonshot.ai/v1. If you've used the OpenAI SDK before, you can make your first K3 call in under 3 minutes: point base_url at Moonshot's endpoint, swap your model ID to kimi-k3, and your existing code works.

We wrote this guide because K3 introduces a different API surface from the K2 family. The thinking parameter is gone; reasoning_effort replaces it. tool_choice: "required" is now supported. The context window jumps from 256K to 1M tokens. And the pricing model — $3/M input, $15/M output, flat across the entire context — changes the cost math for long-context workloads. These differences are small individually but trip you up fast if you're migrating from K2.

Sources: Kimi K3 Quickstart, retrieved 2026-07-18; Kimi K3 Pricing, retrieved 2026-07-18; Model Parameter Reference, retrieved 2026-07-18.

OpenAI-compatible means a provider exposes a chat-completions endpoint whose request and response shape matches the OpenAI API contract closely enough that an unmodified OpenAI SDK call works against it after swapping three values: API key, base URL, and model name. The minimum surface in practice is POST /v1/chat/completions with messages, model, and an OpenAI-shaped streaming response.

Getting Started in 3 Minutes

Step 1: Create an account. Go to platform.kimi.ai and sign up. Moonshot supports email and phone number registration.

Step 2: Get your API key. Navigate to the Console → API Keys page and create a new key. Copy it immediately — keys are shown once.

Step 3: Make your first call. Install the OpenAI Python SDK:

pip install --upgrade 'openai>=1.0'

Then run:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_MOONSHOT_KEY",
    base_url="https://api.moonshot.ai/v1",
)

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

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

That's it. The Kimi API implements the OpenAI Chat Completions specification — any tool, SDK, or code that speaks OpenAI's format works by changing the base_url and API key.

Source: Kimi K3 Quickstart, retrieved 2026-07-18.

Kimi K3 at a Glance: What's Different from K2

K3 is not just a bigger K2. The architecture, API surface, and pricing all changed. Here's the comparison:

Key changes to watch when migrating from K2:

1. thinking → reasoning_effort: K3 does not accept the K2-style thinking parameter. Use reasoning_effort: "max" instead (or omit it — max is the default).
2. Parameters are fixed: temperature, top_p, n, presence_penalty, and frequency_penalty cannot be modified on K3. Passing non-default values returns an error.
3. tool_choice: "required" is new: K3 supports forcing tool calls, which K2 models did not.

Source: Model Parameter Reference, retrieved 2026-07-18.

Reasoning Effort: How K3 Thinks

K3 always reasons. Every request produces reasoning_content in the response alongside the final content. You control the reasoning level with the top-level reasoning_effort field:

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

# Access reasoning trace
message = response.choices[0].message
if hasattr(message, "reasoning_content"):
    print("Reasoning:", message.reasoning_content)
print("Answer:", message.content)

Currently, "max" is the only supported value — more levels are coming. This is compatible with OpenAI's reasoning_effort field, so if your code already sets it, no rename is needed.

Cache behavior: Switching reasoning_effort levels (once more are available) may invalidate the prefix cache. Decide on the effort level before the conversation starts and avoid switching mid-session.

Source: Thinking Effort, retrieved 2026-07-18.

Pricing

K3 uses flat pricing across the entire 1M-token context window — no tiered pricing by context length:

For comparison with other frontier models:

K3's cache-hit rate at $0.30/M input makes long-context, multi-turn conversations significantly cheaper than cache-miss pricing suggests. Moonshot's automatic context caching kicks in without explicit configuration.

Sources: Kimi K3 Pricing, retrieved 2026-07-18; Artificial Analysis — Kimi K3, retrieved 2026-07-18.

Tool Calling and Dynamic Tool Loading

K3 introduces two tool-calling improvements over K2:

tool_choice: "required"

Force the model to call a tool on every turn — useful for retrieval-augmented workflows where the first step must always be a search:

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Find the latest pricing for Claude Opus 4.8"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "web_search",
            "description": "Search the web for current information",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "Search query"}
                },
                "required": ["query"]
            }
        }
    }],
    tool_choice="required",
)

Dynamic Tool Loading

Instead of declaring all tools upfront (which eats context), K3 supports injecting tool definitions mid-conversation via system messages. The pattern:

1. Start with a single search_tools function in tools
2. Set tool_choice: "required" on the first turn to force retrieval
3. Inject matched tool definitions via a system message with a tools field
4. Switch tool_choice back to "auto" for subsequent turns

This keeps your per-request token usage low even with hundreds of available tools.

Source: K3 Tool Calling Best Practices, retrieved 2026-07-18.

Vision Input

K3 natively handles images and video. Pass vision content as an array of objects in the content field:

Image Input

import base64
from pathlib import Path

image_data = base64.b64encode(Path("screenshot.png").read_bytes()).decode()

response = 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 what you see in this screenshot."},
        ],
    }],
)

Video Input

Upload a video file first, then reference it:

video = client.files.create(file=Path("demo.mp4"), purpose="video")

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

# Clean up
client.files.delete(video.id)

Source: Kimi K3 Quickstart — Vision Input, retrieved 2026-07-18.

Streaming

K3 streams reasoning_content and content as separate delta fields:

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(f"[thinking] {reasoning}", end="", flush=True)
    if delta.content:
        print(delta.content, end="", flush=True)

For multi-turn conversations, pass the complete assistant message (including reasoning_content and any tool_calls) back into the next request's messages array.

Source: Kimi K3 Quickstart — Streaming, retrieved 2026-07-18.

Structured Output and JSON Mode

K3 supports strict JSON Schema output via response_format:

import json

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Lin is 28 years old. Extract 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 = json.loads(response.choices[0].message.content or "{}")
print(person)  # {"name": "Lin", "age": 28}

Parse only message.content for structured output — reasoning_content is unstructured thinking trace and should not be JSON-parsed.

Source: Structured Output, retrieved 2026-07-18.

Common Errors and Fixes

Production Checklist

Before going to production with K3, verify:

• API key stored securely — never hardcode keys; use environment variables or a secrets manager
• Error handling for rate limits — implement exponential backoff on 429 responses
• Streaming consumer handles both deltas — reasoning_content and content arrive as separate fields
• Multi-turn message format — pass complete assistant messages (including reasoning_content) back in the conversation
• Fixed parameters removed — do not pass temperature, top_p, n, presence_penalty, or frequency_penalty
• thinking replaced with reasoning_effort — K2-style thinking parameter causes errors on K3
• Token budget awareness — K3 output at $15/M is 1.5x K2.6's output pricing; monitor output token usage
• Context caching strategy — Moonshot's auto-caching reduces input cost by 90% on cache hits; structure conversations to maximize prefix reuse
• Fallback configuration — set up fallback to K2.6 or an alternative provider for availability during K3's early launch period

TheRouter Integration

Moonshot is a verified provider in TheRouter. The existing K2 models (kimi-k2.6, kimi-k2.7-code) are already routable through our OpenAI-compatible gateway.

Kimi K3 is not yet in TheRouter's model registry. Once moonshot/kimi-k3 is added to models-data.ts, you'll be able to route K3 requests through TheRouter with automatic fallback to K2.6 or other providers:

# Future configuration once K3 is added to TheRouter
client = OpenAI(
    api_key="YOUR_THEROUTER_KEY",
    base_url="https://api.therouter.ai/v1",
)

response = client.chat.completions.create(
    model="moonshot/kimi-k3",  # Will route through TheRouter once supported
    messages=[{"role": "user", "content": "Hello from TheRouter!"}],
)

In the meantime, you can call K3 directly via the Moonshot API endpoint at https://api.moonshot.ai/v1, or access it through DashScope (Alibaba Cloud Model Studio) where it is listed as kimi/kimi-k3.

For fallback routing patterns — such as falling back from K3 to DeepSeek V4 or Claude when one provider has an outage — see our LLM API Fallback Routing Guide.

Sources: TheRouter Moonshot Provider, retrieved 2026-07-18; DashScope Newly Released Models, retrieved 2026-07-18.

Further Reading

• Kimi K3 vs Kimi K2: Upgrade Comparison — side-by-side analysis of what changed between generations
• Kimi K2 API Integration Guide — if you need K2-specific documentation
• Coding Agent Model Routing Comparison 2026 — how K3 stacks up against Claude Opus 4.8, DeepSeek V4, and GLM-5.2 for coding tasks
• Best Reasoning Models API Comparison 2026 — cross-provider reasoning model comparison

---

Last updated: 2026-07-18. Kimi K3 API is live. Full model weights release scheduled for July 27, 2026. TheRouter routing support for K3 is pending — check /providers/moonshot/ for the latest status.