Skip to main content
Kimi K3 is Moonshot AI’s flagship model and the first open-weight model in the 3-trillion-parameter class, at 2.8 trillion total parameters. It is built for frontier intelligence work: long-horizon coding, end-to-end knowledge work, and deep reasoning. It accepts both text and image inputs, thinks by default, and holds a 1M-token context window. The model ID is moonshotai/Kimi-K3. Pricing is $3.00 per 1M input tokens, $15.00 per 1M output tokens, and $0.30 per 1M cached input tokens, flat across the full context window. Together AI is working directly with the Moonshot team on this model.

Call Kimi K3

Thinking is on by default, so give max_tokens real headroom. The reasoning trace and the answer share the same completion budget, and a tight cap spends the whole allowance on reasoning and returns empty or truncated content.

Set the thinking effort

K3 thinks by default at reasoning_effort="max". Lower the level to cut cost and latency:
  • "low": shallow reasoning. Use for short, high-volume calls.
  • "high": deep reasoning. Use for most coding and analysis work.
  • "max": maximum reasoning, the default. Use for the hardest planning, architecture, and multi-step agentic problems, and set max_tokens generously.
The levels are coarse dials rather than a strictly monotonic scale, so measure token counts on your own prompts before you tune. Invalid effort strings are accepted silently instead of returning an error, so validate the value in your own code. To skip thinking entirely on trivial turns, pass reasoning={"enabled": False}. No thinking tokens are generated or billed.
For broader guidance on reasoning controls and prompting, see Reasoning.

Stream the reasoning trace and the answer

K3 returns two channels. The thinking trace arrives on reasoning_content and the final answer arrives on content. Handle both, and skip chunks where choices is empty, since Together emits a final usage-only chunk. K3 emits the trace under reasoning_content to match Moonshot, while other Together models use the newer reasoning alias. Reading both keys makes one handler work across models.
Display layers can render either channel. JSON parsers must read content only. History replay requires both, as described in Preserve the thinking history.

Send images

K3 has native visual understanding. Pass content as an array of objects and supply the image as either a public URL or a base64 data URL. Together fetches public URLs server-side.
Vision limits:
  • There is no limit on the number of images per request, but the whole request body must stay under 100 MB. This is the binding constraint when you inline base64.
  • 4K (4096x2160) is the recommended maximum resolution. Higher resolutions cost processing time and tokens without improving understanding.
  • Token cost scales with resolution.
  • A public URL is fetched with a plain server-side HTTP GET, so hosts that block unfamiliar clients return an error. Fall back to base64 for those.
Moonshot also publishes Perception Bench, a visual reasoning benchmark, if you want to evaluate K3’s visual understanding yourself.

Constrain the output to a schema

Pass a JSON schema through response_format with "strict": True to constrain the final content. Keep max_tokens generous. The whole thinking trace is spent before the first schema-constrained token is emitted, so a tight cap truncates the JSON rather than the reasoning. Parse content only, never reasoning_content.
The looser {"type": "json_object"} mode also works when you only need syntactically valid JSON.

Call tools

Declare functions in tools. When the model returns tool_calls, append the complete assistant message to history, append one tool message per call with the matching tool_call_id, then call again. tool_choice accepts four forms: Set tool_choice="required" on the first turn to force a tool call, then switch back to "auto". Changing tool_choice between turns does not invalidate the prefix cache. message.model_dump(exclude_none=True) is the line that matters below. It round-trips the assistant turn whole, including reasoning_content, which K3 depends on. See Preserve the thinking history.

Load tools dynamically

K3 can pick up a tool mid-conversation. Place a complete tool definition (full name, description, and parameters) inside a system message that carries a tools field and no content. The tool becomes available from that message’s position onward. Rules to follow:
  • Dynamic declarations use exactly the same format as the top-level tools field.
  • The system message must have empty content. Sending both content and tools on it returns 400: a system message with dynamic tools must have empty content.
  • Declarations apply per request and are not retained by the server. Keep the message in later request history yourself. Keeping it preserves both the tool’s availability and the cached prefix; dropping it means the model can no longer call that tool and the changed prefix may miss the cache.
  • Append declarations at the tail of messages. Appending does not affect the cached prefix, while removing or modifying an earlier declaration may hurt cache hits from that point onward.
  • Keep at least one tool in the top-level tools array whenever you send tool_choice.
Don’t put dozens or hundreds of tool definitions into every request. They eat context and make the model more likely to pick the wrong tool. Use search-then-inject instead:
  1. At conversation start, declare a single search_tools function backed by your own catalog, plus a few core tools, and advertise the searchable domain tags in the system prompt.
  2. On the first turn, set tool_choice="required" to force retrieval before answering.
  3. Inject the full definitions of the matching tools through a system message based on the retrieval results.
  4. Let the model call the loaded tools directly in later generations.
Decide reasoning_effort before the conversation starts, since changing it mid-conversation costs you cache hits.
Python

Work with the 1M context and the cache

K3 accepts up to 1M input tokens on Together, and context caching is automatic. There is no cache ID, TTL, or extra parameter. Keep your long prefix (system prompt, knowledge base, repo dump) byte-stable across requests so later calls hit the cache. Moonshot reports cache hit rates above 90% in coding workloads, which pulls effective input cost toward the $0.30 floor. Moonshot recommends placing fixed bulk context such as knowledge documents at the very beginning of the messages array, ahead of the system message, then appending questions and replies after it. Read the usage counters defensively. The *_details objects come back as plain dicts on some responses, and completion_tokens_details is absent entirely when you disable reasoning.
Python

Preserve the thinking history

K3 was trained in preserved thinking history mode, so the trace is state that the next turn depends on. Return the complete assistant message on every turn, reasoning_content included. If you keep only content, generation quality becomes unstable. Together accepts the trace back under either reasoning_content (what K3 emits) or the newer reasoning alias.
Python
Drop the trace from the replay and the model answers with a freshly invented number instead, because the commitment lived in the reasoning rather than in content.
Don’t switch an ongoing session over to K3 from another model. K3 inherits a history that contains no K3 thinking at all, and quality degrades. Start K3 sessions on K3.

Sampling parameters

Most sampling parameters are fixed server-side. Omit them and let the defaults apply.

Architecture

Two architectural changes form K3’s backbone, both aimed at moving information through longer sequences and deeper into the network:
  • Kimi Delta Attention (KDA): A hybrid linear attention mechanism that provides an efficient foundation for scaling attention across very long contexts. This is Moonshot’s first model to support a 1M context window.
  • Attention Residuals (AttnRes): Selectively retrieves representations across model depth rather than accumulating them uniformly.
On top of that, Moonshot pushed mixture-of-experts (MoE) sparsity further with the Stable LatentMoE framework, activating 16 of 896 experts. At roughly 2% of experts active per token, routing and optimization become first-order problems, so four supporting techniques keep training stable at 2.8T scale:
  • Quantile Balancing: Derives expert allocation directly from router-score quantiles, which eliminates heuristic updates and a sensitive balancing hyperparameter.
  • Per-Head Muon: Extends the Muon optimizer to optimize attention heads independently for more adaptive learning at scale.
  • Sigmoid Tanh Unit (SiTU): Improves activation control.
  • Gated MLA: Improves attention selectivity.
K3 continues a sustained scaling push: in nine of the twelve months from July 2025 to July 2026, Kimi models set the upper bound of open-model scale. At 2.8T parameters, K3 is the largest open-weight model released to date.

Use cases

K3 is strongest where a task runs long and needs little supervision:
  • Long-horizon coding: Sustained engineering sessions, navigation of massive repositories, and orchestration of terminal tools.
  • Vision in the loop: Iterating between code and live screenshots for game development, frontend engineering, and CAD, using visual feedback rather than a written description of the render.
  • Research pipelines: Reviewing literature, implementing a numerical pipeline, cross-validating results, and producing an interactive deliverable in one run.
  • End-to-end knowledge work: Deep research reports with interactive charts, timelines, and slides rather than a paragraph of prose.
  • Large-repository refactoring: Cross-file, multi-step engineering work held together by the 1M context window.
  • Agentic tool orchestration: Long tool-calling loops with reasoning between steps and tools loaded on demand.

Limitations

  • Cost on short, high-volume calls: Thinking defaults to "max", so a pipeline that never sets reasoning_effort pays the maximum reasoning bill on every call. Reasoning tokens bill as output at $15.00 per 1M. Drop trivial calls to "low" or disable reasoning outright.
  • Excessive proactiveness: K3’s training emphasizes long, difficult tasks, so it may make decisions on your behalf when it hits a minor issue or ambiguous intent mid-task. State hard constraints explicitly in the system prompt or in AGENTS.md.
  • Mid-session model swaps: Switching an in-flight session to K3 from another model leaves it without any K3 thinking history and destabilizes output.
  • Cache fragility: Restructuring earlier messages or editing an earlier tool declaration breaks the prefix cache and reprices the affected input from $0.30 to $3.00 per 1M tokens.

Usage tips

Next steps

Reasoning

Control reasoning depth and handle reasoning output across models.

Function calling

Build tool-calling loops against any function-calling model.

Vision

Send images to vision models and read the results.

Serverless models

Browse every model, context length, and price on serverless inference.