How to Use Kimi K3.1 Pro: API, Codex and Claude Code Setup, Pricing and Gotchas

Kimi K3.1 Pro is usable right now through the Kimi API, Kimi Code and kimi.ai, and for API users it is a straight upgrade: the model ID is kimi-k3.1-pro, the endpoint is the same OpenAI-compatible https://api.moonshot.ai/v1, and the list price is lower than K3 ($2 / $10 per million input / output tokens versus $3 / $15). The things that will trip you up are that it always thinks (you can only lower reasoning_effort, not turn reasoning off), it needs at least a $1 top-up before it unlocks, sampling parameters are fixed, and you must send the full assistant message back on every turn. This guide gets you from zero to a working call, then wires it into Codex and Claude Code, with the fixes for the errors you are most likely to see.

Key facts (from Moonshot’s official blog and API docs):

  • Models: kimi-k3.1-pro and kimi-k3.1-pro-highspeed (2-3x the speed of K3.1 Pro, per Moonshot). Both have a 1,048,576-token context window.
  • What it is: a post-trained version of Kimi K3 with substantially more post-training compute; Moonshot calls it its “most capable 3T-class open-weight model to date”.
  • Open weights: “will be released by Nov 4, 2026”. Today it is API and app only.
  • API price per 1M tokens: K3.1 Pro $2.00 input, $10.00 output, $0.20 cached input. Highspeed $4.00 / $20.00 / $0.20.
  • Access: unlocked after a successful top-up of at least $1. Rate limits depend on cumulative top-up tier.
  • Reasoning: always on. reasoning_effort accepts low, high, max (default max).

If you used K3 already, our Kimi K3 launch-day guide covers the original model, and the Kimi K3 local guide covers what serving a model of this size actually takes. Everything below is specific to K3.1 Pro.

1. What changed from K3, in one table

Moonshot describes K3.1 Pro as K3 plus a much larger post-training run (joint reinforcement learning across “hundreds of downstream domains”). For builders the practical differences are price, speed options and the benchmark claims below. All numbers are Moonshot’s own, from the Kimi K3.1 Pro tech blog; treat them as vendor-reported until independent leaderboards catch up.

Kimi K3Kimi K3.1 Pro
API model IDkimi-k3kimi-k3.1-pro (plus kimi-k3.1-pro-highspeed)
Context window1,048,576 tokens1,048,576 tokens
Input / output per 1M tokens$3.00 / $15.00$2.00 / $10.00
Cached input per 1M tokens$0.30$0.20
Cache write, 5m / 1h TTL per 1M$3.00 / $6.00$2.00 / $4.00
Terminal-Bench 4.0not in this comparison65.7% (vs. GPT-6 Astra 58.2%, Claude Opus 5.5 66.4%)
Kimi Code Bench 3.0 Long-horizon (internal)55.95%61.2%
BenchCAD, with toolsnot in this comparison92.7% (vs. Opus 5.5 96.2%, GPT-6 Astra 95.9%)

A few other claims from the blog worth knowing:

  • Finance and office work: Moonshot reports a state-of-the-art 64.4 on OfficeQA Pro v2, and internal gains over K3 of 7.2 points on financial modeling and 11.6 points on financial research.
  • Hallucinations: on an internal factual-accuracy stress test, the claim-level hallucination rate fell from 23.4% (K3) to 8.3% according to the tech blog. The API docs’ copy of the same section gives 23.35% to 6.85%, so the exact figure is not settled; the direction is the useful signal. Moonshot itself says these rates “do not represent overall error rates in daily use”.
  • Cyber capability was deliberately reduced for the open-weight release. Moonshot says it removed cyber-related data from mid-training and RL; on its internal exploit benchmark the unfiltered checkpoint solved 90.5% versus 81.0% for the released model.
  • Benchmark settings: Moonshot’s results use reasoning_effort max, temperature 1.0 and top_p 0.95, and the coding agents ran inside a Claude Code harness. If you run your own evals at low effort, expect lower numbers.

The money line for most teams: for the same token counts, K3.1 Pro lists one-third cheaper than K3. A request with 100,000 uncached input tokens and 10,000 output tokens costs $0.30 on kimi-k3.1-pro ($0.20 input + $0.10 output) versus $0.45 on kimi-k3 at list prices. Highspeed doubles the uncached input and output rates, so pick it only where latency matters more than cost.

2. Get access: top-up, API key, region

  1. Create an account on platform.kimi.ai. Moonshot runs separate regional platforms, and keys from different regions “are independent and cannot be mixed”. Keys from platform.kimi.ai only work with https://api.moonshot.ai/v1.
  2. Top up at least $1. The quickstart says K3.1 Pro “is unlocked after a successful top-up (minimum $1)”. Until you do, calls to the model will not work even with a valid key.
  3. Create an API key in the console and export it:
export MOONSHOT_API_KEY="sk-..."
  1. Know your tier before load-testing. Limits come from your cumulative top-up, per Moonshot’s Recharge and Rate Limits page:
TierCumulative top-upConcurrencyRPMTPMTPD
Tier0$113500,0001,500,000
Tier1$10151002,000,000Unlimited
Tier2$20401003,000,000Unlimited
Tier3$100502003,000,000Unlimited
Tier4$1,000602004,000,000Unlimited
Tier5$3,0001003005,000,000Unlimited

Tier0 is the trap: 3 requests per minute and a concurrency of 1. Moonshot’s troubleshooting page warns that with the OpenAI SDK’s default retries, “one failed request may consume the entire RPM quota” on a Tier0 account. If you plan to use K3.1 Pro inside a coding agent, which fires many requests per task, a $10 top-up to reach Tier1 is the realistic minimum. Vouchers do not count toward the cumulative total, and Moonshot adds a $5 voucher once cumulative top-up reaches $5.

Also note that a Kimi membership or Kimi Code subscription does not turn into API balance; the two are billed separately.

3. Your first call (cURL and Python)

The API is OpenAI-compatible, so the official OpenAI SDK works with a changed base_url.

cURL:

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

Python (the docs require Python 3.9+ and openai>=1.0):

python3 -m pip install --upgrade 'openai>=1.0'
import os
from openai import OpenAI

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

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

To use the fast variant, change only the model ID to kimi-k3.1-pro-highspeed.

Besides Chat Completions, the platform exposes a Responses API (POST /v1/responses, used by Codex) and an Anthropic-compatible Messages API at https://api.moonshot.ai/anthropic (used by Claude Code). Sections 7 and 8 use those.

4. Reasoning effort: the only “thinking” knob you get

K3.1 Pro always reasons. There is no way to switch thinking off; the docs’ FAQ answers “How do I turn off Kimi K3.1 Pro’s chain-of-thought?” with “You can’t”. What you control is the top-level reasoning_effort field:

ValueWhen to use it
max (default)Hard coding, math, long agent runs. This is what Moonshot benchmarks with.
highMost production work where you want lower latency than max.
lowSimple extraction, classification, short answers. Lowest latency and token use.
completion = client.chat.completions.create(
    model="kimi-k3.1-pro",
    reasoning_effort="low",
    messages=[{"role": "user", "content": "Classify this ticket as bug, feature or question: 'Export button does nothing'"}],
)

message = completion.choices[0].message
if hasattr(message, "reasoning_content"):
    print("REASONING:", getattr(message, "reasoning_content"))
print("ANSWER:", message.content)

Three details that matter:

  1. Leaving it unset means max. If you migrate K3 or K2 code and never set reasoning_effort, every call runs at maximum effort, which is the slowest and most token-hungry option. Set it explicitly.
  2. Don’t send a thinking parameter. That was the K2.x style. The docs say: “When migrating from K2.x to K3, remove the K2.x thinking configuration and use top-level reasoning_effort”. K3.1 Pro “does not support the thinking parameter”.
  3. Reasoning tokens cost money and share the output budget. reasoning_content “counts toward token consumption”, and the reasoning plus the answer together must fit inside max_completion_tokens.

The OpenAI SDK’s response types do not declare reasoning_content, which is why the official examples use hasattr and getattr instead of message.reasoning_content.

5. Fixed parameters, output limits and multi-turn rules

These are the limits from the K3.1 Pro quickstart that most often break ported code.

Sampling parameters are fixed. Omit them. temperature=1.0, top_p=0.95, n=1, presence_penalty=0 and frequency_penalty=0 are fixed. If your wrapper always sends temperature=0.2, strip it for this model rather than assuming it is honored.

Output length. max_completion_tokens defaults to 131,072 and can go up to 1,048,576 (minus your prompt tokens). max_tokens is deprecated in favor of max_completion_tokens; they mean the same thing. If a response looks cut off, check choices[0].finish_reason: length means you hit the cap, and since reasoning eats into the same budget, a long max-effort reasoning trace can leave little room for the answer. Raise the cap, lower the effort, or continue with Partial Mode (section 6).

Return the complete assistant message, every turn. K3.1 Pro runs with Preserved Thinking always on. In multi-turn chats and tool loops you must append the whole assistant message the API returned, including reasoning_content and tool_calls, not just content. The docs call this “required” for K3.1 Pro and K3. Frameworks that rebuild history from content strings alone will degrade or fail here; with the OpenAI SDK, appending the returned message object directly is the simplest fix:

messages = [{"role": "user", "content": "Plan a database migration from MySQL 8 to Postgres 17."}]
first = client.chat.completions.create(model="kimi-k3.1-pro", reasoning_effort="high", messages=messages)
messages.append(first.choices[0].message)   # whole message, not just .content
messages.append({"role": "user", "content": "Now list the three riskiest steps."})
second = client.chat.completions.create(model="kimi-k3.1-pro", reasoning_effort="high", messages=messages)
print(second.choices[0].message.content)

Preserved reasoning stays in the context window and is billed as input on later turns, so long sessions get more expensive per turn. This is where caching (section 6) pays off.

6. Streaming, tools, JSON, vision and caching

Streaming returns separate reasoning_content and content deltas; reasoning always arrives first, so the first content delta tells you thinking has finished:

stream = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[{"role": "user", "content": "Explain why the sky is blue."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    reasoning = getattr(delta, "reasoning_content", None)
    if reasoning:
        print(reasoning, end="", flush=True)
    if delta.content:
        print(delta.content, end="", flush=True)

stream_options.include_usage=true is what makes the final chunk carry the full cache read and write breakdown, per the context-caching guide.

Tool calling follows the OpenAI format. Use tool_choice="required" to force a tool call on the first turn, append the full assistant message, then add one role: "tool" message per call with the matching tool_call_id. Moonshot also supports dynamic tool loading: put a full tool definition in a system message without content mid-conversation, and it becomes available from that point on. Keep that message in later history, because the server does not retain it.

Structured output works with response_format={"type": "json_schema", "json_schema": {..., "strict": True}}. Parse only message.content, never reasoning_content.

Partial Mode lets you continue from a prefix: add a final assistant message with "partial": True, and prepend that prefix when you display the result. It is also the documented way to resume after finish_reason=length.

Vision: image and video input are supported, but public image URLs are not. Send base64 data URLs or upload a file and reference it as ms://<file-id>, and make content an array of objects, not a serialized string. This catches anyone porting OpenAI code that passes https://...jpg URLs.

import base64
from pathlib import Path

image_b64 = base64.b64encode(Path("screenshot.png").read_bytes()).decode()
completion = client.chat.completions.create(
    model="kimi-k3.1-pro",
    reasoning_effort="high",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{image_b64}"}},
            {"type": "text", "text": "What error is shown in this screenshot, and what is the likely fix?"},
        ],
    }],
)
print(completion.choices[0].message.content)

Context caching is automatic and billed in three parts: cache writes, cache hits and uncached input. The default TTL is 5 minutes. If your requests reuse a large prefix (a codebase, a knowledge base, a long system prompt) with gaps longer than 5 minutes, ask for the 1-hour tier:

completion = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[
        {"role": "system", "content": big_shared_prefix},
        {"role": "user", "content": "Summarize the key conclusions."},
    ],
    extra_body={"prompt_cache_options": {"mode": "implicit", "ttl": "1h"}},
)
u = completion.usage
print(u.prompt_tokens, u.prompt_tokens_details)  # look for cached_tokens / cache_write_tokens

The extra_body wrapper is just how the OpenAI Python SDK passes a field it does not know about; in raw JSON it is a top-level "prompt_cache_options": {"mode": "implicit", "ttl": "1h"}. Gotchas from Moonshot’s caching guide:

  • A 1h write costs twice a 5m write ($4.00 versus $2.00 per 1M on K3.1 Pro). Moonshot’s own chart shows 1h becoming the cheaper option after two cache hits.
  • A cache entry’s TTL is locked at first write. You cannot switch a prefix from 5m to 1h until the old entry fully expires.
  • Caches are stored in blocks; a partial block is never cached and is billed at the normal input rate.
  • Caches are shared within an organization, not across organizations, and cannot be cleared manually.

Web search: the quickstart currently says built-in web search “is being updated and is not recommended for production workflows in the near term”. Bring your own search tool for now.

7. Use K3.1 Pro in Codex

Moonshot’s Codex guide connects Codex straight to the Kimi Responses API, with no proxy. Install Codex CLI from OpenAI’s docs and start it once, then:

Step 1: set the key without leaving it in shell history.

echo "Paste your Kimi API key and press Enter (input is hidden):"
read -s KIMI_API_KEY
export KIMI_API_KEY

Step 2: add Kimi as a provider in ~/.codex/config.toml (on Windows %USERPROFILE%\.codex\config.toml). Replace existing model and model_provider values:

model = "kimi-k3.1-pro"
model_provider = "kimi"
model_context_window = 1048576

[model_providers.kimi]
name = "Kimi"
base_url = "https://api.moonshot.ai/v1"
env_key = "KIMI_API_KEY"
wire_api = "responses"

wire_api = "responses" is the setting that makes the direct connection work. model_context_window matters too: without it, Moonshot says Codex falls back to default model metadata, which can degrade performance.

Step 3: restart and verify. Codex only reads config.toml at startup.

cd /path/to/your/project
codex

Confirm the CLI shows kimi-k3.1-pro, send hello, then a real agent task such as “Inspect this repository and summarize its structure.” In Codex Desktop the model picker may say Custom; requests still go to kimi-k3.1-pro.

Codex troubleshooting, from Moonshot’s guide:

SymptomFix
401 UnauthorizedKey invalid, or key and base_url are from different platforms. Check the key is visible to Codex: test -n "$KIMI_API_KEY" && echo set || echo missing
404 on /v1/responsesbase_url must be exactly https://api.moonshot.ai/v1, with /v1, and not a leftover local router address
400 web_search.search_context_size is not supportedRemove search_context_size from your config
Warning Model metadata for kimi-k3.1-pro not foundExpected and harmless; model_context_window already covers it
Config changes ignoredRestart Codex; check no -c flags or profiles override it; if you used CC Switch, turn off Codex routing there or it rewrites the file

Codex CLI cannot send video input, though the model itself accepts video through the API.

8. Use Kimi in Claude Code (and what model you actually get)

Moonshot’s Claude Code guide uses the Anthropic-compatible endpoint. First check the endpoint and your key directly; the guide’s verification call already targets K3.1 Pro:

curl https://api.moonshot.ai/anthropic/v1/messages \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"model": "kimi-k3.1-pro", "max_tokens": 1, "messages": [{"role": "user", "content": "hi"}]}'

Then put the following in the env block of ~/.claude/settings.json and restart Claude Code. This is Moonshot’s documented configuration:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.moonshot.ai/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_MOONSHOT_API_KEY",
    "ANTHROPIC_MODEL": "kimi-k3[1m]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "kimi-k3[1m]",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "kimi-k3[1m]",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "kimi-k2.7-code",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "kimi-k3[1m]",
    "CLAUDE_CODE_SUBAGENT_MODEL": "kimi-k3[1m]",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
    "CLAUDE_CODE_EFFORT_LEVEL": "max"
  }
}

Which model is that? Moonshot’s troubleshooting page says direct API calls and Codex use kimi-k3.1-pro, “while Claude Code uses the compatible alias kimi-k3[1m]”. The docs do not spell out whether that alias now resolves to K3.1 Pro or to the original K3, so if the distinction matters for cost or quality, check the model reported in responses and your usage console, or run your agent through Codex or the API directly where the ID is explicit. Also note the HAIKU tier above uses kimi-k2.7-code, and K2-series models stop being available to newly registered users from October 31, 2026, with full retirement planned by the end of December 2026. Expect that line of the config to change.

Claude Code gotchas from the guide:

  • Set every tier variable. Missing ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_FABLE_MODEL or CLAUDE_CODE_SUBAGENT_MODEL makes background tasks and sub-agents request model names Kimi does not recognize, and they fail quietly.
  • The env block in settings.json overrides variables exported in your shell. Stale ANTHROPIC_* values there, or in ~/.zshrc / ~/.bashrc, are the most common reason a new config “doesn’t take effect”.
  • Remove any old ANTHROPIC_API_KEY so it does not conflict with ANTHROPIC_AUTH_TOKEN.
  • Run /status inside Claude Code: Base URL should show https://api.moonshot.ai/anthropic.
  • The file holds your key in plain text, so never commit it.

If you use Claude Code heavily, our Claude Code daily-driver guide covers the habits that keep long sessions cheap, which matters more with an always-reasoning model.

Kimi Code is the simplest route if you already pay for a Kimi membership: Moonshot says to run Kimi Code and select Kimi K3.1 Pro with the /model command. That is billed through the membership, not your API balance.

9. Troubleshooting the API

ProblemWhat it means and what to do
429 with rate_limit_reached_errorYou hit a concurrency, RPM, TPM or TPD limit for your tier. Slow down or move up a tier (section 2).
429 with engine_overloaded_errorServer-side capacity pressure. Topping up does not fix it. Honor Retry-After and back off exponentially. Requests interrupted by 429 are not charged.
Calls rejected right after creating a keyMake sure you have topped up at least $1; K3.1 Pro is locked until then.
401Wrong key, or a key from another regional platform. platform.kimi.ai keys only work with api.moonshot.ai.
Answer truncatedfinish_reason is length. Raise max_completion_tokens, lower reasoning_effort, or continue with Partial Mode.
Model “forgets” earlier reasoning or tool resultsYou are sending back only content. Append the complete assistant message, including reasoning_content and tool_calls.
Image request failsPublic URLs are not supported. Use base64 or ms://<file-id>, with content as an array.
Responses slow and expensiveYou are probably on the default max effort. Set reasoning_effort to high or low, or switch to kimi-k3.1-pro-highspeed for latency-bound work.

10. What about running it locally?

Not yet. Moonshot says the full K3.1 Pro weights “will be released by Nov 4, 2026”. (Separately, if you are on Kimi Enterprise, an administrator has to enable K3.1 Pro for your organization, because access is off by default at launch.) Since K3.1 Pro is a post-trained K3, the hardware picture in our K3 local guide is the best preview of what self-hosting will involve, but wait for the official model card for the exact files, license and recommended engines before planning hardware. We will follow up when the weights ship; new guides land on the 7minai homepage first.

FAQ

Do I need to pay to use the API? Yes. The API is pay-as-you-go with no subscription, and the model only unlocks after a minimum $1 top-up. The kimi.ai apps and Kimi Code are separate products with their own plans, and their benefits do not convert into API balance.

Is K3.1 Pro more expensive than K3? No. At list price it is cheaper: $2 / $10 per million input / output tokens versus $3 / $15 for kimi-k3. Highspeed costs $4 / $20.

Can I turn off thinking to save tokens? No. Set reasoning_effort to low instead. Not setting it at all gives you max.

Does it work with the OpenAI SDK? Yes. Point base_url at https://api.moonshot.ai/v1 and use model kimi-k3.1-pro. Drop temperature and the other fixed sampling parameters, and read reasoning_content with getattr.

How long is the context? 1,048,576 tokens for both K3.1 Pro variants, with flat per-token pricing and no long-context surcharge, according to the quickstart FAQ.

Sources