Kimi K3 API: Authentication, Endpoints, and Python Integration Guide

Kimi K3, developed by Moonshot AI, is one of the most capable Chinese large language models available through a public API. It offers a 1-million-token context window, competitive pricing, and an OpenAI-compatible interface — meaning you can integrate it with minimal friction using tools you likely already use. This guide covers everything English-speaking developers need to get up and running: authentication, endpoint details, and complete Python examples for chat completions, streaming, and function calling.

If you are also evaluating Chinese frontier models for your stack, glm5.app is a good starting point for exploring GLM 5.2 (GLM-4-Plus), Zhipu AI's flagship model with similar context capabilities.

The Documentation Problem: Why English Developers Struggle

The most common complaint about the Kimi K3 API is straightforward: Moonshot AI's official documentation is primarily in Chinese. The API console, pricing pages, and parameter references are written for a Chinese-speaking audience. English-speaking developers are left translating pages, guessing at parameter names, or piecing together examples from scattered GitHub repositories.

This guide addresses that gap directly. All the information below has been drawn from official Moonshot AI sources and tested against the live API. You should be able to copy these examples, set your API key, and have working code within minutes.

Prerequisites

You will need:

• A Moonshot AI account at platform.moonshot.cn
• An API key generated from the Moonshot console (under "API Keys")
• Python 3.8 or newer
• The openai Python SDK (version 1.x)

Install the SDK:

pip install openai

The Kimi K3 API is OpenAI-compatible, so the openai package is the right client — no Moonshot-specific SDK required.

Authentication: API Keys and Bearer Tokens

Kimi K3 authenticates requests using a Bearer token. Every HTTP request to the API must include the header:

Authorization: Bearer YOUR_API_KEY

When using the OpenAI Python SDK, pass the key via the api_key parameter. Never hardcode the key in source files. Store it in an environment variable:

export MOONSHOT_API_KEY="sk-your-key-here"

Then initialize the client:

import os
from openai import OpenAI

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

The base_url override is the only structural difference from a standard OpenAI setup. Point it at https://api.moonshot.cn/v1 and the rest of the API surface — models, parameters, response shapes — behaves identically to what OpenAI documents.

Endpoints and Model Tiers

The Kimi K3 API exposes a single base: https://api.moonshot.cn/v1. The chat completions endpoint follows the OpenAI convention:

POST https://api.moonshot.cn/v1/chat/completions

Moonshot offers several model variants corresponding to different context window sizes:

Use kimi-latest to access Kimi K3's full capabilities, including the 1M-token context window. For cost-sensitive batch workloads where context is predictably short, moonshot-v1-8k reduces token spend. Check your Moonshot console for current per-model pricing tiers.

Basic Chat Completion

A minimal working example:

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="kimi-latest",
    messages=[
        {
            "role": "system",
            "content": "You are a helpful software engineering assistant.",
        },
        {
            "role": "user",
            "content": "Explain the difference between processes and threads in Python.",
        },
    ],
    temperature=0.6,
    max_tokens=1024,
)

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

The response object follows the OpenAI schema: response.choices[0].message.content holds the assistant's reply. Usage information (prompt tokens, completion tokens, total tokens) is available at response.usage.

Streaming Responses

For interactive applications — chatbots, coding assistants, live document editors — streaming is essential. Users should see tokens appear as they are generated rather than waiting for the complete response. Kimi K3 supports Server-Sent Events (SSE) streaming:

import os
from openai import OpenAI

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

stream = client.chat.completions.create(
    model="kimi-latest",
    messages=[
        {
            "role": "user",
            "content": "Walk me through how Python's garbage collector works.",
        }
    ],
    stream=True,
)

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

print()  # final newline

The stream=True flag switches the response from a single JSON payload to an iterable of partial chunks. Each chunk's delta.content holds the incremental text. This pattern is drop-in compatible with any existing OpenAI streaming code you have written.

Function Calling

Function calling connects the model to your application's logic. You define one or more functions with their parameter schemas, send them alongside the user message, and the model decides whether to call a function and with what arguments. Kimi K3 supports the standard OpenAI tools interface:

import os
import json
from openai import OpenAI

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

tools = [
    {
        "type": "function",
        "function": {
            "name": "search_documents",
            "description": "Search an internal knowledge base for relevant documents.",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The search query string.",
                    },
                    "max_results": {
                        "type": "integer",
                        "description": "Maximum number of results to return.",
                        "default": 5,
                    },
                },
                "required": ["query"],
            },
        },
    }
]

messages = [
    {
        "role": "user",
        "content": "Find me documents about our API rate limit policies.",
    }
]

response = client.chat.completions.create(
    model="kimi-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

choice = response.choices[0]

if choice.finish_reason == "tool_calls":
    tool_call = choice.message.tool_calls[0]
    function_name = tool_call.function.name
    arguments = json.loads(tool_call.function.arguments)

    print(f"Model requested function: {function_name}")
    print(f"Arguments: {arguments}")

    # Execute the function in your code, then send the result back:
    # tool_result = search_documents(**arguments)
    # messages.append(choice.message)
    # messages.append({
    #     "role": "tool",
    #     "tool_call_id": tool_call.id,
    #     "content": json.dumps(tool_result),
    # })
    # final_response = client.chat.completions.create(model="kimi-latest", messages=messages)

The two-step flow is:

1. Send the user message with tool definitions; inspect finish_reason.
2. If finish_reason == "tool_calls", run your function, append the result to messages, and call the API again to get the model's final natural-language reply.

JSON Mode

When your downstream code needs structured output — for parsing, classification, or feeding another service — enable JSON mode:

response = client.chat.completions.create(
    model="kimi-latest",
    messages=[
        {
            "role": "user",
            "content": (
                'Return a JSON object with keys "title", "author", and "year" '
                'for the book "The Pragmatic Programmer".'
            ),
        }
    ],
    response_format={"type": "json_object"},
)

data = json.loads(response.choices[0].message.content)
print(data)

Always explicitly instruct the model in your prompt that you expect JSON. The response_format parameter constrains the output format but works best when the prompt makes the intent clear.

Error Handling and Rate Limits

Rate limits on the Moonshot platform vary by account tier and are visible in your platform dashboard. The API returns standard HTTP status codes:

A practical retry helper for rate limit errors:

import time
from openai import RateLimitError, APIError

def call_with_retry(client, max_attempts=4, **kwargs):
    for attempt in range(max_attempts):
        try:
            return client.chat.completions.create(**kwargs)
        except RateLimitError:
            wait_seconds = 2 ** attempt
            print(f"Rate limited — retrying in {wait_seconds}s (attempt {attempt + 1})")
            time.sleep(wait_seconds)
        except APIError as exc:
            if exc.status_code == 500 and attempt < max_attempts - 1:
                time.sleep(2 ** attempt)
            else:
                raise
    raise RuntimeError("Exceeded maximum retry attempts")

For sustained high-throughput use, apply for a higher rate limit tier through the Moonshot platform contact form.

Kimi K3 vs GPT-4o: The Cost and Context Advantage

The economics of Kimi K3 are compelling for teams running high-volume inference. At $0.30 per million input tokens and $1.10 per million output tokens (as of writing, for kimi-latest), it is approximately five times cheaper on the input side than GPT-4o. For batch document processing, RAG pipelines, or any workload where prompt tokens dominate the bill, the gap adds up quickly.

The 1M-token context window is the other major practical advantage. Fitting an entire codebase, a lengthy legal contract, or a day's worth of customer support logs into a single context removes the need for chunking strategies that add complexity and can lose cross-document relationships.

For teams exploring multiple capable Chinese AI APIs alongside Kimi K3, the GLM 5.2 API guide on glm5.app covers Zhipu AI's GLM-4-Plus model, which pairs a 1M context window with vision (image understanding) capabilities and a similar OpenAI-compatible interface at $1.40/M input tokens.

Putting It All Together

You now have a complete working toolkit for the Kimi K3 API:

• Authentication: Bearer token via environment variable, passed through the OpenAI SDK's api_key and base_url overrides.
• Model selection: Choose context tier by model name, from moonshot-v1-8k for cost efficiency to kimi-latest for maximum capability.
• Chat completions: Standard messages array with system and user roles.
• Streaming: stream=True with chunk iteration for real-time output.
• Function calling: tools parameter with the OpenAI schema; two-step flow for tool execution.
• JSON mode: response_format for structured outputs.
• Error handling: Exponential backoff for 429 and 500 codes.

The OpenAI compatibility means you can swap between Kimi K3 and other providers by changing two lines — api_key and base_url — giving you genuine flexibility in multi-model architectures.

Sources

• Moonshot AI platform and API console: https://platform.moonshot.cn
• Moonshot AI API documentation: https://platform.moonshot.cn/docs
• Kimi AI product page: https://kimi.moonshot.cn
• OpenAI Python SDK (GitHub): https://github.com/openai/openai-python
• OpenAI Chat Completions API reference (compatible interface): https://platform.openai.com/docs/api-reference/chat