Kimi K3 API-Leitfaden: Python, Vision, Tools und 1M-Kontext

Kimi K3 API-Entwicklerleitfaden

Kimi K3 ist über die OpenAI-kompatible Chat Completions API von Moonshot AI mit der Modell-ID kimi-k3 verfügbar. Die API unterstützt dauerhaft aktiviertes Reasoning, Streaming, Bilder, hochgeladene Videos, strikte JSON Schema-Ausgaben, benutzerdefinierte Tools, dynamisches Laden von Tools und ein Kontextfenster mit 1 Million Tokens.

Kompatibilität bedeutet nicht identisches Verhalten. K3 verwendet feste Sampling-Werte, benötigt den vollständigen Assistant-Zustand bei späteren Tool- und Konversationsschritten und behandelt Reasoning getrennt vom finalen Inhalt. Dieser Leitfaden konzentriert sich auf genau diese Details.

Verfügbarkeit und Preise aktualisiert am 22. Juli 2026. Kimi K3 ist auf Poyo.ai als kimi-k3 über die OpenAI-kompatible Chat Completions API verfügbar. Der Preis beträgt $2.28 pro 1 Mio. Eingabe-Token und $11.40 pro 1 Mio. Ausgabe-Token – 24 % günstiger als der offizielle Preis.

Voraussetzungen

Sie benötigen:

Python 3.9 oder neuer;
das Python-Paket openai in Version 1.0 oder neuer;
einen Moonshot-API-Key, der außerhalb der Quellcodeverwaltung gespeichert wird;
die Basis-URL https://api.moonshot.ai/v1;
die Modell-ID kimi-k3.

Installieren Sie das SDK:

python -m pip install --upgrade "openai>=1.0"

Setzen Sie den Key in Ihrer Shell:

export MOONSHOT_API_KEY="your-key"

In PowerShell:

$env:MOONSHOT_API_KEY="your-key"

Platzieren Sie niemals einen Produktiv-Key in einem Codebeispiel, Client-Bundle, Log oder Repository.

Erstellen Sie Ihre erste Kimi K3-Anfrage

Python

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Review this migration plan and list its three highest risks."}
    ],
)

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

cURL

curl https://api.moonshot.ai/v1/chat/completions \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Explain Kimi Delta Attention in plain language."}
    ]
  }'

Reasoning-Aufwand konfigurieren

K3 verwendet immer den Thinking-Modus. Konfigurieren Sie den Aufwand über das Feld reasoning_effort auf oberster Ebene:

response = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="high",
    messages=[
        {"role": "user", "content": "Find the flaw in this distributed lock design."}
    ],
)

Unterstützte Werte:

Wert	Verwenden für
`low`	Einfachere Aufgaben, bei denen Latenz und Ausgabe wichtig sind
`high`	Anspruchsvolle Programmierung, Analysen und Tool-Planung
`max`	Die schwierigsten Aufgaben und Benchmark-ähnliche Bewertungen

Der dokumentierte Standardwert ist max. Gehen Sie nicht davon aus, dass dies die günstigste Einstellung für den Produktiveinsatz ist. Bewerten Sie Erfolgsrate, Latenz und generierte Tokens bei jedem Aufwand.

Reasoning und finalen Inhalt streamen

Streaming-Antworten stellen Reasoning und finalen Text über unterschiedliche Delta-Felder bereit.

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Review this architecture for race conditions."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    reasoning = getattr(delta, "reasoning_content", None)
    if reasoning:
        # Store or process according to your product and provider policies.
        pass
    if delta.content:
        print(delta.content, end="", flush=True)

Halten Sie nutzerseitig sichtbare finale Inhalte getrennt von internen Verarbeitungsdaten. Verarbeiten Sie strukturierte Ausgaben nicht aus reasoning_content.

Ein Bild an Kimi K3 senden

K3-Vision-Nachrichten verwenden ein Array aus Inhaltsobjekten. Öffentliche Bild-URLs werden in diesem Ablauf nicht unterstützt; kodieren Sie ein lokales Bild als Base64.

import base64
from pathlib import Path

image_data = base64.b64encode(Path("interface.png").read_bytes()).decode()

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/png;base64,{image_data}"},
                },
                {
                    "type": "text",
                    "text": "Identify the three largest accessibility problems in this interface.",
                },
            ],
        }
    ],
)

Prüfen Sie Dateityp und Größe vor der Kodierung von Nutzer-Uploads. Vermeiden Sie das Protokollieren von Base64-Payloads.

Ein Video an Kimi K3 senden

Laden Sie Videos über die Files API hoch, referenzieren Sie die zurückgegebene ID mit dem Schema ms:// und löschen Sie die Datei, sobald sie nicht mehr benötigt wird.

from pathlib import Path

video = client.files.create(file=Path("demo.mp4"), purpose="video")

try:
    response = client.chat.completions.create(
        model="kimi-k3",
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "video_url",
                        "video_url": {"url": f"ms://{video.id}"},
                    },
                    {"type": "text", "text": "Summarize the workflow and identify failed steps."},
                ],
            }
        ],
    )
finally:
    client.files.delete(video.id)

Strikte JSON Schema-Ausgaben zurückgeben

Verwenden Sie strict: true, wenn nachgelagerter Code eine vorhersehbare Struktur benötigt.

import json

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Extract the risk, severity, and owner from this incident note."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "incident_risk",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "risk": {"type": "string"},
                    "severity": {"type": "string", "enum": ["low", "medium", "high"]},
                    "owner": {"type": ["string", "null"]},
                },
                "required": ["risk", "severity", "owner"],
                "additionalProperties": False,
            },
        },
    },
)

result = json.loads(response.choices[0].message.content or "{}")

Verarbeiten Sie nur den finalen message.content und validieren Sie ihn anschließend erneut im Anwendungscode.

Benutzerdefinierte Tools aufrufen

Die erste Antwort kann eine oder mehrere Tools anfordern. Führen Sie jeden erlaubten Aufruf aus, fügen Sie die vollständige Assistant-Nachricht hinzu und anschließend für jede tool_call_id ein passendes Tool-Ergebnis.

import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_build_status",
            "description": "Return the current build status for an allowed project.",
            "parameters": {
                "type": "object",
                "properties": {"project": {"type": "string"}},
                "required": ["project"],
                "additionalProperties": False,
            },
        },
    }
]

messages = [{"role": "user", "content": "Check the web build and summarize any failure."}]

first = client.chat.completions.create(
    model="kimi-k3",
    messages=messages,
    tools=tools,
    tool_choice="required",
)

assistant_message = first.choices[0].message
messages.append(assistant_message)

for call in assistant_message.tool_calls or []:
    arguments = json.loads(call.function.arguments)
    # Authorize and validate before executing a real tool.
    tool_result = {"project": arguments["project"], "status": "passed"}
    messages.append(
        {
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(tool_result),
        }
    )

final = client.chat.completions.create(
    model="kimi-k3",
    messages=messages,
    tools=tools,
)

Führen Sie niemals beliebige vom Modell generierte Shell-Befehle ohne Berechtigungsgrenze, Eingabevalidierung, eingeschränkte Umgebung und Prüfprotokoll aus.

Tools dynamisch laden

K3 unterstützt das Platzieren einer vollständigen Tool-Definition in einer system-Nachricht an dem Punkt, an dem sie verfügbar wird. Behalten Sie diese Nachricht im späteren Verlauf bei, da der Server sie nicht für Sie speichert.

Dynamisches Laden hilft großen Agentensystemen dabei, nicht bei jeder Anfrage jedes Tool-Schema senden zu müssen. Es schafft jedoch auch neue Anforderungen an die Zustandsverwaltung: Das Modell muss bei der Interpretation späterer Tool-Ergebnisse exakt dieselbe Deklaration sehen.

Das 1M-Token-Kontextfenster verwenden

Große Kontexte sind besonders wertvoll, wenn weit entfernte Informationen gemeinsam analysiert werden müssen. Verwenden Sie sie gezielt:

Platzieren Sie stabile Repositories oder Dokumentensammlungen am Anfang.
Fügen Sie Fragen und Ergebnisse hinzu, anstatt den Präfix neu zu schreiben.
Verfolgen Sie gecachte und nicht gecachte Eingaben getrennt.
Rufen Sie eine kleinere Teilmenge ab, wenn der vollständige Korpus nicht erforderlich ist.
Legen Sie Quellen-IDs fest, damit die finale Antwort überprüft werden kann.
Verdichten Sie nur, wenn Ihr Client den vollständigen für K3 erforderlichen Zustand erhält.

Automatisches Caching besitzt keine Cache-ID oder gewöhnlichen TTL-Parameter. Stabile Präfixe geben dem Dienst die beste Möglichkeit, den Cache zu nutzen.

Vollständigen Multi-Turn-Zustand erhalten

Dies ist die wichtigste K3-spezifische Integrationsregel.

Beim Fortsetzen einer Unterhaltung oder Zurückgeben von Tool-Ergebnissen müssen Sie die vollständige vom API zurückgegebene Assistant-Nachricht anhängen. Behalten Sie nicht nur content. Moonshot weist darauf hin, dass K3 mit erhaltenem Thinking-Verlauf trainiert wurde und instabil werden kann, wenn die Umgebung erforderlichen Verlauf entfernt oder mitten in einer Sitzung zu K3 wechselt.

Speichern Sie Konversationszustände sicher, wenden Sie Aufbewahrungsgrenzen an und legen Sie versteckte Zustände nicht Nutzern offen, die diese nicht sehen sollten.

Wichtige Kimi K3 API-Limits

K3 hat Reasoning immer aktiviert.
reasoning_effort unterstützt low, high und max.
max_completion_tokens ist standardmäßig auf 131,072 gesetzt und kann bis auf 1,048,576 erhöht werden.
temperature=1.0, top_p=0.95, n=1, presence_penalty=0 und frequency_penalty=0 sind festgelegt; lassen Sie diese Werte weg.
Öffentliche Bild-URLs werden für Vision-Nachrichten nicht unterstützt.
Multi-Turn- und Tool-Anfragen müssen die vollständige Assistant-Nachricht erhalten.
Moonshot zufolge wird das Web-Suche-Tool derzeit aktualisiert und ist aktuell nicht für den Produktiveinsatz empfohlen.

Produktions-Checkliste

Bewahren Sie API-Keys serverseitig auf.
Fügen Sie Request-Timeouts und begrenzte Wiederholungsversuche hinzu.
Validieren Sie Tool-Argumente und autorisieren Sie jede Aktion.
Begrenzen Sie Tool-Schritte und Ausgabelänge.
Erhalten Sie den vollständigen K3-Assistant-Zustand.
Validieren Sie striktes JSON nach der Generierung.
Erfassen Sie Eingabe, gecachte Eingabe, Ausgabe, Latenz und Fehler.
Wechseln Sie nicht mitten in einer K3-Sitzung das Modell.
Fügen Sie explizite Verhaltensgrenzen hinzu, um übermäßige Eigeninitiative zu reduzieren.
Testen Sie mit fehlerhaften Tools, unvollständigen Antworten und langen Verläufen.

Lesen Sie Kimi K3 API Pricing, bevor Sie Kontext- und Ausgabelimits auswählen. Folgen Sie der Kimi K3 model page für die Verfügbarkeit auf Poyo.ai.

Häufig gestellte Fragen

Ist die Kimi K3 API OpenAI-kompatibel?

Ja. Moonshot stellt einen OpenAI-kompatiblen Chat Completions-Endpunkt bereit. Die K3-spezifischen Regeln für Zustand, Reasoning, Sampling und Medien gelten weiterhin.

Wie lautet die Kimi K3 Modell-ID?

Die offizielle Modell-ID der Moonshot API lautet kimi-k3.

Unterstützt Kimi K3 Function Calling?

Ja. Es unterstützt benutzerdefinierte Tools, erforderliche Tool-Auswahl, passende Tool-Ergebnisse und dynamisches Laden von Tools.

Kann Kimi K3 Videos verarbeiten?

Ja. Laden Sie das Video über die Files API hoch und referenzieren Sie dessen ms://-Datei-ID in einem Video-Inhaltsobjekt.

Wie verwende ich das 1M-Kontextfenster?

Senden Sie die erforderlichen Nachrichten und Inhalte über die Standard-Modellanfrage, behalten Sie stabile Präfixe für automatisches Caching unverändert bei und setzen Sie begrenzte Abschlusslimits.