Kimi K3.1 Pro API: Endpunkte, Tool Calling, Caching und Fehler

Die Kimi K3.1 Pro API läuft unter https://api.moonshot.ai/v1 mit den Modell-IDs kimi-k3.1-pro und kimi-k3.1-pro-highspeed. Sie spricht drei Wire-Formate: OpenAI Chat Completions, die Responses API und Anthropic Messages – die SDKs, die Sie bereits verwenden, funktionieren also mit einer geänderten Base-URL. Das Modell wird nach einer Mindestaufladung von 1 $ freigeschaltet.

Dies ist die Referenz für Produktionscode. Für Ihren ersten Aufruf, Streaming und die Einrichtung mit Codex oder Claude Code lesen Sie So verwenden Sie Kimi K3.1 Pro; zu den Kosten siehe Kimi K3.1 Pro Preise. Die Fakten stammen aus Moonshots K3.1 Pro Quickstart und den verlinkten Dokumenten, gelesen am 24. Oktober 2026.

Kimi K3.1 Pro Responses API, Anthropic API und Chat Completions

Moonshot stellt K3.1 Pro über drei API-Oberflächen bereit. Wählen Sie diejenige, die Ihre Client-Bibliothek oder Ihr Agent bereits spricht; Modell, Schlüssel und Abrechnung sind bei allen drei identisch.

Sie unterscheiden sich darin, wie Sie die Cache-TTL festlegen und wo die Nutzung landet (siehe Caching unten). Sie kommen von K3? Unser Kimi K3 API-Leitfaden gilt weiterhin; K3.1 Pro ist ein nachtrainiertes K3 mit demselben Kontext von 1.048.576 Token.

Kimi K3.1 Pro API-Schlüssel: freischalten und Zugriff prüfen

Sie benötigen ein aufgeladenes Konto und einen Schlüssel aus dem richtigen Produkt. Vier Schritte:

1. Laden Sie mindestens 1 $ auf der Kimi API-Plattform auf. K3.1 Pro ist ein Flaggschiffmodell und wird erst nach einer erfolgreichen Aufladung freigeschaltet.
2. Erstellen Sie einen Schlüssel in der API-Schlüssel-Konsole und exportieren Sie ihn als MOONSHOT_API_KEY.
3. Bestätigen Sie mit GET /v1/models, dass das Modell für diesen Schlüssel sichtbar ist.
4. Rufen Sie kimi-k3.1-pro aus dem Code auf.

curl https://api.moonshot.ai/v1/models \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" | grep -o '"kimi-k3.1-pro[^"]*"'

Wenn das Modell nicht aufgeführt ist, beheben Sie das zuerst. Kimi API, Kimi Code und Kimi Membership sind separate Produkte: Ein Kimi Code-Schlüssel funktioniert nicht am API-Endpoint, und eine Mitgliedschaft wird nicht zu API-Guthaben.

Anfrageparameter, die für K3.1 Pro wichtig sind

Die meisten OpenAI-Parameter verhalten sich wie erwartet. Diese hier weichen ab oder sorgen für Überraschungen:

Reasoning-Token zählen zu Ihrer Nutzung, verwenden Sie also "low" für Klassifizierung und Extraktion. Preserved Thinking ist immer aktiv, daher geht jede Assistant-Nachricht mit intaktem reasoning_content zurück (Leitfaden zu Thinking-Modellen).

Kimi K3.1 Pro Tool-Calling: eine vollständige Schleife in Python

Eine Produktions-Tool-Schleife auf K3.1 Pro folgt vier Regeln aus Moonshots Docs:

• Erzwingen Sie im ersten Durchgang einen Tool-Aufruf mit tool_choice="required" und wechseln Sie dann zu "auto".
• Hängen Sie die vollständige Assistant-Nachricht an, einschließlich reasoning_content und tool_calls.
• Senden Sie eine tool-Nachricht pro tool_call_id.
• Begrenzen Sie die Anzahl der Durchgänge, damit ein verwirrtes Modell nicht endlos schleifen kann.

import json, os
from openai import OpenAI

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

TOOLS = [{"type": "function", "function": {
    "name": "get_order_status",
    "description": "Look up an order's shipping status by ID",
    "parameters": {"type": "object",
                   "properties": {"order_id": {"type": "string"}},
                   "required": ["order_id"]}}}]

def get_order_status(order_id):
    return {"order_id": order_id, "status": "shipped"}

messages = [{"role": "user", "content": "Where is order A-1042?"}]
tool_choice = "required"
for _ in range(8):  # hard cap on turns
    resp = client.chat.completions.create(
        model="kimi-k3.1-pro", reasoning_effort="high",
        messages=messages, tools=TOOLS, tool_choice=tool_choice)
    msg = resp.choices[0].message
    messages.append(msg)  # whole message, not msg.content
    if not msg.tool_calls:
        print(msg.content)
        break
    for call in msg.tool_calls:
        result = get_order_status(**json.loads(call.function.arguments))
        messages.append({"role": "tool", "tool_call_id": call.id,
                         "content": json.dumps(result)})
    tool_choice = "auto"

Der klassische Bug ist, msg.content statt msg anzuhängen, wodurch tool_calls und reasoning_content verloren gehen.

Tool-Calling im großen Maßstab mit search_tools

Wenn Ihr Agent Dutzende oder Hunderte von Tools hat, senden Sie nicht bei jeder Anfrage jede Definition mit. Moonshots Best Practice für K3 Tool-Calling empfiehlt diesen Ablauf:

1. Deklarieren Sie eine search_tools-Funktion (die Ihr Backend implementiert) plus einige Kern-Tools.
2. Setzen Sie tool_choice: "required" im ersten Durchgang, damit das Modell abruft, bevor es antwortet.
3. Injizieren Sie die passenden Tool-Definitionen über eine system-Nachricht, die ein tools-Feld trägt.
4. Lassen Sie das Modell in späteren Durchgängen die geladenen Tools aufrufen, wobei tool_choice wieder auf "auto" steht.

# after search_tools returns ["create_github_pr"]
messages.append({"role": "system",
                 "tools": [CATALOG["create_github_pr"]]})

Injizierte Definitionen verwenden das tools-Format auf oberster Ebene und gelten ab dieser Nachricht. Der Server behält sie nicht, behalten Sie die Nachricht also in späteren Anfragen bei. Weder das Ändern von tool_choice noch das Anhängen einer Definition bricht den Prefix-Cache.

Bild- und Videoeingabe

K3.1 Pro akzeptiert Bilder und Videos zusammen mit Text und gibt Text zurück. Machen Sie content zu einem Array aus Teilen: einem image_url-Teil (das Quickstart-Beispiel sendet eine Base64-Daten-URL und merkt an, dass öffentliche Bild-URLs nicht unterstützt werden) oder einem video_url-Teil, der auf eine hochgeladene Datei mit einer ms://-ID verweist.

from pathlib import Path

video = client.files.create(file=Path("demo.mp4"), purpose="video")
content = [{"type": "video_url", "video_url": {"url": f"ms://{video.id}"}},
           {"type": "text", "text": "Summarize this video."}]

Übergeben Sie content als User-Nachricht und löschen Sie die Datei mit client.files.delete(video.id), wenn Sie fertig sind.

Context-Caching im Code

Caching erfolgt automatisch für wiederholte Präfixe mit einer Standard-TTL von 5 Minuten. Cache-Treffer werden mit 0,20 $ pro Million Token abgerechnet gegenüber 2,00 $ für nicht gecachte Eingabe, und ein Schreibvorgang mit 1 Stunde kostet 4,00 $ gegenüber 2,00 $ für 5 Minuten. Bei einem Präfix von 1 Mio. Token amortisiert sich die 1-Stunden-TTL nach zwei Treffern.

Setzen Sie stabilen Inhalt an den Anfang (System-Prompt, Tool-Definitionen, Docs), veränderlichen Inhalt ans Ende und keine Zeitstempel ins Präfix. Beim openai SDK übergeben Sie die TTL über extra_body:

resp = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[{"role": "system", "content": DOCS},
              {"role": "user", "content": question}],
    extra_body={"prompt_cache_options": {"mode": "implicit", "ttl": "1h"}},
)
d = resp.usage.prompt_tokens_details
print(resp.usage.prompt_tokens, d.cached_tokens,
      getattr(d, "cache_write_tokens", 0))

Die Anthropic API legt die TTL mit einem cache_control-Feld auf oberster Ebene fest; Marker innerhalb von Nachrichten werden ignoriert:

curl https://api.moonshot.ai/anthropic/v1/messages \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" \
  --data '{"model": "kimi-k3.1-pro", "max_tokens": 256,
    "cache_control": {"type": "ephemeral", "ttl": "1h"},
    "messages": [{"role": "user", "content": "Hello"}]}'

Wo die Cache-Nutzung angezeigt wird, hängt von der Oberfläche ab:

Beim Streaming von Chat Completions setzen Sie stream_options.include_usage=true, um die Nutzung im letzten Chunk zu erhalten. Jeder Treffer erneuert die TTL, die beim ersten Schreiben festgelegt wird. Vollständige Regeln: der Leitfaden zum Context-Caching.

Kimi K3.1 Pro API-Fehler und Lösungen

Die meisten Fehler fallen in sechs Muster. Prüfen Sie bei jeder 429 error.type, denn die Lösung hängt davon ab.

Achten Sie auf Wiederholungsversuche. Das OpenAI SDK wiederholt standardmäßig 2-mal bei Verbindungsfehlern, 408, 409, 429 und 5xx, sodass aus einem Aufruf drei Anfragen gegen Ihr RPM werden können. Senken Sie in einem niedrigen Tarif die max_retries des Clients und verwenden Sie selbst Backoff anhand von error.type. Durch eine 429 unterbrochene Anfragen werden nicht berechnet.

Wenn ein Drittanbieter-Agent fehlschlägt, rufen Sie die API direkt mit demselben Schlüssel, Endpoint und Modell auf. Wenn das funktioniert, liegt das Problem beim Tool. Siehe die Troubleshooting-Seite und die Fehlercodes.

Kimi K3.1 Pro Rate Limits nach Tarif

Ihre kumulative Aufladung bestimmt Ihren Tarif auf der Limits-Seite:

Tier0 erlaubt 3 Anfragen pro Minute, und jeder Durchgang einer Tool-Schleife ist eine Anfrage. Ein Agent-Lauf mit fünf Durchgängen überschreitet in diesem Tarif bereits eine Minute, planen Sie also 10 $ kumulativ ein, bevor Sie Agents ernsthaft testen.

Contract-Testing der Kimi API mit der Apidog CLI

Ein Contract-Test fängt den Tag ab, an dem Ihre Tool-Schleife keine tool_calls mehr zurückbekommt. Lassen Sie Ihren Coding-Agenten ihn mit der Apidog CLI erstellen. Einmal installieren und anmelden:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
apidog skill install

Dann prompten Sie Claude Code, Codex oder welchen Agenten Sie auch verwenden:

In Apidog project <projectId>, create an environment for https://api.moonshot.ai/v1
and an endpoint for POST /chat/completions. Add a test case that sends model
kimi-k3.1-pro, reasoning_effort "low", one get_order_status tool and
tool_choice "required". Assert status 200 and that choices[0].message.tool_calls
is non-empty. Run it and report failures.

Der Agent liest das Schema, validiert seine Payload und führt den Testfall aus:

apidog environment create kimi-prod --project <projectId> --base-url https://api.moonshot.ai/v1
apidog endpoint create --project <projectId> --file ./endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,json

Testfälle benötigen eine gültige Kategorie; apidog test-case category --project <projectId> listet sie auf. Sobald der Lauf erfolgreich ist, tauschen Sie -r cli,json gegen -r junit mit --out-dir aus, und dieselbe Prüfung sichert Ihre CI ab, wie unser Apidog CLI CI/CD-Leitfaden zeigt. Das Agent-Setup finden Sie unter Apidog CLI in Claude Code. Der kostenlose Plan von Apidog deckt bis zu 4 Nutzer ab.

FAQ

Wie lautet die Base-URL für die Kimi K3.1 Pro API?

https://api.moonshot.ai/v1 für Chat Completions und die Responses API sowie https://api.moonshot.ai/anthropic für die Anthropic-kompatible Messages API.

Unterstützt die Kimi K3.1 Pro API den Parameter thinking?

Nein. Das Denken ist immer aktiv. Steuern Sie es mit dem Feld reasoning_effort auf oberster Ebene ("low", "high" oder "max").

Warum bekomme ich direkt nach dem Aufladen eine 429?

Lesen Sie error.type. engine_overloaded_error ist Serverkapazität, und eine Aufladung behebt das nicht. rate_limit_reached_error bedeutet die Limits Ihres Tarifs, und Tier0 erlaubt nur 3 RPM.

Wie erkenne ich, ob das Caching funktioniert?

Ein Cache-Lese-Feld ungleich null in usage bedeutet einen Treffer: prompt_tokens_details.cached_tokens bei Chat Completions oder cache_read_input_tokens bei Messages.

Gibt es einen kostenlosen Tarif für die Kimi K3.1 Pro API?

Nein. Die API erfordert eine Mindestaufladung von 1 $. Der kostenlose Chat in der Kimi-App ist der 0-$-Weg, beschrieben unter So verwenden Sie Kimi K3.1 Pro kostenlos. Hintergrundinformationen zum Modell finden Sie unter Was Kimi K3.1 Pro ist.