Schrittweise Migration zur Responses API
Auf dieser Seite
Aktualisiert am 3. November 2026: Die vorherige Zuordnung der Parameter deutete an, dass
max_tokensseinen Namen in der Responses API behält; die Tabelle von xAI ändert dies jedoch zumax_output_tokens, und auch die Zähler für die Nutzung ändern ihre Bezeichnungen. Quelle: Vergleich mit Chat Completions.
Warum und wann zu migrieren
Der Endpunkt für Chat Completions ist als veraltet (legacy) gekennzeichnet. Er wird weiterhin funktionieren, aber es werden keine neuen Funktionen mehr hinzugefügt. Wenn Ihre Anwendung serverseitige Tools (Web-Suche, Code-Ausführung), die Speicherung von Gesprächen oder verschlüsseltes Reasoning benötigt, wird eine Migration zur Responses API notwendig.
Die gute Nachricht: Diese Migration kann schrittweise erfolgen. Sie müssen nicht alles auf einmal umschreiben.
Schritt 1: Erfassen der genutzten Funktionen
Bevor Sie migrieren, sollten Sie feststellen, welche Funktionen Ihre Anwendung mit Chat Completions nutzt:
# Audit Ihres bestehenden Codes
# Suchen Sie nach diesen Mustern:
# 1. Basisaufrufe (einfacher Text)
client.chat.completions.create(model=..., messages=...)
# 2. Streaming
client.chat.completions.create(..., stream=True)
# 3. Funktionsaufrufe
client.chat.completions.create(..., tools=[...])
# 4. Vision (Bilder)
# Nachrichten mit Inhalt als Array [text, image_url]
# 5. Generierungsparameter
# temperature, max_tokens, top_p, stop, seed
Basisaufrufe und Streaming sind am einfachsten zu migrieren. Funktionsaufrufe erfordern eine Anpassung des Formats. Vision funktioniert ähnlich.
Schritt 2: Migrieren von Basisaufrufen
Das Migrieren eines einfachen Aufrufs folgt diesem Muster:
# VORHER — Chat Completions
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{"role": "system", "content": "Sie sind ein hilfreicher Assistent."},
{"role": "user", "content": "Hallo!"}
]
)
texte = response.choices[0].message.content
# NACHHER — Responses API
response = client.responses.create(
model="grok-4.20-0309-reasoning",
instructions="Sie sind ein hilfreicher Assistent.",
input="Hallo!"
)
texte = response.output_text
Feldzuordnung
Die wichtigsten Änderungen sind:
messagesmit der Rollesystem→instructions(eigener Parameter)messagesmit der Rolleuser→input(einfacher String)response.choices[0].message.content→response.output_textmax_tokens→max_output_tokens, gemäß der Zuordnungstabelle von xAI;temperaturebehält seinen Namenresponse.usage.prompt_tokensundcompletion_tokens→input_tokensundoutput_tokens(Details:input_tokens_details.cached_tokens,output_tokens_details.reasoning_tokens)
Schritt 3: Migrieren von mehrstufigen Gesprächen
Hier vereinfacht die Responses API die Dinge. Anstatt die Historie bei jedem Aufruf neu zu rekonstruieren, verknüpfen Sie diese über die ID:
# VORHER — Chat Completions (Historie selbst verwalten)
historique = [
{"role": "system", "content": "Sie sind ein hilfreicher Assistent."}
]
def envoyer_message(texte: str) -> str:
historique.append({"role": "user", "content": texte})
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=historique
)
reponse = response.choices[0].message.content
historique.append({"role": "assistant", "content": reponse})
return reponse
# NACHHER — Responses API (Server verwaltet die Historie)
dernier_id = None
def envoyer_message(texte: str) -> str:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
instructions="Sie sind ein hilfreicher Assistent.",
input=texte,
previous_response_id=dernier_id
)
dernier_id = response.id
return response.output_text
Der Code ist einfacher, und Sie müssen das Nachrichten-Array nicht mehr manuell verwalten.
Schritt 4: Neue Funktionen nutzen
Sobald migriert, können Sie Funktionen nutzen, die exklusiv für die Responses API verfügbar sind:
Eingebaute Web-Suche
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Was sind die neuesten Entwicklungen im Bereich generative KI?",
tools=[{"type": "web_search"}]
)
# Die Antwort enthält Zitate mit Quell-URLs
Antwort-Speicherung
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Analysieren Sie dieses Dokument...",
store=True # Speichert für 30 Tage
)
# Später abrufen
stored = client.responses.retrieve(response.id)
Verschlüsseltes Reasoning
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Lösen Sie dieses komplexe Problem...",
include=["reasoning.encrypted_content"]
)
# Das verschlüsselte Reasoning kann in nachfolgenden Anfragen wiederverwendet werden
Empfohlene Migrationsstrategie
Statt alles auf einmal zu migrieren, gehen Sie schrittweise vor:
- Erfassen Sie Chat Completions-Aufrufe in Ihrem Code
- Klassifizieren Sie sie nach Komplexität (Basis → Streaming → Funktionsaufrufe)
- Migrieren Sie zuerst neue Endpunkte oder Funktionen (Greenfield)
- Dann migrieren Sie die einfachsten bestehenden Aufrufe
- Behalten Sie Chat Completions für Drittanbieter-Integrationen, die diese benötigen (z. B. LangChain)
Temporäre Koexistenz
Es ist völlig in Ordnung, beide Endpunkte während des Übergangs parallel zu betreiben:
# Wrapper, der den genutzten Endpunkt abstrahiert
class GrokClient:
def __init__(self, use_responses: bool = False):
self.use_responses = use_responses
self.client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1"
)
def generate(self, system: str, user_message: str) -> str:
if self.use_responses:
response = self.client.responses.create(
model="grok-4.20-0309-reasoning",
instructions=system,
input=user_message
)
return response.output_text
else:
response = self.client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{"role": "system", "content": system},
{"role": "user", "content": user_message}
]
)
return response.choices[0].message.content
Dieser Ansatz ermöglicht es Ihnen, schrittweise umzustellen, indem Sie jede Migration einzeln testen.
Wichtige Erkenntnisse
- Die Migration kann schrittweise erfolgen: Es ist nicht nötig, alles auf einmal umzuschreiben.
- Hauptänderungen:
messages→input/instructions,choices[0].message.content→output_text. - Mehrstufige Gespräche wechseln von einem Nachrichten-Array zu einer einfachen
previous_response_id. - Die Responses API bietet Zugang zu exklusiven Funktionen (Web-Suche, Speicherung, verschlüsseltes Reasoning).
- Betreiben Sie beide Endpunkte während des Übergangs parallel und migrieren Sie nach Komplexitätsstufen.
Testen Sie Ihr Wissen
Die veraltete API verstanden und die Migration vorbereitet.
1. Was bedeutet der veraltete und zustandslose Status von Chat Completions?
Antwort: Der Endpunkt bleibt unterstützt, entwickelt sich aber nicht weiter: Zustandslos erfordert er das erneute Senden der gesamten Historie bei jedem Aufruf – die Responses API ist der moderne Weg.
2. Welche Rollen strukturieren die Nachrichten?
Antwort: system (und developer), user, assistant – das Gerüst, die Anfragen, die Antworten: Die vollständige Historie startet bei jedem neuen Aufruf neu.
3. Wie nutzen Sie bestehenden OpenAI-Code mit Grok?
Antwort: Indem Sie die base_url auf https://api.x.ai/v1 und den API-Schlüssel ändern – die Formatkompatibilität übernimmt den Rest, einschließlich OpenAI SDK und Vercel AI SDK.
4. Was lesen Sie in der Antwort und im Nutzungszähler?
Antwort: choices enthält Antworten mit finish_reason; usage liefert Details zu Tokens, einschließlich reasoning_tokens für Reasoning-Modelle – die Grundlage für die Kostenverfolgung.
5. Wie migrieren Sie sauber zur Responses API?
Antwort: Schrittweise: Neue Entwicklungen in der Responses API, bestehende Endpunkte einzeln umgewandelt mit erneuter Prüfung der Prompts – der Vergleich der beiden Formate leitet die Umwandlung.
Verstehen Sie das Veraltete, bauen Sie für das Moderne: Der schrittweise Migrationsplan des Kurses ist Ihre Landkarte – ohne großen Knall.