Kimi K3 Complete Guide: From API Calls to Agent Building ...

On July 16, 2026, Moonshot AI (月之暗面) released Kimi K3 — a massive open-source model with 2.8 trillion parameters. On July 27, the full model weights were officially open-sourced, making it the world’s first 3T-class open-source model.

Kimi K3 isn’t just “bigger.” It outperforms GPT-5.6 and Claude Fable 5 across multiple benchmarks, while API costs run at just one-third of Claude’s.

This guide walks you through using Kimi K3 in real projects: from API registration and basic calls, to building a complete Agent, and finally comparing the three major models to help you pick the right one.

1. What Is Kimi K3?

1.1 A 2.8 Trillion Parameter Open-Source Behemoth

Core specs of Kimi K3:

Metric	Value
Total Parameters	2.8 trillion (2.8T)
Context Window	1 million tokens
Activated Parameters	16 out of 896 experts per inference
Architecture	KDA (Kimi Delta Attention)
Open Source Status	Full weights open-sourced 2026-07-27

What does this mean for you? You can get performance close to or even beyond GPT-5.6 at a lower cost, with fully open weights you can deploy locally and fine-tune.

1.2 KDA Architecture: How to Make Large Models More Efficient

Kimi K3 uses an entirely new KDA (Kimi Delta Attention) architecture, paired with MoE (Mixture of Experts) sparse activation:

896 Experts: The model contains 896 independent expert networks
Sparse Activation: Each inference activates only 16 of them
Attention Residuals: Preserves key attention info to avoid long-context forgetting

This design lets Kimi K3 maintain 2.8T total parameters while drastically reducing actual inference cost. You only pay for the parameters you actually use, not all of them.

1.3 Core Capabilities at a Glance

Ultra-long context: 1M tokens — handle an entire book or large codebase in one pass
Native visual understanding: Supports image and video input, not just text
Tool Calling: Supports custom tool calls for Agent building
Adjustable reasoning effort: Three tiers — low, high, max — choose as needed
Structured output: JSON Schema constraints for controlled output formatting
Streaming output: Separates reasoning and answer tokens so you can see the thinking process in real time

2. Getting Started: Call the Kimi K3 API in 5 Minutes

2.1 Registration and API Key

Step 1: Go to the Kimi API Platform and register an account.

Step 2: Navigate to the API Keys management page and create a new API key.

Step 3: Top up at least 10 CNY to unlock Kimi K3 (note: the 15 CNY credit given to new users cannot be used for K3 — real top-up is required).

Step 4: Install the OpenAI SDK (Kimi K3 is fully compatible with the OpenAI format):

pip install openai

2.2 Your First Request: Python Example

Create a file called kimi_test.py:

from openai import OpenAI
import os

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

# Basic call
completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Write a quicksort algorithm in Python"}
    ],
)

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

Set the environment variable before running:

export MOONSHOT_API_KEY="your-api-key-here"
python kimi_test.py

You’ll see Kimi K3 return the complete quicksort code.

2.3 Streaming Output and Reasoning Effort Configuration

Kimi K3 supports reasoning effort control, letting you decide how “deep” the model thinks:

completion = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="max",  # low / high / max
    stream=True,
    messages=[
        {"role": "user", "content": "Analyze the performance bottleneck in this code"}
    ],
)

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

Reasoning effort recommendations:

low: Simple Q&A, fast responses (lowest latency)
high: General coding tasks, document generation (balanced)
max: Complex reasoning, code review, architecture design (highest quality)

2.4 Visual Understanding: Image and Video Input

Kimi K3 supports native visual understanding — you can pass images directly:

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What's in this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.jpg"
                    }
                }
            ]
        }
    ],
)

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

You can also pass Base64-encoded images:

import base64

with open("screenshot.png", "rb") as f:
    image_base64 = base64.b64encode(f.read()).decode()

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

3. In Practice: Building an Agent with Kimi K3

Agents are one of Kimi K3’s core use cases. Through Tool Calling, you can have the model invoke custom tools to complete complex tasks.

3.1 Agent Architecture Design

Let’s build an “Industry Information Research Agent” that can:

Search for the latest news in a specific industry
Extract key information
Generate a structured report

Tool definitions:

search_news(query): Search industry news
extract_key_info(text): Extract key information
save_report(content): Save report to file

3.2 Tool Calling Implementation

Kimi K3’s Tool Calling syntax is fully compatible with OpenAI:

import json
from openai import OpenAI

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 news in a specific industry",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Search keyword, e.g. 'AI healthcare'"
                    }
                },
                "required": ["query"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "save_report",
            "description": "Save a report to a file",
            "parameters": {
                "type": "object",
                "properties": {
                    "filename": {
                        "type": "string",
                        "description": "Filename, e.g. 'report.md'"
                    },
                    "content": {
                        "type": "string",
                        "description": "Report content"
                    }
                },
                "required": ["filename", "content"]
            }
        }
    }
]

# Simulated tool implementations
def search_news(query):
    # In a real project, this would call a search API
    return f"Latest news about {query}: 1. AI healthcare breakthrough... 2. New drug approval accelerated..."

def save_report(filename, content):
    with open(filename, "w", encoding="utf-8") as f:
        f.write(content)
    return f"Report saved to {filename}"

# Agent main loop
def run_agent(task):
    messages = [
        {"role": "system", "content": "You are an industry information research assistant. Based on user needs, search for news, extract key information, and generate reports."},
        {"role": "user", "content": task}
    ]
    
    while True:
        completion = client.chat.completions.create(
            model="kimi-k3",
            messages=messages,
            tools=tools,
            reasoning_effort="high",
        )
        
        response = completion.choices[0].message
        
        # If the model requests a tool call
        if response.tool_calls:
            messages.append(response)
            
            for tool_call in response.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 tool
                if func_name == "search_news":
                    result = search_news(**func_args)
                elif func_name == "save_report":
                    result = save_report(**func_args)
                else:
                    result = "Unknown tool"
                
                # Return tool result to model
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": result
                })
        else:
            # Model gives final answer
            print("\n✅ Final answer:")
            print(response.content)
            break

# Run the Agent
run_agent("Research the latest developments in the AI healthcare industry and generate a Markdown report")

3.3 Full Code Example: Industry Research Agent

The code above demonstrates the core Agent logic. In a real project, you’ll need to:

Replace search_news: Connect to a real search API (SerpAPI, Bing Search, etc.)
Add error handling: Tool calls can fail — implement retry logic
Limit iterations: Prevent the Agent from calling tools indefinitely
Logging: Record input and output for each tool call

3.4 Debugging and Optimization Tips

Problem 1: Agent stuck in an infinite loop

Fix: Set a maximum iteration count (e.g., 5)

Problem 2: Tool calling parameter errors

Fix: Provide more detailed parameter descriptions and examples in tool definitions

Problem 3: Responses too slow

Fix: Lower reasoning_effort to low or high

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

4.1 Performance Comparison: Benchmark Data

Benchmark	Kimi K3	GPT-5.6 Sol	Claude Fable 5
Frontend Code Arena	1679	1650	1631
AI Intelligence Index	57	59	58
Programming (composite)	Open-source #1	Commercial #1	#2

Key takeaways:

Kimi K3 ranks first globally in frontend code generation
Overall intelligence is slightly below GPT-5.6 and Claude Fable 5, but the gap is small
Among open-source models, Kimi K3 leads by a wide margin

4.2 Pricing Comparison: Cost Analysis

Model	Output Price (CNY/million tokens)	Relative Cost
Kimi K3	~120	Baseline
GPT-5.6 Sol	~216	1.8x
Claude Fable 5	~360	3x

Cost advantage: Kimi K3’s API cost is just one-third of Claude Fable 5 and half of GPT-5.6. For high-frequency usage, this can save thousands of CNY per month.

4.3 Scenario-Based Selection: When to Use Which?

Choose Kimi K3 when:

Budget is tight and you need high-frequency calls
Frontend code generation, coding assistance
Ultra-long context is needed (1M tokens)
Local deployment or fine-tuning is desired

Choose GPT-5.6 when:

You need the highest overall intelligence
The most mature ecosystem matters
Multimodal tasks (images, audio, video)

Choose Claude Fable 5 when:

Long text understanding and generation
The most natural conversational style
Security requirements are critical

4.4 Migration Cost: Switching from OpenAI to Kimi

Kimi K3 is fully compatible with the OpenAI SDK format — migration is straightforward:

# Original OpenAI code
from openai import OpenAI
client = OpenAI(api_key="sk-...")

# Switch to Kimi K3
from openai import OpenAI
client = OpenAI(
    api_key="your-moonshot-key",
    base_url="https://api.moonshot.cn/v1",
)

Just change the base_url and api_key. Everything else stays the same.

5. What Does Open Source Mean?

5.1 The Possibility of Local Deployment

With full weights open-sourced on July 27, you can:

Deploy Kimi K3 on your own GPU cluster
Run fully offline — your data never leaves your premises
Apply custom inference optimizations to reduce latency

Estimated hardware requirements:

Full model: 8× A100 80GB or higher
Quantized version (INT8): 4× A100 80GB might work
Community quantized versions (GGUF): Consumer GPUs may support partial functionality

5.2 Fine-Tuning and Customization

Open-source weights mean you can:

Fine-tune on domain-specific data
Adapt to internal enterprise knowledge bases
Optimize performance for specific tasks

Community tutorials and tools for fine-tuning are expected in the coming weeks.

5.3 Impact on the AI Development Ecosystem

Kimi K3’s open-source release will:

Lower AI application costs: Developers have more choices and aren’t locked into a single vendor
Accelerate innovation: The community can build new tools and applications on top of Kimi K3
Drive competition: Other model providers will need to cut prices or improve performance

6. Frequently Asked Questions

6.1 Is a 1M Token Context Window Actually Useful?

A 1M token context window means:

You can process an entire book (~700K tokens) in one go
You can analyze large codebases (dozens of files)
You can have long conversations without the model forgetting earlier content

In practice, place key information in the first half of the context — models tend to be more attentive to content at the beginning and end.

6.2 When Can I Download the Open-Source Weights?

On July 27, 2026, the full model weights have been open-sourced. Expect downloads on Hugging Face or ModelScope.

6.3 What Improvements Over Kimi K2?

Kimi K3 vs K2:

Parameters: 1T → 2.8T
Context window: 128K → 1M
Added native visual understanding
30% faster inference speed
Significantly enhanced tool calling capabilities

References

As of July 27, 2026, Kimi K3 is one of the most powerful open-source models available. If you’re looking for a cost-effective AI API or want to deploy a large model locally, Kimi K3 is well worth a try.

Questions? Feel free to join the discussion in the comments.

#Kimi K3 #Open Source LLM #AI API #Agent Building #Moonshot AI