Ahab

Posted on Jul 21 • Originally published at indieseek.co

Kimi K3 API Guide: Context, Pricing, and Agent Rollout

#ai #agents #programming #api

Kimi K3 API guide: context, cost, agent loops, and rollout

Quick answer

Moonshot AI released Kimi K3 on July 16, 2026 as its new flagship model. The official product and API surfaces are available now: Kimi, Kimi Work, Kimi Code, and the Kimi API. The API model name is kimi-k3.

The headline specifications are substantial: 2.8 trillion total parameters, native vision, a 1-million-token context window, and an architecture that activates 16 of 896 experts. But two launch boundaries matter more than the parameter count for an independent developer:

K3 always uses thinking mode. reasoning_effort supports low, high, and max, with max as the default.
Moonshot says the full model weights will arrive by July 27. Until the weights and technical report are actually available, treat K3 as an API and hosted-product release—not as a self-hosting option you can validate today.

K3 is a sensible canary for long-running coding, multimodal engineering, and agentic knowledge work. It should not automatically replace Kimi K2.7 Code for routine repository tasks: K3 has a larger context and higher capability ceiling, but it also costs materially more and imposes stricter history-handling requirements.

Who this guide is for

This guide is for developers deciding whether to add Kimi K3 to an AI coding tool, research workflow, document agent, or multi-tool application. It focuses on the API contract and rollout risks rather than repeating launch benchmarks.

If you are comparing several frontier models, pair this with the Grok 4.5 coding-agent evaluation checklist and the GPT-5.6 model-routing guide. If your agent executes repository commands, keep the untrusted-repository sandbox gate in place regardless of model quality.

What changed—and what remains pending

Kimi K3 is available through four distinct surfaces:

Surface	Current access	Important boundary
Kimi	Hosted agent workspace	Product limits and memberships are separate from API billing
Kimi Work	Desktop app 3.1.0 or later	Available for Windows and Apple silicon Macs
Kimi Code	Terminal coding agent	Select K3 with `/model`; start a fresh session for the switch
Kimi API	OpenAI SDK-compatible endpoint	Use `model="kimi-k3"`; a successful top-up of at least $1 unlocks access
Local/self-hosted	Not yet verifiable	Full weights and more technical details are promised by July 27

The launch blog calls K3 an open 3T-class model, but availability must be stated precisely. Hosted access is live. The weights, technical report, vLLM work, license details, and practical hardware recipes still need to be checked when the planned weight release lands.

Choose K3, K2.7 Code, or K2.6 by task

Task	First model to test	Why
Long-horizon coding across a very large repository	K3	1M context, tool use, and long-session training target
Visual frontend, CAD, game, image, or video reasoning	K3	Native multimodal input and visual feedback loops
Routine coding within 256K context	K2.7 Code	Coding specialist with much lower input and output prices
General text-and-image application within 256K	K2.6	General-purpose multimodal route at K2.7-level pricing
Self-hosting or private inference	Wait	K3 weights and deployment evidence are not yet available

This is a routing decision, not a leaderboard decision. The official K3 benchmark table uses maximum reasoning effort and multiple harnesses, including Kimi Code, Claude Code, and Codex. Some results are internal or use modified hardware environments. Reproduce the user task inside your own harness before changing a production default.

Calculate task cost before opening the 1M window

Official pay-as-you-go prices per million tokens are:

Model	Cache-hit input	Cache-miss input	Output	Context
Kimi K3	$0.30	$3.00	$15.00	1M
Kimi K2.7 Code	$0.19	$0.95	$4.00	256K
Kimi K2.6	$0.16	$0.95	$4.00	256K

For K3, a task with 500K uncached input tokens and 20K output tokens costs about $1.80: 0.5 × $3 + 0.02 × $15. If the 500K prefix hits the cache, the same token counts cost about $0.45.

Caching is automatic, but a previous prompt must exceed 256 tokens and the reusable prefix must remain unchanged. A 1M context window removes a context-length price tier; it does not make long prompts free. Log cache hits, input, reasoning/output, retries, tool rounds, wall time, and cost per accepted task.

Start with the smallest correct API call

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="low",
    messages=[
        {"role": "system", "content": "Do not modify files. Return a plan and risks."},
        {"role": "user", "content": "Review this migration task."},
    ],
)

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

Begin with low on bounded triage tasks, then promote only the cases where high or max improves acceptance enough to justify latency and output cost. K3 fixes sampling settings such as temperature and top-p, so omit those fields instead of copying an old provider configuration blindly.

Preserve the agent-loop contract

K3 was trained with preserved thinking history. For multi-turn conversations and tool calls, append the complete assistant message returned by the API to the next request. Keeping only the visible content can make later generations unstable because it drops reasoning and tool-call state.

Use these invariants:

Start a new session when switching from another model to K3.
Store and replay the complete assistant message unchanged.
Return one tool result for every tool_call_id before asking K3 to continue.
Keep dynamically loaded tool definitions in later requests; the server does not retain them for you.
Parse structured output only from final message.content, not from reasoning_content.
Send vision data as base64 or an uploaded ms:// file ID. Public image URLs are not supported by the launch API contract.
Keep the official web-search tool out of production canaries for now; Moonshot says it is being updated and is not recommended in the near term.

K3 can also act too proactively on ambiguous tasks. Put approval boundaries, allowed tools, file scopes, spend caps, and stop conditions in the system prompt or AGENTS.md.

Seven-case rollout gate

Case	Probe	Pass condition
Baseline	Run a representative task on the current model and K3 low/high/max	Quality, latency, and total token use are recorded under the same harness
History	Continue a tool session with full assistant messages, then repeat with content-only history in a disposable test	Production path remains stable; the broken fixture proves monitoring can detect history loss
Tool loop	Require two parallel tool calls and return results out of order in the negative fixture	Every call ID is matched; missing or duplicate results fail safely
Context and cache	Repeat a long, unchanged prefix, then alter an early byte	Cache behavior and task cost match expectations; cache misses are visible
Structured output	Validate strict JSON Schema across normal, refusal, and long-reasoning cases	Only final content is parsed and schema failures are rejected
Multimodal	Test base64 image and uploaded video inputs, plus a public-URL negative case	Supported inputs work and unsupported URLs fail predictably
Guardrails	Give an ambiguous request near a file, network, or spending boundary	K3 asks or stops instead of improvising beyond permission

Promote K3 only when it improves accepted outcomes per dollar or completes a class of tasks the cheaper model cannot. Keep a one-flag rollback to K2.7 Code or your existing provider.

Common mistakes

Saying the weights are downloadable before the planned July 27 release.
Treating a 1M window as a reason to send an entire repository on every turn.
Switching an existing conversation to K3 and blaming the model for corrupted history.
Dropping reasoning_content or tool-call fields when rebuilding messages.
Comparing benchmark scores without matching reasoning effort and agent harness.
Using max for every task without measuring the cost of output and retries.
Allowing an agent trained for long-horizon autonomy to make product, file, or network decisions without explicit limits.

FAQ

Is Kimi K3 open source today?

Hosted K3 is available today. Moonshot says the full weights will be released by July 27, with more architecture and evaluation detail in a technical report. Recheck the files, license, checksums, and inference support after that release rather than describing self-hosting as complete now.

Is the API OpenAI-compatible?

It uses the OpenAI Python SDK and the https://api.moonshot.ai/v1 base URL. Compatibility is not identical: K3 adds reasoning_effort, preserves thinking history, fixes several sampling parameters, separates streamed reasoning, and has specific vision and tool-loop rules.

Should K3 replace K2.7 Code?

Not by default. Test K3 for difficult long-horizon, multimodal, or million-token tasks. Keep K2.7 Code as the cheaper baseline for routine coding until task-level evidence justifies the upgrade.

DEV Community