Kimi K3 Complete Guide: From API Calls to Agent Building (2026 Practical Tutorial)

Kimi K3 Complete Guide: From API Calls to Agent Building (2026 Practical Tutorial)

Timeliness note: This article was updated on July 27, 2026. The full Kimi K3 model weights were officially open-sourced today, and the API is fully available.

On July 16, 2026, Moonshot AI officially released Kimi K3 β€” the world’s first open-source large language model at the trillion-parameter scale. Eleven days later today (July 27), the full model weights have been open-sourced, meaning developers worldwide can not only access and use this powerful model for free, but also fine-tune and deploy it on their own hardware.

As a developer, you now face an urgent question: How capable is Kimi K3 really? Is it worth switching from GPT-5.6 or Claude? And how do I integrate it into my projects?

This guide exists to answer those questions. I’ll walk you through everything from getting started with API calls, to building a complete Agent workflow step by step, and finish with an objective comparison against leading proprietary models. Whether you want to quickly try it out or seriously evaluate migrating your tech stack, this tutorial has the answers you need.


1. What Is Kimi K3?

1.1 A 2.8-Trillion-Parameter Open-Source Giant

Kimi K3 boasts 2.8 trillion (2.8T) total parameters, making it the largest and most capable open-source language model to date. In Kimi’s model evolution, it represents a qualitative leap:

  • 2023: Kimi supports 200K-character long text (a first in China)
  • 2024: Kimi k1.5 introduces reinforcement learning-based reasoning
  • 2025: Kimi K2 supports 128K context and basic Tool Calling
  • 2026.7: Kimi K3 β€” 2.8T parameters, 1M token context, native vision understanding

Kimi open-source model scale evolution{alt=β€œKimi K3 open-source model scale evolution: showing Kimi K3’s leading parameter scale among open-source models, with leapfrog growth from K1 to K3”}

Image source: Moonshot AI Official Tech Blog

Parameter count alone doesn’t equal capability β€” Kimi K3’s real breakthrough lies in its architecture design.

1.2 KDA Architecture: Making Large Models More Efficient

Kimi K3 uses the proprietary KDA (Kimi Delta Attention) architecture, with core innovations including:

Technical FeatureDescription
Delta AttentionIncremental computation on the attention mechanism, significantly reducing VRAM usage for ultra-long contexts
Attention ResidualsResidual connection optimization to mitigate gradient vanishing in deep networks
MoE Sparse ActivationOnly 16 out of 896 expert networks are activated per inference, making actual compute far less than 2.8T
Mixed Precision TrainingBF16 + FP8 mixed precision for improved training efficiency and inference speed

Kimi K3 architecture diagram{alt=β€œKimi K3 technical architecture: KDA attention mechanism and MoE sparse activation architecture diagram”}

Image source: Moonshot AI Official Tech Blog

The MoE (Mixture of Experts) design is key to Kimi K3’s efficiency β€” although total parameters reach 2.8T, only about 50B parameters are actually activated per inference. This means that with reasonable hardware configurations, inference speed and cost are far lower than what β€œ2.8T” might intuitively suggest.

1.3 Core Capabilities at a Glance

CapabilityDetails
Context Window1,048,576 tokens (1 million), supporting ultra-long documents and codebases
Vision UnderstandingNative support for image and video frame input, no external model needed
Tool CallingSupports custom function calls for building Agent workflows
Adjustable ReasoningThree levels: low / high / max, flexibly balancing speed and quality
Structured OutputSupports JSON Schema constraints for easy engineering integration
Streaming OutputSeparates reasoning deltas and answer deltas, reducing TTFB (time to first byte)
Partial ModeSupports continuing generation from a user-provided prefix
MultilingualDeeply optimized for Chinese and English, supports 100+ languages

2. Quick Start: Call the Kimi K3 API in 5 Minutes

2.1 Registration and API Key

The first step to calling the Kimi K3 API is obtaining an API Key:

  1. Visit the Kimi Open Platform and register an account
  2. Go to the API Keys management page
  3. Create a new API Key

Note: Using Kimi K3 requires a minimum top-up of Β₯10 to unlock the service (the Β₯15 coupon for new users is not applicable to K3). This ensures proper API usage and billing.

2.2 Your First Request: Python Example

The Kimi K3 API is fully compatible with the OpenAI SDK format, making migration virtually cost-free. Here’s the complete code for your first request:

from openai import OpenAI
import os

# Initialize the client, pointing to Kimi's API endpoint
client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.cn/v1",
)

# Send the first request
completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {
            "role": "user",
            "content": "Write a quicksort algorithm in Python with detailed comments"
        }
    ],
)

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

Run this script and you should receive a response from Kimi K3 within a second or two. If you’re already familiar with the OpenAI API, the code above should look very familiar β€” you only need to change two parameters: api_key and base_url.

2.3 Streaming Output and Reasoning Effort Configuration

In production applications, streaming output is practically standard β€” it lets users see results as the model generates content, greatly improving the experience.

# Streaming output + reasoning effort configuration
completion = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="max",  # Three levels: low / high / max
    stream=True,
    messages=[
        {"role": "system", "content": "You are a senior Python engineer."},
        {"role": "user", "content": "Explain what the GIL (Global Interpreter Lock) is and how it affects multithreaded programming"}
    ],
)

# Print output chunk by chunk
for chunk in completion:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

The reasoning_effort parameter is a signature feature of Kimi K3:

LevelUse CaseSpeedQuality
lowSimple Q&A, translation, summarizationFastestBasic
highCode generation, complex analysisMediumHigh
maxDeep reasoning, mathematical proofs, complex architecture designSlowerBest

It’s recommended to use max for tasks requiring deep thought (such as architecture design or complex bug investigation), and high for everyday interactions to get the best value.

2.4 Vision Understanding: Image and Video Input

Kimi K3 natively supports visual input without requiring additional vision models. This is extremely useful for scenarios involving screenshot analysis, charts, and UI design review.

# Image analysis example
completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Please analyze the UI design issues in this screenshot and provide improvement suggestions"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/screenshot.png"
                    }
                }
            ]
        }
    ],
)

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

You can also pass Base64-encoded local images:

import base64

def encode_image(image_path):
    with open(image_path, "rb") as f:
        return base64.b64encode(f.read()).decode("utf-8")

base64_image = encode_image("screenshot.png")

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Describe the content in this image"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/png;base64,{base64_image}"
                    }
                }
            ]
        }
    ],
)

3. Hands-On: Building an Agent with Kimi K3

Simply calling the API is just the beginning. The real value of Kimi K3 comes from using it as the core brain of an Agent, combined with Tool Calling to build automated workflows.

3.1 Agent Architecture Design

The scenario we’ll build is: an Agent that automatically collects industry news and generates a daily report.

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                  User Instruction                β”‚
β”‚  "Help me collect today's important AI industry  β”‚
β”‚   news and summarize them"                      β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                   β”‚
         β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”
         β”‚   Kimi K3 Agent   β”‚
         β”‚  (reasoning: max) β”‚
         β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                   β”‚ Decides which tools to call
         β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”
         β–Ό         β–Ό         β–Ό
   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”
   β”‚ Search β”‚ β”‚  Web   β”‚ β”‚Summary β”‚
   β”‚  Tool  β”‚ β”‚Scrapingβ”‚ β”‚  Tool  β”‚
   β””β”€β”€β”€β”€β”¬β”€β”€β”€β”˜ β””β”€β”€β”€β”¬β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”¬β”€β”€β”€β”€β”˜
        β”‚         β”‚          β”‚
        β–Ό         β–Ό          β–Ό
   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
   β”‚        Generated Report        β”‚
   β”‚  - Top 5 Industry Headlines    β”‚
   β”‚  - Key Insight Summaries       β”‚
   β”‚  - Trend Analysis              β”‚
   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

3.2 Tool Calling Implementation

Kimi K3’s Tool Calling interface is fully compatible with OpenAI’s tools parameter. Let’s implement the Agent described above:

from openai import OpenAI
import os
import json
import requests

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

# Define tools
tools = [
    {
        "type": "function",
        "function": {
            "name": "search_news",
            "description": "Search for the latest industry news",
            "parameters": {
                "type": "object",
                "properties": {
                    "keyword": {
                        "type": "string",
                        "description": "Search keyword, e.g., 'AI industry news'"
                    },
                    "count": {
                        "type": "integer",
                        "description": "Number of results to return, default 10"
                    }
                },
                "required": ["keyword"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "fetch_article",
            "description": "Fetch the content of a specified URL article",
            "parameters": {
                "type": "object",
                "properties": {
                    "url": {
                        "type": "string",
                        "description": "Article URL"
                    }
                },
                "required": ["url"]
            }
        }
    }
]

# Tool function implementations
def search_news(keyword, count=10):
    """Simulate news search (in production, integrate SerpAPI, Bing API, etc.)"""
    # Simplified here; in production, connect to a real search API
    return json.dumps([
        {"title": f"AI Industry Key News: {keyword}", "url": "https://example.com/news/1"},
        {"title": f"Tech Update: Latest progress on {keyword}", "url": "https://example.com/news/2"},
    ])

def fetch_article(url):
    """Simulate fetching article content"""
    return f"This is the full article content from {url}..."

# Agent main loop
def run_agent(user_query, max_turns=5):
    messages = [{"role": "user", "content": user_query}]
    tools_map = {"search_news": search_news, "fetch_article": fetch_article}

    for _ in range(max_turns):
        # Call Kimi K3
        response = client.chat.completions.create(
            model="kimi-k3",
            reasoning_effort="high",
            tools=tools,
            messages=messages,
        )

        msg = response.choices[0].message

        # If the model requests tool calls
        if msg.tool_calls:
            messages.append(msg)  # Add the model's response to message history

            for tool_call in msg.tool_calls:
                func_name = tool_call.function.name
                func_args = json.loads(tool_call.function.arguments)

                print(f"πŸ”§ Calling tool: {func_name}({func_args})")

                # Execute the tool function
                result = tools_map[func_name](**func_args)

                # Return tool results to the model
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": result
                })
        else:
            # Model has given the final answer
            return msg.content

    return "Maximum turn limit reached. Please simplify the task or increase max_turns."

# Run the Agent
result = run_agent("Help me collect today's important AI industry news, pick the 5 most important ones, and summarize the key insights")
print("\n" + "="*50)
print("πŸ“‹ Agent Output:")
print(result)

3.3 Advanced: Structured Daily Report Output

Combined with Kimi K3’s JSON Schema structured output capability, we can have the Agent directly produce formatted reports:

response = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="max",
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "daily_report",
            "schema": {
                "type": "object",
                "properties": {
                    "date": {"type": "string", "format": "date"},
                    "top_news": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "title": {"type": "string"},
                                "summary": {"type": "string"},
                                "source": {"type": "string"},
                                "importance": {"type": "integer", "minimum": 1, "maximum": 5}
                            }
                        }
                    },
                    "trend_analysis": {"type": "string"},
                    "action_items": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                },
                "required": ["date", "top_news", "trend_analysis"]
            }
        }
    },
    messages=[
        {
            "role": "user",
            "content": """Based on the following news summaries, generate a structured AI industry daily report:

1. Kimi K3 full weights open-sourced today, becoming the world's first 3T-class open-source model
2. OpenAI releases GPT-5.6 Sol update with further improved reasoning
3. Google DeepMind announces Gemini 3.5 technical roadmap
4. Multiple Chinese AI companies announce LLM API price cuts
5. EU AI Act enters Phase 2 compliance review"""
        }
    ],
)

report = json.loads(response.choices[0].message.content)
print(json.dumps(report, ensure_ascii=False, indent=2))

The output will strictly follow your defined JSON Schema and can be directly used for frontend display or downstream automation pipelines.

3.4 Debugging and Optimization Tips

When running Agents in production, the following tips can significantly improve stability and results:

  1. Set timeouts and retries: Network requests can fail; use openai.Timeout and retry logic
  2. Limit token consumption: Control per-turn output length via the max_tokens parameter
  3. Logging: Record parameters and results of each tool call for troubleshooting
  4. Fallback strategy: If Kimi K3 is temporarily unavailable, prepare a backup model (e.g., kimi-k2 or another alternative)
  5. Prompt templating: Extract System Prompts into templates for version management and A/B testing
# Timeout and retry example
from openai import OpenAI, Timeout

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.cn/v1",
    timeout=Timeout(30.0, connect=10.0),  # Total timeout 30s, connect timeout 10s
    max_retries=3,
)

4. Kimi K3 vs GPT-5.6 vs Claude Fable 5

How do you choose between three top-tier models? Let’s look at data and use cases.

4.1 Performance Comparison: Benchmark Data

BenchmarkKimi K3GPT-5.6 SolClaude Fable 5Notes
Frontend Code Arena167915901631Kimi K3 ranks #1 globally
Artificial Analysis Intelligence Index576265Claude and GPT slightly ahead
Math Reasoningβ˜…β˜…β˜…β˜…β˜†β˜…β˜…β˜…β˜…β˜…β˜…β˜…β˜…β˜…β˜…GPT-5.6 stronger in math
Code Generationβ˜…β˜…β˜…β˜…β˜…β˜…β˜…β˜…β˜…β˜†β˜…β˜…β˜…β˜…β˜†Kimi K3 leads in frontend code
Long Text Processingβ˜…β˜…β˜…β˜…β˜…β˜…β˜…β˜…β˜…β˜†β˜…β˜…β˜…β˜…β˜†1M tokens is a killer feature
Chinese Understandingβ˜…β˜…β˜…β˜…β˜…β˜…β˜…β˜…β˜…β˜†β˜…β˜…β˜…β˜†β˜†Kimi K3 deeply optimized for Chinese
Tool Calling Stabilityβ˜…β˜…β˜…β˜…β˜†β˜…β˜…β˜…β˜…β˜…β˜…β˜…β˜…β˜…β˜…Proprietary models have more mature tool calling

Data sources: Kimi Official Tech Blog, Frontend Code Arena public leaderboard, Artificial Analysis Intelligence Index. Benchmark data as of July 2026; models continue to iterate.

Conclusion: Kimi K3 has surpassed GPT-5.6 and Claude Fable 5 in frontend code generation and Chinese-language scenarios, ranking in the global top 3 for overall intelligence. For Chinese-speaking developers, Kimi K3 is an extremely cost-effective choice.

4.2 Pricing Comparison: Cost Analysis

ModelInput Price (Β₯/M tokens)Output Price (Β₯/M tokens)Context Pricing
Kimi K3~40~1201M context
Claude Fable 5~108~360200K context
GPT-5.6 Sol~72~216128K context

Key Findings:

  • Kimi K3’s output cost is only 1/3 of Claude Fable 5’s
  • Kimi K3’s output cost is roughly half of GPT-5.6 Sol’s
  • In long-context scenarios (1M tokens), Kimi K3’s cost advantage becomes even more pronounced

For teams processing 1 billion tokens daily, migrating from Claude to Kimi K3 could theoretically save hundreds of thousands of yuan in monthly expenditure.

4.3 Use Case Selection: When to Use Which?

ScenarioRecommended ModelReason
Chinese content creationKimi K3Deep Chinese understanding and long text capability
Frontend code generationKimi K3#1 on Frontend Code Arena globally
Math reasoning & researchGPT-5.6 SolStill leads in math benchmarks
Complex Agent orchestrationClaude Fable 5Most mature Tool Calling ecosystem
Ultra-long document analysisKimi K31M token context is unmatched
Multilingual (non-Chinese)GPT-5.6 SolBroader coverage of less common languages
Cost-sensitive scenariosKimi K3Lowest per-token cost

4.4 Migration Cost: Switching from OpenAI to Kimi

If you’re already using the OpenAI SDK, the cost of migrating to Kimi K3 is very low β€” the API format is nearly fully compatible:

# OpenAI version
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
response = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "Hello!"}],
)

# Migrate to Kimi K3: only 3 changes needed
client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],     # 1. Change API Key
    base_url="https://api.moonshot.cn/v1",      # 2. Change Base URL
)
response = client.chat.completions.create(
    model="kimi-k3",                             # 3. Change Model Name
    reasoning_effort="high",                     # Kimi K3-specific parameter
    messages=[{"role": "user", "content": "Hello!"}],
)

No need to rewrite business logic, no need to switch SDKs β€” just change a few configuration parameters and you’re running.


5. What Does Open-Source Mean?

Kimi K3 officially open-sourced its full model weights on July 27, 2026. What does this mean?

5.1 Possibilities for Local Deployment

After open-sourcing, teams with the right hardware can deploy Kimi K3 on their own servers, enabling:

  • Data Privacy: Sensitive data never leaves your premises; fully local inference
  • Customization: Fine-tune for specific industries or scenarios
  • No Dependencies: No reliance on third-party APIs; you control service availability

Practical hardware requirements: Thanks to MoE sparse activation, after quantization (INT4/INT8), the VRAM needed for inference drops significantly. It’s estimated that multiple A100/H100 GPUs can run the full model, which is feasible for enterprises with existing compute infrastructure.

5.2 Fine-Tuning and Customization

The greatest value of open-source models lies in the ability to fine-tune for vertical scenarios:

  • Legal industry: Inject legal codes and case law to train a specialized legal consulting model
  • Healthcare: Combine medical literature to train diagnostic assistance models
  • Enterprise knowledge bases: Inject company documents to train internal Q&A assistants

Kimi K3’s 896-expert MoE architecture means fine-tuning may only require training a subset of expert networks, dramatically reducing fine-tuning costs.

5.3 Impact on the AI Development Ecosystem

Kimi K3’s open-sourcing has a structural impact on the entire AI ecosystem:

  1. Lowering barriers to entry: Individual developers and startups can build products on world-class models
  2. Driving industry competition: Open-source model performance approaching proprietary leaders pushes companies like OpenAI and Anthropic to keep lowering prices
  3. Accelerating application innovation: More developers can experiment with cutting-edge directions like Agents and multimodal applications

6. Frequently Asked Questions

6.1 Is Kimi K3’s 1M Token Context Really Useful?

Extremely useful. 1 million tokens is roughly equivalent to:

  • 750,000 Chinese characters (approximately 1,500 A4 pages)
  • 500,000 English words
  • Approximately 1 million lines of code

This means you can:

  • Feed an entire project codebase to the model at once
  • Input a complete technical book for analysis and Q&A
  • Process large legal contracts or financial reports

By comparison, GPT-5.6 Sol’s context is 128K tokens and Claude Fable 5’s is 200K tokens β€” the gap is very significant.

6.2 When Can the Open-Source Weights Be Downloaded?

Starting today (July 27, 2026), Kimi K3’s full model weights are officially open-source. You can follow Moonshot AI’s official GitHub repository for download links. After the weights are released, Hugging Face and community mirror sites are expected to provide downloads within 1-2 days.

6.3 What Improvements Over Kimi K2?

DimensionKimi K2Kimi K3
Parameters~100B2.8T
Context128K1 Million
Vision UnderstandingNot supportedNative support
Tool CallingBasicEnhanced (custom functions)
Structured OutputNot supportedJSON Schema support
Adjustable ReasoningNot supportedSupported (low/high/max)
ArchitectureStandard TransformerKDA + MoE

K3 represents a comprehensive qualitative leap over K2, not just a parameter increase.


7. Summary

The release and open-sourcing of Kimi K3 marks another breakthrough for Chinese AI models in global competition. For developers, it offers:

  • βœ… Top-tier performance: #1 globally in frontend code, top 3 in overall intelligence
  • βœ… Extreme cost efficiency: API pricing at 1/3 of Claude’s and 1/2 of GPT’s
  • βœ… Ultra-long context: 1M tokens for processing lengthy documents and codebases
  • βœ… Low migration cost: Compatible with OpenAI SDK β€” just change a few parameters
  • βœ… Open-source freedom: Full weights downloadable, fine-tunable, deployable locally

If you’re a Chinese-speaking developer, especially in scenarios involving long text processing, code generation, or Agent workflow building, Kimi K3 deserves serious evaluation.

Reference Resources:


This article was updated on July 27, 2026. The AI model landscape changes rapidly β€” we recommend following the Kimi Official Documentation for the latest information.