Kimi K3 API Tutorial: 1M Context, Pricing & Python (2026)

Kimi K3 is Moonshot AI’s newest flagship model. It stretches the context window all the way to 1 million tokens and bakes in native vision plus always-on reasoning, aiming squarely at “long-horizon coding + knowledge work + complex reasoning.” This guide follows a simple path — get a key, send your first request, make the most of the 1M context, work out the real cost, and migrate from K2 — so you can actually get Kimi K3 running. In a hurry? Grab free credits with a referral code on GetModel and call Kimi, GPT and Claude with a single key.

What Kimi K3 offers

Kimi K3 uses a Mixture-of-Experts (MoE) architecture with roughly 2.8T total parameters, activating 16 of its 896 experts per pass. Paired with a new KDA (Kimi Delta Attention) + Attention Residuals attention design, Moonshot claims overall training/inference scaling efficiency is about 2.5x better than K2. In practical terms, a few things are worth remembering up front:

• 1M context window — precisely 1,048,576 tokens, enough to swallow a mid-sized codebase, a full manual or dozens of long documents in one shot. This is the most obvious upgrade over K2 (256K).
• Native vision — image and video input are supported directly, making it a first-class citizen for “look at the image, write the code” tasks like front-end, games and CAD, with no bolted-on OCR.
• Always-on reasoning — K3 has deep thinking enabled by default, controlled via reasoning_effort. Only the max tier is available for now (the default); the other tiers ship later.
• OpenAI-compatible API — Chat Completions format, so existing openai SDK code usually only needs the base_url and model changed to switch over.

The current primary model ID is kimi-k3. Before integrating, it’s worth checking the available model list in the console — Moonshot iterates quickly.

Integration steps + code

There are two paths below: direct integration suits Kimi-only setups; an aggregator gateway suits you if you also use GPT, Claude or Gemini and don’t want to juggle a pile of keys and invoices.

Option 1: Direct integration (Moonshot platform)

1. Sign up and log in at the Moonshot Open Platform;
2. Create a key under “API Key management”;
3. Note the endpoints: https://api.moonshot.cn/v1 (domestic) and https://api.moonshot.ai/v1 (overseas).

curl example:

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

Python (using the openai SDK directly — only base_url and model change):

import os
from openai import OpenAI

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

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

For streaming just add stream=True — the SSE format matches OpenAI’s — and function calling uses OpenAI’s tools field as usual.

Option 2: Aggregator gateway (call Kimi / GPT / Claude with one key)

If your project uses more than just Kimi, an aggregator gateway like GetModel saves a lot of hassle: one key, one OpenAI-compatible endpoint, and switching models means only changing the model field. Balance is shared across all models, and there’s a single invoice.

1. Log in to the GetModel Console and create a key starting with sk- on the “API tokens” page;
2. Change base_url to https://getmodel.ai/v1;
3. Set model to kimi-k3.

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-GetModel-key",
    base_url="https://getmodel.ai/v1",
)

# Call Kimi K3
resp = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Hello, Kimi K3"}],
)
print(resp.choices[0].message.content)

# Same code — swap model for gpt-5.2 or claude-opus-4-8 to switch providers

The gateway has built-in multi-channel failover, automatically switching when an upstream provider hiccups — steadier for production.

Making the most of 1M context and native vision

Long context is K3’s core selling point. Dropping an entire repo, a full contract or dozens of PDF pages straight into messages and letting the model answer with the full context is often simpler — and loses less information — than slicing it up yourself for RAG. Keep in mind that the longer the context, the higher the per-request token cost and latency, so any fixed prefix (a long system prompt, reference docs) should absolutely be reused via caching — see the pricing section below.

Vision input has two things to watch: first, image/video content must go into content as an array of objects, not concatenated into one serialized string; second, K3’s vision input does not support public image URLs — use base64 for local images, and upload videos via the files API, then reference them as ms://<file-id>.

resp = client.chat.completions.create(
    model="kimi-k3",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Write the matching HTML/CSS from this design mockup"},
            {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}},
        ],
    }],
)

Pricing comparison: direct vs. aggregator

Kimi K3 is billed per token and context caching is on by default — once a repeated prefix hits the cache, the input price drops to a tenth. Below is the official reference pricing (per 1M tokens, in RMB; the console’s live price is authoritative):

Billing item	Price / 1M tokens
Input (cache miss)	¥20
Input (cache hit)	¥2
Output	¥100

A few things worth noting:

• A cache hit pushes input down to ¥2/M, so for long system prompts and fixed documents called repeatedly, the real cost can be an order of magnitude lower than it looks — long-horizon agents benefit most;
• K3 is a flagship-tier model, so its output price is clearly higher than K2’s. For pure-throughput tasks that don’t demand top-end capability, the K2 series is still more economical (see Kimi K3 vs K2 comparison);
• Prices on official and various relay/aggregator channels fluctuate, so check the live price before you commit. See Kimi’s and other models’ live rates on GetModel’s pricing page.

Free credits: Moonshot’s ¥15 new-user credit cannot currently be used on K3 — official K3 access is paid. To try K3’s capabilities at zero cost, register through GetModel’s referral code for a free credit that works across all models, so you can benchmark K3, GPT and Claude side by side before picking your main driver.

Migrating from K2

If you’re switching from K2 / K2.x to K3, there are three pitfalls to avoid:

• Stop using the thinking parameter. K3 controls thinking effort via reasoning_effort (only max for now); K2.x’s thinking field doesn’t apply on K3.
• In multi-turn conversations and tool calls, add the full assistant message the API returns back into the next round as-is — don’t keep only content, or the reasoning/tool state is lost.
• The context budget grew 4x (256K → 1M), but don’t mindlessly fill it — longer means pricier and slower, so the trimming and cache reuse you’d normally do still matter.

Common errors and troubleshooting

• 401 / auth failure: a mistyped key, a missing Bearer prefix, or a key from a different environment. Check that the Authorization header and base_url match.
• 429 / rate limited: over your RPM/TPM or concurrency limit. Add exponential backoff retries, lower concurrency, or raise your account tier; via GetModel, multi-channel failover spreads the load automatically.
• Vision request errors: usually a public image URL was passed, or the mixed text/image content was concatenated into a string. Switch to base64 / ms:// references and use an array of objects.
• Context overflow: input exceeding 1M tokens throws an error. Trim the input, process in segments, or enable cache reuse for fixed prefixes.

FAQ

• How big is Kimi K3’s context? 1,048,576 tokens (about 1M), four times K2’s — ideal for whole-repo code, long documents and long-horizon agents.
• Does K3 have free credits? The official ¥15 credit can’t currently be used on K3; registering through GetModel gets you a cross-model credit, good for try-before-you-buy.
• Does it support vision, tool calls and streaming? All three. Vision uses an array of objects + base64/ms://; tool calls use OpenAI’s tools field; streaming adds stream=True.
• Can I reuse my existing OpenAI code? Yes. K3 is compatible with the OpenAI Chat Completions API, usually needing only base_url and model changed; but when migrating from K2, remember to swap thinking for reasoning_effort.
• How do I choose between K3 and K2? For 1M context, native vision and the strongest code/reasoning, pick K3; for pure throughput and cost sensitivity, pick the K2 series.

To use Kimi, GPT, Claude and Gemini from one codebase while maintaining a single key and a single invoice, start at the GetModel Console and use your bonus credit to get Kimi K3 running first.