Die Schwierigkeit bei der Grok-API liegt meist nicht im Schreiben der Anfrage, sondern in drei Dingen: Passen Key und Adresse zusammen, welcher Endpunkt ist der richtige, und wo kopiert man den Modellnamen? Sind diese drei Punkte korrekt, läuft der erste Aufruf in wenigen Minuten; sind sie falsch, zeigen sich meist 401, 404 oder „model not found“.

Dieser Beitrag folgt der offiziellen xAI-Dokumentation und geht die Schritte Konto und Key, Base URL, Modellname, curl, Python, Streaming und Funktionsaufrufe, Fehlersuche und Migrationscheckliste durch. Preise und verfügbare Modelle ändern sich; prüfen Sie vor der Anbindung die offizielle Models-Seite von xAI und die Modellpreise auf dieser Website.

Hinweis: xAI und Grok sind Marken ihrer jeweiligen Inhaber, OpenAI ist eine Marke seines Inhabers. Dieser Beitrag dient der technischen Anbindung.

1. Zuerst den Weg wählen: offizielle Konsole oder kompatibles Gateway

Grok-API-Keys stammen häufig aus zwei Quellen: der offiziellen xAI-Konsole und einem inländischen Gateway mit OpenAI-kompatiblem Zugang. Das Anfrageformat ist ähnlich, doch Konto, Zahlung und Base URL unterscheiden sich; Keys sind nicht austauschbar.

Vergleich xAI offiziell ZSQH AI Gateway
Konsole console.x.ai ai.zhongshangqihang.com
Base URL https://api.x.ai/v1 https://ai.zhongshangqihang.com/v1
Zahlung nach offiziell unterstützten Methoden Aufladung in RMB, Details gemäß Website
Geeignet für stabilen Zugang und Auslandszahlung inländischen Zugang, einheitliche Abrechnung, Modellwechsel

Wählen Sie zuerst den Weg, dann legen Sie den Key an. Ein offizieller Key an einer Gateway-Adresse – oder umgekehrt – führt meist zu 401. Die Registrierung beim Gateway finden Sie hier; ob Sie ein Gateway benötigen, hängt von Netzwerk, Zahlung und Rechnungsanforderungen ab.

2. Key in sechs Schritten anlegen

  1. Registrieren Sie sich und melden Sie sich in der Konsole an. Offiziell über console.x.ai; beim Gateway über die Registrierungsseite.
  2. Richten Sie die Abrechnung ein oder laden Sie Guthaben auf. Ohne verfügbares Guthaben kann der Key erstellt werden, Aufrufe scheitern aber.
  3. Öffnen Sie die Seite API Keys, legen Sie einen neuen Key an und benennen Sie Projekt und Umgebung, etwa prod-qa-2026-10.
  4. Kopieren Sie den vollständigen Key sofort und legen Sie ihn in einer serverseitigen Umgebungsvariable oder einem Secret-Management-Dienst ab. Viele Konsolen zeigen ihn nur einmal.
  5. Setzen Sie nach dem Prinzip minimaler Rechte Limits, IP- oder Teamrechte; nicht jede Konsole bietet alle Optionen.
  6. Prüfen Sie mit einer minimalen Anfrage, ob Key, Base URL und Modellname zusammenpassen.

Schreiben Sie den Key nicht in Frontend-Code, Git-Repositories oder Chatverläufe. Legen Sie getrennte Keys für Test und Produktion an, damit eine Rotation nicht alle Dienste trifft.

3. Base URL und Endpunkte: nur bis /v1

Die offizielle Base URL lautet https://api.x.ai/v1. Zwei Hinweise: Die Base URL endet bei /v1, hängen Sie /chat/completions nicht selbst an; den konkreten Endpunkt bestimmt das SDK oder der Anfragepfad.

Aktuell empfiehlt xAI POST /v1/responses (Responses API). Das OpenAI-kompatible POST /v1/chat/completions funktioniert weiterhin, ist offiziell aber als legacy gekennzeichnet; neue Funktionen kommen zuerst in die Responses API. Neue Projekte sollten direkt die Responses API nutzen; bestehender OpenAI-Chat-Completions-Code läuft weiter, muss aber akzeptieren, dass er nicht mehr der Hauptweg ist.

Eine minimale curl-Anfrage, Authentifizierung einheitlich über Authorization: Bearer:

export XAI_API_KEY="IhrSchluessel"

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "input": "Erklären Sie in drei Sätzen, was ein API-Gateway ist.",
    "store": false
  }'

store steuert, ob Anfrage und Antwort serverseitig gespeichert werden. Laut offizieller Dokumentation speichert die Responses API standardmäßig 30 Tage; bei sensiblen Inhalten sollte store: false ausdrücklich gesetzt werden. Dann ist allerdings previous_response_id zum Fortsetzen einer Unterhaltung nicht verfügbar.

4. Modellnamen: ID kopieren, nicht raten

Der Modellname ist die Kennung der API, nicht der Werbename auf der Produktseite. Die offizielle Models-Seite listet aktuelle IDs, Kontextlängen und Abrechnungsstufen. Die folgenden Beispiele aus der Dokumentation von Oktober 2026 dienen nur der Formatierung:

Modell-ID Kontext Typische Nutzung
grok-4.7 500k allgemeine Fragen, Coding, Agenten
grok-4.3 1M lange Dokumente, lange Unterhaltungen
grok-4.20-0309-reasoning 1M Aufgaben mit explizitem Schlussfolgern
grok-build-0.1 256k Coding- und Build-Workflows

Modelle kommen und gehen, Namen tragen Datumssuffixe. Kopieren Sie die Kennung vor dem Produktivstart von der offiziellen Models-Seite oder aus den Modellpreisen, schreiben Sie sie nicht aus dem Gedächtnis. Modelle mit -reasoning geben häufig den Schlussfolgerungsprozess aus; Latenz und Kostenstruktur unterscheiden sich von normalen Modellen. Zuerst mit kleinem Traffic testen.

5. Erster Aufruf in Python

xAI bietet ein eigenes SDK und unterstützt auch das OpenAI SDK. Teams mit bestehendem OpenAI-Code ändern nur base_url und api_key:

import os
from openai import OpenAI

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

response = client.responses.create(
    model="grok-4.7",
    input="Erklären Sie in drei Sätzen, was ein API-Gateway ist.",
    store=False,
)

print(response.output_text)

output_text ist eine bequeme Eigenschaft des SDK für reine Textresultate. Für Schlussfolgerungen, Werkzeugaufrufe oder Zitate durchlaufen Sie response.output und prüfen type; verlassen Sie sich nicht darauf, dass Text immer an einem festen Index steht.

6. Streaming und Funktionsaufrufe

Streaming nutzt SSE: In der Anfrage "stream": true setzen, der Client liest die Deltas blockweise. Die offizielle Dokumentation weist darauf hin, dass Reasoning-Modelle länger generieren können; bei Streaming muss das Client-Timeout erhöht werden, damit die Verbindung nicht vorzeitig schließt. So ruft das OpenAI SDK einen kompatiblen Endpunkt auf:

stream = client.chat.completions.create(
    model="grok-4.7",
    messages=[{"role": "user", "content": "Erklären Sie SSE in drei Sätzen."}],
    stream=True,
)

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

Funktionsaufrufe laufen in fünf Schritten: Name, Beschreibung und JSON-Schema des Werkzeugs definieren; Werkzeug in die Anfrage aufnehmen; das Modell gibt function_call zurück; die Funktion lokal ausführen; das Ergebnis zur weiteren Generierung an das Modell zurückgeben. In der Responses API sind Werkzeugdefinitionen flach aufgebaut; zentrale Felder sind type: "function", name, description und parameters.

Zwei leicht übersehene Details: Im Streaming-Modus können Funktionsparameter als Block statt zeichenweise zurückkommen; serverseitige Suchwerkzeuge werden möglicherweise nach Aufrufen separat abgerechnet, maßgeblich ist die offizielle Preisseite. Je mehr Werkzeuge und je unschärfer die Beschreibungen, desto häufiger wählt das Modell das falsche Werkzeug; Anzahl und Parameter zuerst straffen.

7. Häufige Fehler: zuerst den Statuscode lesen

Statuscode Häufige Ursache Vorgehen
401 Key fehlt, ist falsch oder passt nicht zur Base URL Authorization-Header und Adresse prüfen
403 Konto oder Key ohne Recht, regionale oder vertragliche Sperre Rechte und Kontostatus in der Konsole prüfen
404 falscher Pfad oder Modellname existiert nicht /v1/responses und Modell-ID prüfen
400 / 422 fehlerhaftes Feldformat im Request-Body Felder mit der API-Referenz abgleichen
429 Anfragefrequenz oder Parallelität überschritten exponentielles Backoff, Parallelität senken
Timeout lange Generierung des Reasoning-Modells, langsame Verbindung Timeout erhöhen, Streaming nutzen, Dauer erfassen

Unzureichendes Guthaben zeigt sich nicht immer als 429; genaue Fehlercodes und Hinweise stehen in Konsole und offizieller Dokumentation. Die Reihenfolge der Fehlersuche: Statuscode, Fehlermeldung, erst dann der Prompt. Ein noch so guter Prompt repariert keine falsche Base URL.

8. Migrationscheckliste vor dem Produktivstart

  1. Key in eine serverseitige Umgebungsvariable legen und sicherstellen, dass er nicht in Frontend-Bundles oder Logs landet.
  2. Base URL fest verdrahten; Endpunkte nicht im Anwendungscode zusammensetzen.
  3. Eine Modell-Zuordnungstabelle anlegen: altes Modell, neues Modell, Kontext und Abrechnungsstufe.
  4. Neue Projekte mit /v1/responses; bestehende Chat-Completions-Projekte als legacy markieren und die Migration planen.
  5. Timeouts, Wiederholungen und Abbruchlogik für Streaming und Nicht-Streaming vereinheitlichen.
  6. Exponentielles Backoff für 429 und 5xx einrichten, ohne unbegrenzte Wiederholungen.
  7. Request-ID, Modell, Tokenverbrauch und Latenz protokollieren, um Abrechnung und Fehlersuche zu erleichtern.
  8. Zuerst eine unkritische Funktion mit wenig Traffic testen, eine Woche beobachten, dann ausweiten.

Häufige Fragen

Welche Base URL gehört in die Grok API?

Offiziell https://api.x.ai/v1; bei einem Gateway gilt die in dessen Konsole angegebene Adresse. Nur bis /v1, ohne konkreten Endpunkt.

Warum kann das OpenAI SDK die Grok API aufrufen?

xAI bietet eine OpenAI-kompatible Anfragestruktur, insbesondere Chat Completions; auch die Responses API lässt sich über responses.create des OpenAI SDK aufrufen. Richten Sie base_url auf xAI, Modellnamen und einzelne Parameter folgen jedoch der xAI-Dokumentation.

Sind Grok API und OpenAI API dasselbe?

Nein. Es sind Dienste unterschiedlicher Unternehmen mit lediglich kompatibler Schnittstellenform. Keys, Abrechnung, Modelle und Datenrichtlinien unterscheiden sich und sind nicht austauschbar.

Muss man die Responses API verwenden?

Für neue Projekte empfohlen. xAI hat Chat Completions als legacy markiert, neue Funktionen kommen zuerst in die Responses API. Bestehende Systeme können die Migration nach Aufwand planen; ein Wechsel über Nacht ist nicht nötig.

Wie binden inländische Teams die API stabiler an?

Klären Sie zuerst, ob Netzwerk, Zahlung oder Compliance das Problem sind. Geht es nur um Zugang und Abrechnung, kommt ein OpenAI-kompatibles Gateway infrage; dürfen Daten das interne Netz nicht verlassen, sind Private Deployment oder andere Betriebsformen zu prüfen. Maßgeblich sind Ihre tatsächlichen Anforderungen.

Fazit

Die Grok-API-Anbindung lässt sich in einem Satz zusammenfassen: richtige Key-Quelle wählen, Base URL nur bis /v1, Modellnamen von der offiziellen Seite kopieren, neue Projekte bevorzugt mit der Responses API. Streaming, Funktionsaufrufe und Fehlerbehandlung ergänzen diese Hauptkette.

Für einheitliche Verwaltung mehrerer Modelle und Abrechnungen können Sie mit der Registrierungsseite beginnen; Modelle und Abrechnung richten sich nach den Modellpreisen.

Weiterlesen: