Kimi

https://platform.kimi.ai/docs
Admin
Kimi is an AI platform providing language model inference services with multimodal support,...
Tokens:427,573
Snippets:2,540
Trust Score:9.4
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install OpenAI SDK

Source: https://platform.kimi.ai/docs/guide/kimi-k3-quickstart

Install the OpenAI SDK (version 1.0 or later) required by the examples. Run this before initializing the client.

```bash
python3 -m pip install --upgrade 'openai>=1.0'

```

--------------------------------

### Install OpenAI SDK and initialize client

Source: https://platform.kimi.ai/docs/llms-full.txt

Install the OpenAI SDK (Python 3.9+ required) and initialize the client once. The client is reused by later Python examples.

```bash
python3 -m pip install --upgrade 'openai>=1.0'
```

```python
import os

from openai import OpenAI

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

--------------------------------

### Go example

Source: https://platform.kimi.ai/docs/api/list-models

Uses the net/http package to send a GET request with an Authorization header. Prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.moonshot.ai/v1/models"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### MoonPalace startup log output

Source: https://platform.kimi.ai/docs/llms-full.txt

Example output shown when MoonPalace starts successfully. The displayed address should be used as the base_url; for the default port, set base_url=http://127.0.0.1:9988/v1.

```console
[MoonPalace] 2024/07/29 17:00:29 MoonPalace Starts {'=>'} change base_url to "http://127.0.0.1:9988/v1"
```

--------------------------------

### Initialize Kimi client in Node.js with openai library

Source: https://platform.kimi.ai/docs/llms-full.txt

Node.js setup for the Kimi large language model client using the openai library. Requires installing the openai package and setting the MOONSHOT_API_KEY environment variable; the base URL is https://api.moonshot.ai/v1.

```javascript
const axios = require('axios');
const openai = require('openai'); // You need to install the openai library

const client = new openai.OpenAI({
    apiKey: process.env.MOONSHOT_API_KEY, // Set the MOONSHOT_API_KEY environment variable before running this example
    baseURL: "https://api.moonshot.ai/v1",
});
```

--------------------------------

### Python tool-call setup with OpenAI client and tools definition

Source: https://platform.kimi.ai/docs/guide/use-kimi-api-to-complete-tool-calls

Python example that sets up the OpenAI client with the Moonshot API and defines a `tools` list with a `search` function. The `MOONSHOT_API_KEY` environment variable must be set before running. The code is part of the tool-execution loop example.

```python
from typing import *

import json
import httpx
import os

from openai import OpenAI


client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"], # Set the MOONSHOT_API_KEY environment variable before running this example
    base_url="https://api.moonshot.ai/v1",
)

tools = [
	{
		"type": "function", # The field type is agreed upon, and currently supports function as a value
		"function": { # When type is function, use the function field to define the specific function content
			"name": "search", # The name of the function, please use English letters, numbers, plus hyphens and underscores as the function name
			"description": """ 
				Search for content on the internet using a search engine.

```

--------------------------------

### Install MoonPalace with go install

Source: https://platform.kimi.ai/docs/guide/use-moonpalace

Installs MoonPalace using the Go toolchain. The compiled binary is placed in $GOPATH/bin/.

```bash
$ go install github.com/MoonshotAI/moonpalace@latest

```

--------------------------------

### JSON Mode example output

Source: https://platform.kimi.ai/docs/api/partial

Example output from running the JSON Mode example. The API response does not include the leading_text, so you need to manually concatenate it to get the full response.

```json
{"name": "SmartHome Mini", "size": "256 x 128 x 128mm", "price": "998 yuan", "colors": ["black", "silver"]}

```

--------------------------------

### Start OpenCode

Source: https://platform.kimi.ai/docs/guide/open-code

Run the opencode command to start OpenCode. Then use the /models command to search for and select Kimi K3.

```bash
opencode

```

--------------------------------

### Get file content with Python and curl

Source: https://platform.kimi.ai/docs/llms-full.txt

Retrieve the Markdown-formatted content of a file uploaded with purpose file-extract. The Python example uses client.files.content(file_id=file_object.id).text; note that retrieve_content is deprecated in the latest version. The curl example sends a GET request to /v1/files/{file_id}/content with the API key in the Authorization header.

```python
# Note: retrieve_content is marked with a warning in the latest version. Use the line below instead.
# If you are using an older version, you can use retrieve_content.
file_content = client.files.content(file_id=file_object.id).text
```

```bash
curl https://api.moonshot.ai/v1/files/{file_id}/content \
  -H "Authorization: Bearer $MOONSHOT_API_KEY"
```

--------------------------------

### Run the example agent

Source: https://platform.kimi.ai/docs/guide/use-kimi-k3-to-setup-agent

Run the example agent script from the command line. Replace the question in main() with your target industry, region, and years; the final response should contain a summary, key findings, risks, and sources instead of raw tool output.

```bash
python3 agent.py
```

--------------------------------

### Web Search Basic Go example

Source: https://platform.kimi.ai/docs/api/tools-search

Go example using the standard library to call the search endpoint. Creates a POST request with a text_query and prints the response body.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.moonshot.ai/v1/tools/search"

	payload := strings.NewReader("{\n  \"text_query\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### SSE Response Format Example

Source: https://platform.kimi.ai/docs/api/chat

SSE response format example. Each line starts with `data:`, followed by a JSON object. When `finish_reason` is `null`, content accumulates in `delta.content`; when not `null`, output is complete.

```text
data: {"id":"cmpl-xxx","object":"chat.completion.chunk","created":1698999575,"model":"kimi-k2.6","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"cmpl-xxx","object":"chat.completion.chunk","created":1698999575,"model":"kimi-k2.6","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"cmpl-xxx","object":"chat.completion.chunk","created":1698999575,"model":"kimi-k2.6","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":19,"completion_tokens":13,"total_tokens":32,"cached_tokens":12,"prompt_tokens_details":{"cached_tokens":12,"cache_write_tokens":0}}}

data: [DONE]
```

--------------------------------

### List Models with GET /v1/models

Source: https://platform.kimi.ai/docs/llms-full.txt

Query the GET /v1/models endpoint to list available models and their IDs. Requires a valid MOONSHOT_API_KEY; the Python and JavaScript examples use the OpenAI SDK with base URL https://api.moonshot.ai/v1, while the curl example sends a Bearer token. The response includes model objects with fields such as id, context_length, and capability flags.

```python
import os
from openai import OpenAI

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

models = client.models.list()
print(models.data)
```

```bash
curl https://api.moonshot.ai/v1/models \
    -H "Authorization: Bearer $MOONSHOT_API_KEY"
```

```javascript
const OpenAI = require("openai");

const client = new OpenAI({
    apiKey: process.env.MOONSHOT_API_KEY,
    baseURL: "https://api.moonshot.ai/v1",
});

async function main() {
    const models = await client.models.list();
    console.log(models.data);
}

main();
```

--------------------------------

### Node.js usage example with environment variable

Source: https://platform.kimi.ai/docs/api/balance

Uses the MOONSHOT_API_KEY environment variable and fetch to get the balance.

```javascript
const apiKey = process.env.MOONSHOT_API_KEY;

async function main() {
    const response = await fetch("https://api.moonshot.ai/v1/users/me/balance", {
        method: "GET",
        headers: {
            Authorization: `Bearer ${apiKey}`,
        },
    });
    const data = await response.json();
    console.log(data);
}

main();
```

--------------------------------

### Start Kimi Code CLI and open /login

Source: https://platform.kimi.ai/docs/guide/kimi-code-cli

Start Kimi Code CLI in the project directory and enter /login to open the platform selector. /login must be run while the CLI is idle.

```bash
kimi

```

```bash
/login

```

--------------------------------

### Go net/http example for /v1/tools/search_pro

Source: https://platform.kimi.ai/docs/api/tools-search-pro

Go example using net/http to call the Web Search Pro endpoint. Replace <token> and <string> with your credentials and query.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.moonshot.ai/v1/tools/search_pro"

	payload := strings.NewReader("{\n  \"text_query\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Ruby example

Source: https://platform.kimi.ai/docs/api/list-models

Uses Net::HTTP to send a GET request with an Authorization header. Prints the response body.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.moonshot.ai/v1/models")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Provide Examples of Desired Output to the Model

Source: https://platform.kimi.ai/docs/guide/prompt-best-practice

Provides a few-shot prompt example where the system message instructs the model to respond in a consistent style. This is useful when the desired style is difficult to describe explicitly.

```json
{
  "messages": [
    {"role": "system", "content": "Respond in a consistent style"},
    {"role": "user", "content": "Insert text here"}
  ]
}

```

--------------------------------

### Java Unirest example

Source: https://platform.kimi.ai/docs/api/list-models

Uses the Unirest HTTP library to send a GET request with an Authorization header. Returns the response as a string.

```java
HttpResponse<String> response = Unirest.get("https://api.moonshot.ai/v1/models")
  .header("Authorization", "Bearer <token>")
  .asString();
```

--------------------------------

### PHP cURL example

Source: https://platform.kimi.ai/docs/api/list-models

Uses PHP cURL to send a GET request with an Authorization header. Prints the response or an error message.

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.moonshot.ai/v1/models",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

--------------------------------

### Example Output of Multi-file Q&A

Source: https://platform.kimi.ai/docs/guide/ask-questions-about-pdf-content

Example output from the Kimi K3 model comparing K3 to K2, covering scale, architecture, training, and post-training details.

```markdown
# Kimi K3 vs. Kimi K2: Key Improvements

## Scale and Architecture

| Aspect | K2 | K3 | Change |
|---|---|---|---|
| Total params | 1.04T | 2.78T | +167% |
| Activated params | 32.6B | 104.2B | +220% |
| Layers | 61 | 93 | +52% |
| Routed experts | 384 (8 active) | 896 (16 active) | sparsity 48→56 |
| Shared experts | 1 | 2 | — |
| Attention heads | 64 | 96 | +50% |
| Attention | All MLA | Hybrid: 69 KDA + 24 Gated MLA | new |
| Activation | SwiGLU | SiTU-GLU | new |
| Context | 128K | 1M | 8× |
| Vision | None (text-only) | Native (401M MoonViT-V2) | new |

## Architectural Innovations

1. **Kimi Delta Attention (KDA)** — A linear attention mechanism with channel-wise forget gates replaces most MLA layers (3:1 KDA:MLA ratio), giving fixed-size recurrent state instead of a growing KV cache. K3 adds a lower-bounded decay (scaled sigmoid instead of negative Softplus) that keeps values in BF16 range and enables full Tensor Core computation, plus a full-rank output gate.

2. **Gated MLA with NoPE** — The periodic global-attention layers drop positional encoding entirely (no RoPE/YaRN retuning needed for context extension) and add input-dependent output gating.

3. **Attention Residuals (AttnRes)** — Replaces uniform residual accumulation with learned attention over all preceding block outputs, letting each layer selectively retrieve information across depth (8 blocks of 12 layers).

4. **Stable LatentMoE** — Routed experts operate in a compressed 3584-dim latent space, making 896 experts affordable. Stabilized by RMSNorm before up-projection, SiTU-GLU (smoothly bounded activation, output ≤ β₁β₂), and **Quantile Balancing** — a closed-form, learning-rate-free load-balancing rule replacing K2-style fixed-step bias updates.

5. **Native vision** — MoonViT-V2 is trained from scratch with next-token prediction rather than initialized from SigLIP, yielding more stable optimization and no contrastive pre-training dependency.

6. **Per-Head Muon** — Newton–Schulz orthogonalization applied per attention head rather than per full projection matrix, for more balanced updates.

## Training Recipe

- **~2.5× better scaling efficiency** over K2 (per fitted scaling-law curves on held-out data).
- **Cosine LR schedule** replaces WSD, after a fair per-schedule hyperparameter search showed cosine wins.
- **Native multimodal pre-training** from the start (no post-hoc alignment stage).
- **Progressive context extension** 8K→64K→256K→1M (vs. K2's 4K→128K via YaRN), with synthesized long-range tasks to prevent attention degenerating into local patterns.

## Post-Training

K2 was a **non-thinking** model trained with SFT + RLVR + self-critique rubrics. K3 is a full **reasoning model**:

- RL across 3 domains (general, general agents, coding agents) × 3 effort levels (low/high/max) = 9 expert policies, consolidated into one model via **Multi-Teacher On-Policy Distillation**.
- Per-problem **budget control** for token-efficient reasoning; agentic generative reward model with anti-verbosity control.
- Rich verifiable environments: kernel optimization (CUDA/Triton/etc.), personal assistant workflows spanning days, autonomous execution tasks with verify-in-the-loop, web development with deterministic + judged rewards.
- **MXFP4/MXFP8 quantization-aware training** throughout post-training, and EAGLE-3 draft-model fine-tuning with LK loss for speculative decoding.
- New XTML chat template for extensibility and low alignment tax.

## Infrastructure

```

--------------------------------

### Define and use a search tool with Kimi API

Source: https://platform.kimi.ai/docs/guide/use-kimi-api-to-complete-tool-calls

Shows how to define a search tool and use it with the Kimi API (kimi-k3 model) via the OpenAI SDK. The example sets up a client with the Moonshot API key and base URL, defines a function tool with parameters, and streams a chat completion while handling tool_calls in the response.

```python
import os
import json

from openai import OpenAI

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

tools = [
    {
        "type": "function",  # The agreed-upon field type, currently supports function as a value
        "function": {  # When type is function, use the function field to define the specific function content
            "name": "search",  # The name of the function, please use English letters, numbers, plus hyphens and underscores as the function name
            "description": """ 
				Search for content on the internet using a search engine.

				When your knowledge cannot answer the user's question, or the user requests you to perform an online search, call this tool. Please extract the content the user wants to search from the conversation with the user as the value of the query parameter.
				The search results include the title of the website, the website's address (URL), and the website's description.
			""",  # The introduction of the function, write the specific function here and its usage scenarios so that the Kimi large language model can correctly choose which functions to use
            "parameters": {  # Use the parameters field to define the parameters accepted by the function
                "type": "object",  # Fixed use type: object to make the Kimi large language model generate a JSON Object parameter
                "required": ["query"],  # Use the required field to tell the Kimi large language model which parameters are required
                "properties": {  # The properties are the specific parameter definitions, you can define multiple parameters
                    "query": {  # Here, the key is the parameter name, and the value is the specific definition of the parameter
                        "type": "string",  # Use type to define the parameter type
                        "description": """
							The content the user is searching for, please extract it from the user's question or chat context.
						"""  # Use description to describe the parameter so that the Kimi large language model can better generate the parameter
                    }
                }
            }
        }
    },
]

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Please search for Context Caching technology online."}
    ],
    stream=True,
    tools=tools,  # <-- Add tool invocation
)

# Here, we pre-build a List to store different response messages, since we set n=2, we initialize the List with 2 elements
messages = [{}, {}]

for chunk in completion:
    # Loop through all the choices in each data chunk and get the message object corresponding to the index
    for choice in chunk.choices:
        index = choice.index
        message = messages[index]
        delta = choice.delta
        role = delta.role
        if role:
            message["role"] = role
        content = delta.content
        if content:
            if "content" not in message:
                message["content"] = content
            else:
                message["content"] = message["content"] + content

        # From here, we start processing tool_calls
        tool_calls = delta.tool_calls  # <-- First check if the data chunk contains tool_calls
        if tool_calls:
            if "tool_calls" not in message:
                message["tool_calls"] = []  # <-- If it contains tool_calls, we initialize a list to save these tool_calls, note that the list is empty at this time with a length of 0
            for tool_call in tool_calls:
                tool_call_index = tool_call.index  # <-- Get the index of the current tool_call
                if len(message["tool_calls"]) < (
                        tool_call_index + 1):  # <-- Expand the tool_calls list according to the index so that we can access the corresponding tool_call via the subscript
                    message["tool_calls"].extend([{}] * (tool_call_index + 1 - len(message["tool_calls"])))
                tool_call_object = message["tool_calls"][tool_call_index]  # <-- Access the corresponding tool_call via the subscript
                tool_call_object["index"] = tool_call_index

                # The following steps are to fill in the id, type, and function fields of each tool_call based on the information in the data chunk
                # In the function field, there are name and arguments fields, the arguments field will be supplemented by each data chunk
                # Sequentially, just like the delta.content field.
```

--------------------------------

### Java: Get File Information

Source: https://platform.kimi.ai/docs/api/files-retrieve

Use this Java Unirest example to retrieve file information. Replace {file_id} and <token> as needed.

```java
HttpResponse<String> response = Unirest.get("https://api.moonshot.ai/v1/files/{file_id}")
  .header("Authorization", "Bearer <token>")
  .asString();
```

--------------------------------

### JavaScript: Get File Information

Source: https://platform.kimi.ai/docs/api/files-retrieve

Use this JavaScript fetch example to retrieve file information. Replace {file_id} and <token> as needed.

```javascript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.moonshot.ai/v1/files/{file_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```
Tokens:
Raw