Die Kimi API ist OpenAI-kompatibel; bei einer Migration sind meist nur drei Stellen zu ändern: Base URL, API Key und Modellname. Die Schnittstellendetails im Jahr 2026 haben jedoch einige Stolperstellen: ältere Modelle sind abgekündigt, max_tokens ist veraltet, K3 nutzt standardmäßig die höchste Denkstufe, und bei Streaming-Anfragen kommt die Nutzung erst im letzten Block.

Dieser Artikel führt die Anbindung von Grund auf durch: zuerst Seite und Protokoll klären, dann das Modell wählen, anschließend den ersten curl- und Python-Aufruf abschließen und zum Schluss Migrationscheckliste und Fehlercode-Tabelle. Modelle und Preise entnehmen Sie unseren Modellpreisen.

Hinweis: Moonshot und Kimi sind Marken ihrer jeweiligen Inhaber. Dieser Artikel dient nur der technischen Einführung. Modellliste, Kontextlänge und Parameterregeln können sich ändern; maßgeblich ist die aktuelle offizielle Dokumentation.

1. Drei Dinge vor dem Start klären

  1. Seite: Die China-Seite nutzt platform.kimi.com, die internationale Seite platform.kimi.ai. Konten, Guthaben und Keys der beiden Seiten sind vollständig getrennt.
  2. Protokoll: Die meisten Projekte verwenden OpenAI-kompatible Chat Completions; Projekte mit vorhandenem Anthropic SDK können den Messages-kompatiblen Zugang nutzen.
  3. Modell: Prüfen Sie zuerst, welche Modelle Ihr Konto sieht, und schreiben Sie diese in den Code. Kopieren Sie keine Anleitungen von vor einigen Monaten.

Die China-Seite verwendet die Anfrage-Domain https://api.moonshot.cn, die internationale Seite https://api.moonshot.ai. Domain und Key müssen zusammenpassen; das ist eine der häufigsten Ursachen für 401.

2. Base URL und Schnittstellenpfade

Protokoll Base URL Pfad
OpenAI Chat Completions https://api.moonshot.cn/v1 /chat/completions
OpenAI Responses https://api.moonshot.cn/v1 /responses
Anthropic Messages https://api.moonshot.cn/anthropic /v1/messages
Modellliste https://api.moonshot.cn/v1 /models
Guthabenabfrage https://api.moonshot.cn/v1 /users/me/balance

Für die internationale Seite ersetzen Sie die Domain durch api.moonshot.ai, die Pfade bleiben gleich. Beim OpenAI SDK wird base_url bis einschließlich /v1 angegeben; das SDK hängt /chat/completions selbst an. Bei curl muss der vollständige Pfad stehen. Wer beides vermischt, erhält eine zusätzliche oder fehlende /v1-Ebene und damit 404.

Der Anthropic-kompatible Zugang verwendet eine Base URL ohne /v1, anders als der OpenAI-Zugang. Bei Claude Code oder anderen Anthropic SDKs tragen Sie laut offiziellem Beispiel https://api.moonshot.cn/anthropic ein.

3. Modellnamen auswählen

Modellname Kontext Geeignete Aufgaben Hinweis
kimi-k3 1M Komplexe Schlussfolgerungen, Softwareentwicklung, Wissensarbeit, sehr lange Dokumente Standard für reasoning_effort ist max
kimi-k2.7-code 256K Codegenerierung, Repository-Fragen, Agenten Bessere Befolgung von Anweisungen bei langem Kontext
kimi-k2.7-code-highspeed 256K Vervollständigung mit niedriger Latenz, interaktives Programmieren Gleiches Modell wie die Standardversion, schneller
kimi-k2.6 256K Allzweckdialog, Extraktion, Bild- und Texteingabe Unterstützt Denk- und Nicht-Denkmodus

Ältere Modelle sind abgekündigt: Die gesamte moonshot-v1-Reihe und kimi-k2.5 wurden am 31. August 2026 eingestellt, die kimi-k2-Reihe am 25. Mai 2026, kimi-latest noch früher. Projekte, die diese Namen noch verwenden, sollten bei der Aktualisierung direkt auf kimi-k3 oder die K2-Reihe wechseln und nicht weiter nach alten Dokumenten suchen.

Für Allzweckaufgaben muss nicht standardmäßig K3 verwendet werden. K3 ist leistungsfähig, hat aber eine hohe Standard-Denkstufe, was Latenz und Ausgabe-Tokens erhöht. Für einfache Klassifikation und Extraktion in festem Format ist kimi-k2.6 oft passender. Für Codeaufgaben kommt die K2.7-Code-Reihe infrage.

4. Erster Aufruf mit curl

export MOONSHOT_API_KEY="IHR_KEY"

curl "https://api.moonshot.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Antworte nur: Verbindung erfolgreich"}
    ],
    "max_completion_tokens": 64
  }'

Wenn 200 zurückkommt und der Inhalt passt, stimmen Key, Seite, Modellname und Pfad. Bei 401 prüfen Sie zuerst, ob Seite und Key zusammenpassen. Bei 404 prüfen Sie Modellname und /v1. Bei 400 sehen Sie in der Fehlermeldung nach, ob Kontext- oder Ausgabegrenzen genannt werden.

5. Python SDK und Streaming

Installieren Sie das OpenAI SDK ab Version 1.0 und ändern Sie base_url und Key:

import os
from openai import OpenAI

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

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Erkläre in drei Punkten, für welche Teams ein API-Gateway geeignet ist."}],
    max_completion_tokens=512,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
    if chunk.usage:
        print("\nNutzung:", chunk.usage)

Die Streaming-Antwort ist SSE; jede Zeile beginnt mit data: und endet mit data: [DONE]. Mit aktiviertem include_usage wird vor dem Ende ein zusätzlicher Block zurückgegeben, dessen choices leer ist und der nur usage enthält. Bricht die Verbindung vorher ab, kann dieser Block fehlen; verlassen Sie sich bei der Nutzungsabrechnung daher nicht ausschließlich auf den Client.

6. max_completion_tokens und Denkstufe

max_tokens ist veraltet; neuer Code verwendet einheitlich max_completion_tokens. Der Wert bezeichnet die erwartete Ausgabelänge, nicht die Summe aus Eingabe und Ausgabe. Bei K3 liegt der Standard bei 131072, der Maximalwert bei 1048576. Überschreitet Eingabe plus dieser Wert das Kontextfenster, gibt die Anfrage invalid_request_error zurück.

Zwei praktische Regeln:

  • Bei Tests und Aufgaben mit festem Format den Wert klein halten, etwa 256 bis 1024, um lange Ausgaben zu vermeiden.
  • Wird die Obergrenze erreicht, ist finish_reason gleich length; ein normales Ende ist stop. Bei length nicht sofort wiederholen, sondern prüfen, ob die Ausgabe wirklich länger sein muss oder der Prompt zu offen ist.

K3 hat außerdem den Parameter reasoning_effort auf oberster Ebene mit den Werten low, high und max; Standard ist max. Für einfache Aufgaben senkt low Latenz und Tokenverbrauch; bei komplexen Schlussfolgerungen erhöhen Sie die Stufe. Wenn die verwendete OpenAI-SDK-Version den Parameter nicht kennt, übergeben Sie ihn über extra_body. Der Denkinhalt von K3 steht in reasoning_content und muss bei mehrstufigen Dialogen und Tool-Aufrufen unverändert zurückgegeben werden.

7. Migration von OpenAI oder älterem Moonshot

  1. Alle alten Modellnamen in Code und Konfiguration erfassen und eine Ersetzungstabelle anlegen.
  2. base_url ändern: China-Seite https://api.moonshot.cn/v1, internationale Seite https://api.moonshot.ai/v1.
  3. Den Key der passenden Seite einsetzen; nicht seitenübergreifend wiederverwenden.
  4. Modellnamen ersetzen, vorzugsweise durch aktuelle Modelle aus kimi-k3 oder der K2-Reihe.
  5. max_tokens in max_completion_tokens umbenennen.
  6. Die thinking-Einstellung von K2.x auf reasoning_effort von K3 umstellen; nicht beide gleichzeitig senden.
  7. Bei Streaming-Anfragen stream_options={"include_usage": True} ergänzen.
  8. Mit derselben Charge echter Aufgaben eine Regression durchführen und Qualität, Latenz, finish_reason und Nutzung erfassen.
  9. Die alte Konfiguration einen Release-Zyklus lang behalten und erst nach Bestätigung löschen.

Wechseln Sie nicht auf einmal vollständig. Zuerst Testumgebung, dann risikoarme Geschäftsfälle, zuletzt die Kernstrecke; jeder Schritt behält einen Rollback-Schalter.

8. Häufige Fehlercodes

Statuscode Fehlertyp Häufige Ursache Behandlung
400 invalid_request_error Falscher Parameter, Kontext zu lang, Ausgabegrenze überschritten Anfrage korrigieren
400 content_filter Eingabe oder Ausgabe durch Inhaltssicherheit blockiert Prompt anpassen
401 invalid_authentication_error Key ungültig, Seite passt nicht Key oder Domain wechseln
404 resource_not_found_error Modellname oder Pfad falsch Modellliste prüfen
429 rate_limit_reached_error Parallelität, RPM, TPM oder TPD überschritten Tempo senken oder Stufe erhöhen
429 exceeded_current_quota_error Zahlungsrückstand oder Guthaben zu niedrig Aufladen
504 Gateway Time-out Nicht gestreamte lange Anfrage wartet zu lange Auf Streaming wechseln

Nicht gestreamte Anfragen können nach mehr als 900 Sekunden Serverseite mit 504 enden. Lange Texte, Dokumentanalysen und Code-Agenten sollten Streaming nutzen; so erhält der Client laufend Daten, und die Verschwendung durch „bis zum Timeout warten und dann wiederholen“ sinkt.

Häufige Fragen

Bis zu welcher Ebene wird die Base URL angegeben?

Beim OpenAI SDK https://api.moonshot.cn/v1, ohne /chat/completions. Bei curl steht der vollständige Pfad https://api.moonshot.cn/v1/chat/completions. Beim Anthropic SDK https://api.moonshot.cn/anthropic.

Warum wirkt max_tokens nicht?

Der Parameter ist veraltet; einige Modelle ignorieren ihn oder geben einen Fehler zurück. Verwenden Sie max_completion_tokens und beachten Sie, dass es die Ausgabegrenze und nicht die Eingabe-plus-Ausgabe-Grenze ist.

Warum ist K3 langsamer als erwartet?

K3 nutzt standardmäßig reasoning_effort auf max und führt tiefergehende Schlussfolgerungen aus. Für einfache Aufgaben senken Sie auf low oder high und begrenzen die Ausgabelänge; das verbessert die Latenz meist deutlich.

Warum fehlt nach dem Streaming die usage?

Sie müssen stream_options={"include_usage": True} explizit setzen. Auch dann kann der letzte Block bei einer Verbindungsunterbrechung fehlen; in der Produktion sollte serverseitig separat abgerechnet werden.

Was muss bei der Migration von OpenAI außerdem geändert werden?

Meist nur Base URL, Key und Modellname. Prüfen Sie zusätzlich max_tokens, Streaming-Nutzung, Zuordnung der Fehlertypen und Wiederholungsstrategie, insbesondere die Behandlung von 429.

Nächster Schritt

Erstellen Sie zuerst im ZSQH AI Gateway einen Test-Key und führen Sie je eine echte Aufgabe mit kimi-k3 und kimi-k2.6 aus. Erst nach Bestätigung der Verbindung gehen Sie in die Produktion. Verfügbare Modelle und Abrechnung entnehmen Sie den Modellpreisen.

Weiterlesen: