Kimi K3 for builders.
The measurements, configs, and tests that gate it.

The launch threads will do the usual thing: screenshot the benchmark table, argue about it for a week, and never route a single real task to the model. This guide is for the other group, the people who actually ship.

Done right, your heaviest long-context work drops to a fraction of frontier prices. Done lazily, you pay closed-frontier rates for an open model with known UX gaps. The whole difference is in the engineering. Here is the full setup.

What actually shipped, in plain terms

Moonshot AI released its new flagship on July 17. The quick facts, drawn from the official launch materials and the technical report:

• The model. A Mixture-of-Experts with 2.8 trillion total parameters, 896 experts, and only 16 active per token. Marketed as the world’s first open 3T-class model, and it is, by a wide margin.
• Context: 1,048,576 tokens. Pricing is reported flat across the whole window, with no long-context premium tier, so an 800K-token prompt bills at the same rate as an 8K one. Worth confirming on the platform, since Moonshot has historically priced by context-length tier.
• Input: text and images natively. Vision is first-class, not a bolt-on.
• Reasoning: always on. The K2.x thinking toggle is gone, replaced by a reasoning_effort parameter, max-only at launch, with low and high promised in later updates.
• Where to use it. Kimi.com, Kimi Code, and the API at api.moonshot.ai/v1 with model id kimi-k3 (confirm the base URL for your region). OpenAI-compatible chat-completions surface with function calling, tool_choice, and streaming.
• Open weights. Promised July 27, shipped in MXFP4 (weights) with MXFP8 activations, alongside a technical report and a vLLM implementation.

Under the hood, the architecture story is real: Kimi Delta Attention (a hybrid linear attention mechanism), Attention Residuals (selective retrieval of representations across model depth), and a Stable LatentMoE routing framework, plus Gated MLA, Per-Head Muon, and a Sigmoid Tanh Unit activation. Moonshot reports roughly a 2.5x scaling-efficiency gain over K2, which is the only reason a 1M-token context is economical to serve at this scale.

The numbers, and how to read them

Read the deltas, not the decimal places. And read the provenance first: with one exception, the figures below are illustrative and directional, synthesized from the launch narrative and our own engineering brief. They are not vendor-confirmed scores. The only number here that traces to Moonshot’s published material is DeepSWE 67.3 (marked †). Treat everything else as a claim to verify, including every competitor column.

† DeepSWE 67.3 is the one figure anchored to Moonshot’s published material. Every other cell is illustrative.

The pattern these numbers describe, if it holds up, is worth internalizing:

1. K3 clears K2.7 by a wide margin everywhere. The biggest jump is on multi-hour maintenance (+11.2 pts), exactly where long agent runs live.
2. K3 leads the entire open-weight field on coding (past DeepSeek, Llama, Qwen).
3. On SWE Marathon, K3 runs level with Claude Fable 5 and ahead of GPT-5.6 Sol. For deep, multi-file refactors it is a genuine alternative, not a fallback. Note this “level” result is specific to SWE Marathon; on DeepSWE the closed leaders are still a few points ahead.
4. On the hardest terminal, reasoning, and knowledge tasks, the closed leaders still win. The gap is up to about 7 points on terminal work, narrowing to roughly 1 to 3 points on reasoning, math, and knowledge.

One caveat that builds trust instead of hype: apart from DeepSWE, these are illustrative, not independently verified, and Moonshot’s own tech blog admits K3 trails Fable 5 and GPT-5.6 Sol on overall polish. Treat every chart as a claim until independent evals land, and better, until your evals land.

The price math that decides everything

This is the section to slow down on, because K3 breaks the entire K2 framing.

The K2 line’s pitch was frontier-adjacent coding at a tenth of the closed price. K3’s sticker is different:

• $3.00 per 1M input tokens (cache-miss).
• $15.00 per 1M output tokens.
• $0.30 per 1M input tokens on cache hits, a 10x reduction.

That sticker sits in the closed-flagship neighbourhood: broadly comparable to the other leaders on a per-token basis, while carrying a 1M window and native vision. Exact cross-vendor multiples move with each flagship’s current price sheet, so compare against your incumbent’s real rates, not a headline ratio. What K3 is not is cheap relative to its own lineage: it is 5x to 6x K2.7’s pricing ($0.60 / $2.50). Anyone still quoting the “tenth of the price” line is quoting a stale model.

So the entire cost case moved to one place: the cache-hit rate on your traffic.

Moonshot reports above 90% cache-hit rates on coding workloads. At 90% hits, your blended input cost is:

blended_input = 0.90 × $0.30 + 0.10 × $3.00 = $0.57 / 1M tokens

That is an effective bill roughly 80% below the cache-miss headline for context-reusing workloads ($0.57 is about 81% off $3.00). On a caching-friendly agent loop, K3 undercuts the closed frontier. On a cache-hostile one (prompts that churn, preambles that shuffle, context rewritten every call), it will not.

Two more launch-week notes worth banking. First, pricing is reported flat across the 1M window, with no long-context premium; confirm that on the platform before you rely on it. Second, Moonshot is reportedly running a launch-window bonus on API top-ups, so if you want to test cheaply, check the current terms and expiry rather than trusting a forwarded figure.

The kickoff config (copy this)

K3 speaks an OpenAI-compatible surface, so integration is a config change plus an eval pass, not a rewrite. Point any OpenAI-compatible client at it:

from openai import OpenAI

client = OpenAI(
    api_key=MOONSHOT_API_KEY,
    base_url="https://api.moonshot.ai/v1",  # confirm the base URL for your region
)

response = client.chat.completions.create(
    model="kimi-k3",
    # "max" is non-standard for the OpenAI reasoning_effort enum (low/medium/high).
    # If your SDK version rejects it, pass it through instead:
    #   extra_body={"reasoning_effort": "max"}
    reasoning_effort="max",           # only option at launch; low/high promised later
    messages=[
        {"role": "system", "content": STABLE_PROJECT_CONTEXT},  # never changes
        {"role": "user", "content": task},                      # varies per call
    ],
    tools=TOOL_SCHEMAS,
    tool_choice="auto",
    stream=True,
    stream_options={"include_usage": True},  # required to get usage when streaming
)

The one migration note from K2.x: delete the old thinking toggle from your adapter and expose reasoning_effort instead. That is the whole diff in a well-abstracted provider layer.

Engineering the cache hit (this is the actual work)

The cache matches on identical prompt prefixes. Identical prefixes bill at $0.30/M instead of $3/M. So the job is to restructure every agent loop so the stable part comes first and never changes, and the variable part comes last:

def build_messages(task, history):
    return [
        # ---- STABLE PREFIX: byte-identical across every call ----
        {"role": "system", "content": SYSTEM_PREAMBLE},   # versioned, frozen
        {"role": "system", "content": CODEBASE_DIGEST},   # regenerated nightly, not per-call
        {"role": "system", "content": TOOL_USAGE_GUIDE},  # static
        # ---- VARIABLE SUFFIX: append-only ----
        *history,                                          # never rewrite past turns
        {"role": "user", "content": task},
    ]

Cache-killers to hunt down in code review:

• Timestamps or request IDs in the system prompt. One changing byte at position 0 invalidates everything after it.
• Re-ranking or re-summarizing history every call. K3 preserves thinking history across turns and was trained expecting it. Rewriting the transcript both misses cache and can degrade quality. Append, do not rewrite.
• Tool schemas generated in nondeterministic order. Sort your keys.
• Per-user personalization near the top of the prompt. Move it below the shared preamble.

Then instrument the hit rate as a first-class cost metric. The usage field names are provider-specific, so confirm Moonshot’s actual response shape (a DeepSeek-style API, for example, exposes prompt_cache_hit_tokensinstead of the OpenAI cached_tokens field):

# Field names below follow the OpenAI shape; verify against Moonshot's response.
cached = usage.prompt_tokens_details.cached_tokens
total  = usage.prompt_tokens
hit_rate = cached / total

metrics.gauge("k3.cache_hit_rate", hit_rate, tags=[f"route:{route}"])
metrics.gauge(
    "k3.effective_input_cost_per_1m",
    (cached * 0.30 + (total - cached) * 3.00) / total,
)

If k3.cache_hit_rate averages below 70% on an agent route, K3 is probably the wrong model for that route, or the prompt architecture is broken. Either way, now you know.

Where K3 fits your stack, and where it doesn’t

Moonshot’s own candor gives you a clean routing rule. They admit K3 trails Fable 5 and GPT-5.6 Sol on the hardest terminal and reasoning work. That honesty tells you exactly how to route:

Long-context reading, repo-wide analysis, doc synthesis  →  Kimi K3
    (1M window at flat rate, cache hits at $0.30)
Multi-hour / multi-file maintenance & refactors          →  Kimi K3
    (level with Fable 5, ahead of GPT-5.6 Sol on SWE Marathon)
Agent loops with repeated context                        →  Kimi K3 via cache hits
Vision-in-the-loop agents (screenshots, diagrams, UI)    →  Kimi K3
Hardest terminal work, security-sensitive reasoning      →  closed frontier
Data residency / air-gapped / fixed-cost-at-scale        →  K3 self-hosted (MXFP4)
Quick, cheap edits and everyday tasks                    →  your current mid-tier model

And route it, do not marry it: K3 should be one option behind a vendor-neutral provider layer, picked at runtime, with a closed-model fallback for the steps that still need it.

What model engineers can try first

If you have an afternoon, these are the experiments that tell you the most about whether K3 belongs in your stack, ordered from cheapest signal to biggest commitment. Each is designed to produce a number you can defend, not a vibe.

The launch-week catches

Four things the hype posts skip, all from the official docs and Moonshot’s own blog:

1. reasoning_effort is max-only at launch. Every request burns full thinking output at $15/M, so short tasks are quietly expensive until the lighter tiers ship. Keep quick edits elsewhere for now.
2. The benchmarks are self-reported, or illustrative. Independent evals only started landing this week. Treat every chart as a claim until third parties confirm, and re-run on your own tasks regardless.
3. Preserved thinking history is load-bearing. K3 was trained expecting its reasoning history kept in context across turns. Strip or compress it in your pipeline and quality can degrade. Check your framework’s transcript handling before production.
4. Weights are not downloadable yet. July 27 is a promise, not a link. And realistically, self-hosting a 2.8T MoE, even MXFP4-quantized, is a GPU-fleet commitment. For most teams the openness matters as optionality (residency, exit rights, auditability), not day-one self-hosting.

The testing criteria: what to measure before production

This is the part most write-ups skip entirely. Moonshot’s report is unusually candid about two failure modes: over-proactiveness on ambiguous tasks (doing more than asked) and sensitivity to thinking-history preservation. That candor is a gift: it tells you exactly where to point your eval suite. Benchmarks average these problems away; your users will not.

Run this acceptance suite on your real tasks, gated before any traffic shifts.

1. Instruction adherence and proactiveness probes

Feed K3 deliberately under-specified tasks and measure scope creep:

PROBES = [
    "Fix the failing test in auth_test.py",  # does it also 'refactor' auth.py?
    "Rename this variable",                   # does it reformat the whole file?
    "Summarize this RFC",                     # does it start proposing changes?
]

def score_scope(diff, allowed_paths):
    touched = set(files_in(diff))
    allowed = set(allowed_paths)
    return {
        "in_scope": touched <= allowed,
        "excess_files": len(touched - allowed),
        "excess_lines": lines_outside(diff, allowed),
    }

2. Thinking-history sensitivity

Run the same 20-task agent suite twice, once with reasoning history preserved verbatim, once with your framework’s default compression, and diff the pass rates.

3. Cache economics under real traffic

Replay a week of production prompts through the K3 adapter in shadow mode.

4. Long-context integrity

Do not trust the 1M window blindly. Plant retrieval targets at the 5%, 50%, and 95% positions of a real codebase dump and measure recall; then run a multi-file refactor at 200K, 500K, and 800K prompt sizes.

5. Vision-in-the-loop (if you use it)

Screenshot-to-action loops on your actual UI: dashboard reading, design-review diffs, error-state recognition.

6. Production observability (non-negotiable)

A model in production without observability is roulette. Instrument, at minimum:

• Cost per call: tokens in and out, dollars, sliced by feature, tenant, and route.
• Cache-hit rate: a first-class metric with alerts on regression.
• Latency p50 / p95 / p99: real distributions, not averages. Max-effort reasoning has a long tail; know yours.
• Continuous eval pass rates: the same suite that gated the release, running on live traffic.
• Prompt and completion logs: PII-scrubbed, shipped to your SIEM, retention matched to your compliance window.

7. Governance line items

A frontier-scale open model from a China-based lab needs diligence, not a reflex in either direction: licence sign-off, content-policy and refusal-behaviour probes in the eval suite, and provenance and supply-chain review of any weights you self-host. For many product workloads it clears the bar; for some regulated ones it will not. Decide with evidence.

Common mistakes

• Testing it with chat questions. A 2.8T MoE with a 1M window shows you nothing on “write me a function.” Feed it a whole repo or a research corpus. That is the class of work it is built for.
• Ignoring the cache pricing. Naive prompting pays $3/M every time. Structured prefixes pay $0.30 on repeats. Same model, 10x difference on agent workloads.
• Quoting the benchmarks as fact. They are self-reported or illustrative, and the vendor itself says it trails Fable 5. Repeating “beats everything” from launch threads is how you end up community-noted.
• Moving all traffic overnight. Route one workload class first (long-context reading is the obvious pick), compare quality and cost for a week, then expand.
• Forgetting the effort catch. Max-only reasoning means K3 overthinks trivial tasks at full output price. It is the heavy machine; keep it on heavy work.
• Rewriting the transcript mid-run. Thinking-history preservation is both a quality feature and a cache feature. Append-only or bust.

The 15-minute plan

1. Grab an API key and top up inside any active bonus window.
2. Wire the OpenAI-compatible config above into your provider layer behind a feature flag.
3. Restructure one heavy prompt for cache hits: stable prefix, variable task last.
4. Run your biggest long-context job on K3 and on your current model.
5. Compare output and cost, then add the routing block if K3 earns it.

Then schedule the real work: the seven-part acceptance suite above, on your tasks, before any production traffic moves.

The bottom line

K3 changes the question from cheap to capable. It is the first open 3T-class model, it runs level with the closed frontier on multi-hour maintenance and within a few points elsewhere on long-horizon coding, and its economics are genuinely excellent, but only if you engineer for the cache and verify the hit rate on your own traffic.

Sources and further reading

• Moonshot AI, Kimi K3 launch post
• Cloudflare Workers AI, moonshotai/kimi-k3 model card
• OpenRouter, moonshotai/kimi-k3
• Kensink Labs, Kimi K3 technical brief