Moonshot API Complete Guide: From Kimi K2 to K3 and Beyond

Bri Whitmore — Tue, 28 Jul 2026 04:55:32 +0000

Moonshot AI has rapidly evolved from a promising Chinese AI lab into one of the most important model providers in the global market. With the release of Kimi K3 in July 2026 -- a 2.8-trillion-parameter open-weight model leading on agentic benchmarks -- understanding the Moonshot API ecosystem has become essential for any developer working with AI.

This guide covers everything you need to know: the evolution from K2 to K3, API setup and authentication, model selection, pricing, rate limits, code examples, and how to integrate Moonshot models into your application.

The Kimi Model Family: K2 Through K3

Moonshot's model lineup has evolved through several generations. Understanding the differences helps you choose the right model for your task and budget.

Kimi K2.5

Parameters: 1 trillion (sparse MoE)
Context window: 256K tokens
Release: Early 2025
Positioning: K2.5 was Moonshot's first model to gain significant international attention. It competed respectably with GPT-4-level models on general reasoning and coding tasks but was not yet frontier-class on agentic benchmarks.
Best for: General chat, basic coding, Chinese-language tasks. Largely superseded by K2.7 and K3 for most use cases.

Kimi K2.6

Parameters: 1 trillion (sparse MoE)
Context window: 256K tokens
Release: Mid 2025
Positioning: An efficiency-focused iteration on K2.5. Moonshot reported that K2.6 reduced output token consumption by approximately 21% compared to K2.5 while maintaining or improving quality.
Best for: Cost-sensitive deployments where K2.5-quality reasoning is sufficient. The token efficiency improvement makes it notably cheaper to run at scale.

Kimi K2.7 Code

Parameters: 1 trillion (sparse MoE)
Context window: 256K tokens
Release: Early 2026
Positioning: A code-specialized variant. K2.7 Code targeted software engineering tasks specifically, competing with models like Claude Opus and GPT-4 on coding benchmarks.
Best for: Code generation, refactoring, debugging. Strong for single-turn coding tasks but less effective on multi-step agentic workflows compared to K3.

Kimi K3

Parameters: 2.8 trillion (sparse MoE)
Context window: 1 million tokens
Release: July 16, 2026
Positioning: A frontier model that leads on agentic benchmarks. K3 ranks #1 on BrowseComp (91.2) and Automation Bench (30.8), and #2 on AA-Briefcase (Elo 1543, behind only Fable 5). It represents a generational leap over the K2 series, not just an iteration.
Best for: Autonomous agents, web-browsing research tasks, multi-step automation, complex coding projects with large codebases, document-heavy knowledge work.
Architecture innovations: Kimi Delta Attention (KDA) and Attention Residuals (AttnRes) enable efficient processing of the 1M-token context window without the context-compression hacks some competitors require.

Moonshot API Setup and Authentication

Direct API Access

The Moonshot API is OpenAI-compatible, meaning you can use the standard OpenAI Python or Node.js SDK by changing the base URL:

from openai import OpenAI

client = OpenAI(
    api_key="your-moonshot-api-key",
    base_url="https://api.moonshot.ai/v1",
)

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain how attention mechanisms work in transformers."},
    ],
    max_tokens=4096,
)

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

// Node.js example
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'your-moonshot-api-key',
  baseURL: 'https://api.moonshot.ai/v1',
});

const response = await client.chat.completions.create({
  model: 'kimi-k3',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Explain how attention mechanisms work in transformers.' },
  ],
  max_tokens: 4096,
});

console.log(response.choices[0].message.content);

Account Requirements

Direct Moonshot API access requires:

A Chinese phone number for account verification
Chinese payment methods (Alipay, WeChat Pay) for billing
API documentation that is primarily available in Chinese

These requirements create friction for international developers. If you do not have Chinese credentials, using an API gateway is the practical alternative.

Access Through an API Gateway

For international developers, multi-provider gateways like TeamoRouter provide the simplest path to K3 access. You use the same OpenAI-compatible SDK but with the gateway's base URL and API key:

from openai import OpenAI

client = OpenAI(
    api_key="your-teamorouter-api-key",
    base_url="https://api.teamorouter.com/v1",
)

response = client.chat.completions.create(
    model="moonshotai/kimi-k3",  # or "kimi-k3" depending on gateway naming
    messages=[
        {"role": "user", "content": "Research the latest developments in fusion energy and summarize the key breakthroughs."},
    ],
)

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

The gateway handles procurement, billing, and failover on the back end. You get a standard international API that works with any payment method.

Moonshot API Pricing

Current Pricing (as of July 2026)

Model	Input (per 1M tokens)	Output (per 1M tokens)
Kimi K3	$3.00	$15.00
Kimi K2.7 Code	$1.50	$7.50
Kimi K2.6	$1.20	$6.00

K3's pricing is notably aggressive for a frontier model. Comparable closed models typically charge $10-15/M input and $30-75/M output. K3 undercuts those prices by 50-80% while matching or exceeding capability on agentic benchmarks.

A Note on K3 Token Consumption

Independent testers have noted that K3 currently operates at a single inference level ("max" mode) and can consume significant output tokens, especially on complex reasoning tasks. Moonshot's claim of 21% fewer output tokens compared to K2.6 applies to the architecture but real-world usage varies. Budget accordingly -- a complex agentic task with web browsing and multi-step reasoning can easily consume 10,000-50,000 output tokens.

Rate Limits and Reliability

Moonshot's API rate limits are not publicly documented in detail, but community reports suggest:

Free tier: Very limited, essentially a trial tier
Pay-as-you-go: Higher limits that scale with spending history
Enterprise: Custom limits with SLA guarantees

For production workloads, the reliability consideration extends beyond rate limits:

Moonshot's infrastructure is primarily China-based, which can introduce latency variability for international users (200-800ms typical from the US and Europe).
During high-demand periods, response times can spike.
No built-in failover if the Moonshot API experiences downtime.

These considerations make API gateways with automatic failover particularly valuable for production use of K3, as covered in the integration patterns section below.

Model Selection: When to Use Which Kimi Model

Use Case	Recommended Model	Reason
Autonomous web-browsing agents	K3	#1 BrowseComp, built for multi-step web research
Complex multi-file coding projects	K3	1M context handles large codebases; #1 Automation Bench
Document-heavy analysis (legal, financial)	K3	1M context fits entire documents; AA-Briefcase Elo 1543
Simple single-turn coding tasks	K2.7 Code	Sufficient capability at half the price of K3
Cost-sensitive high-volume chat	K2.6	Lowest cost; adequate for straightforward Q&A
Chinese-language applications	K3 or K2.6	All Kimi models have strong Chinese-language performance
Agentic task automation	K3	Automation Bench leader; purpose-built for multi-step execution

Function Calling and Tool Use

The Moonshot API supports function calling (tool use) through the standard OpenAI interface:

tools = [
    {
        "type": "function",
        "function": {
            "name": "search_documentation",
            "description": "Search the project documentation for relevant information",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The search query"
                    }
                },
                "required": ["query"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": "You are a coding assistant with access to documentation search."},
        {"role": "user", "content": "How do I configure Redis caching in the application?"}
    ],
    tools=tools,
    tool_choice="auto",
)

K3's strong tool-use performance is a key reason it leads on agentic benchmarks. The model is particularly good at deciding when to invoke tools, interpreting tool results, and chaining multiple tool calls into coherent multi-step workflows.

Streaming and Long-Running Requests

K3 supports streaming responses through the standard stream=True parameter:

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Write a detailed analysis of quantum computing's impact on cryptography."}],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

For long-running agentic tasks, consider implementing a polling or callback pattern rather than holding open a streaming connection, especially given the latency variability of China-based infrastructure.

Production Integration Patterns

Pattern 1: Direct-to-Moonshot (Simplest, If You Have Access)

Your App → Moonshot API (api.moonshot.ai)

Best for developers with Chinese credentials who only need K3 and can tolerate occasional downtime.

Pattern 2: Gateway with K3 Primary (Recommended for Most Teams)

Your App → TeamoRouter → Moonshot API (primary)
                      → Fallback Model (if K3 is unavailable)

You get K3 access without Chinese credentials, plus automatic failover and multi-model access through a single integration.

Pattern 3: Multi-Model Orchestration

Your App → TeamoRouter → K3 (for research/browsing tasks)
                      → Claude (for code generation)
                      → GPT (for creative/general tasks)

Route each task to the best model for that job. This is the pattern that maximizes performance-per-dollar across a diverse workload.

The Future: Beyond K3

Moonshot has established a pattern of rapid iteration -- K2.5, K2.6, K2.7 Code, and K3 all released within roughly 18 months. The open-weight release of K3 suggests Moonshot is committed to the open model approach, which means the community can expect:

Community fine-tuned variants of K3 for specialized domains
Third-party optimized inference engines delivering lower latency and cost
Integration with local deployment frameworks like Ollama, vLLM, and llama.cpp

For developers, the practical takeaway is to adopt K3 through a flexible integration layer -- an API gateway or routing platform -- so that when Moonshot releases K3.5 or K4, you can adopt it immediately without changing your application code.

Get Started with Kimi K3 Today

TeamoRouter gives you instant access to Kimi K3 through a standard OpenAI-compatible API. No Chinese phone number, no Alipay, no separate accounts for every model. One API key unlocks K3 alongside Claude, GPT, Gemini, DeepSeek, and 200+ other models.

Production-ready K3 access with automatic failover
Multi-model routing -- use the best model for each task
Unified billing -- one invoice, all models
International payment methods -- credit cards, not Alipay

Start building at teamorouter.com.

DEV Community: Bri Whitmore