Migratie naar de Responses API in fasen
Op deze pagina
Bijgewerkt op 3 november 2026: De eerdere parametermapping gaf aan dat
max_tokenszijn naam behoudt in de Responses API; de tabel van xAI wijzigt dit echter naarmax_output_tokens, en ook de namen van de gebruikstatellers veranderen. Bron: Comparison with Chat Completions.
Waarom en wanneer migreren
Het Chat Completions-eindpunt is aangemerkt als verouderd (legacy). Het blijft werken, maar er worden geen nieuwe functies meer aan toegevoegd. Als uw applicatie server-side tools nodig heeft (zoals webzoekopdrachten, code-uitvoering), gespreksopslag of versleutelde redenering, wordt migratie naar de Responses API noodzakelijk.
Het goede nieuws: deze migratie kan geleidelijk plaatsvinden. U hoeft niet alles in één keer herschrijven.
Stap 1: Breng uw gebruikte functies in kaart
Voordat u migreert, maakt u een inventarisatie van wat uw applicatie momenteel gebruikt binnen Chat Completions:
# Audit your existing code
# Look for these patterns:
# 1. Basic calls (simple text)
client.chat.completions.create(model=..., messages=...)
# 2. Streaming
client.chat.completions.create(..., stream=True)
# 3. Function calling
client.chat.completions.create(..., tools=[...])
# 4. Vision (images)
# messages with content as array [text, image_url]
# 5. Generation parameters
# temperature, max_tokens, top_p, stop, seed
Basisaanroepen en streaming zijn het eenvoudigst te migreren. Voor function calling moet u het formaat aanpassen. Vision werkt op vergelijkbare wijze.
Stap 2: Migreer basisaanroepen
Het migreren van een eenvoudige aanroep volgt dit patroon:
# BEFORE — Chat Completions
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
]
)
texte = response.choices[0].message.content
# AFTER — Responses API
response = client.responses.create(
model="grok-4.20-0309-reasoning",
instructions="You are a helpful assistant.",
input="Hello!"
)
texte = response.output_text
Veldmapping
De belangrijkste wijzigingen zijn:
messagesmet rolsystem→instructions(dedicated parameter)messagesmet roluser→input(eenvoudige string)response.choices[0].message.content→response.output_textmax_tokens→max_output_tokens, volgens de mapping-tabel van xAI;temperaturebehoudt zijn naamresponse.usage.prompt_tokensencompletion_tokens→input_tokensenoutput_tokens(details:input_tokens_details.cached_tokens,output_tokens_details.reasoning_tokens)
Stap 3: Migreer conversaties met meerdere beurten
Hier vereenvoudigt de Responses API de zaken aanzienlijk. In plaats van bij elk verzoek de geschiedenis opnieuw op te bouwen, koppelt u verzoeken aan elkaar via een ID:
# BEFORE — Chat Completions (manage history yourself)
historique = [
{"role": "system", "content": "You are a helpful assistant."}
]
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
# AFTER — Responses API (server manages history)
dernier_id = None
def envoyer_message(texte: str) -> str:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
instructions="You are a helpful assistant.",
input=texte,
previous_response_id=dernier_id
)
dernier_id = response.id
return response.output_text
De code is eenvoudiger en u hoeft de messages-array niet langer handmatig te beheren.
Stap 4: Profiteer van nieuwe functies
Zodra u bent gemigreerd, kunt u gebruikmaken van functies die exclusief zijn voor de Responses API:
Ingebouwde webzoekopdracht
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What are the latest developments in generative AI?",
tools=[{"type": "web_search"}]
)
# The response includes citations with source URLs
Opslag van antwoorden
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Analyze this document...",
store=True # Keeps for 30 days
)
# Retrieve later
stored = client.responses.retrieve(response.id)
Versleutelde redenering
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Solve this complex problem...",
include=["reasoning.encrypted_content"]
)
# The encrypted reasoning can be reused in subsequent requests
Aanbevolen migratiestrategie
Migreer niet alles in één keer, maar werk stapsgewijs:
- Identificeer Chat Completions-aanroepen in uw code
- Classificeer ze op complexiteit (basis → streaming → function calling)
- Migreer eerst nieuwe eindpunten of functies (greenfield)
- Migreer daarna de eenvoudigste bestaande aanroepen
- Behoud Chat Completions voor integraties van derden die dit vereisen (zoals LangChain, etc.)
Tijdelijke co-existentie
Het is volkomen acceptabel om beide eindpunten tijdens de overgangsfase naast elkaar te laten draaien:
# Wrapper that abstracts the endpoint used
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
Met deze aanpak kunt u geleidelijk overschakelen door elke migratie afzonderlijk te testen.
Belangrijkste punten
- Migratie kan geleidelijk verlopen: u hoeft niet alles in één keer herschrijven
- Belangrijkste wijzigingen:
messages→input/instructions,choices[0].message.content→output_text - Conversaties met meerdere beurten verschuiven van een messages-array naar een simpele
previous_response_id - De Responses API biedt toegang tot exclusieve functies (web_search, opslag, versleutelde redenering)
- Laat beide eindpunten tijdens de overgang naast elkaar draaien en migreer op volgorde van complexiteit
Test uw kennis
De verouderde API begrepen – en de migratie voorbereid.
1. Wat betekent de status 'verouderd' en 'stateless' van Chat Completions?
Antwoord: Het eindpunt blijft ondersteund maar evolueert niet langer: omdat het stateless is, moet bij elke aanroep de volledige geschiedenis opnieuw worden verzonden; de Responses API is de moderne weg vooruit.
2. Welke rollen structureren de berichten?
Antwoord: system (en developer), user, assistant – het kader, de verzoeken, de antwoorden: de volledige geschiedenis start bij elk verzoek opnieuw.
3. Hoe gebruikt u bestaande OpenAI-code met Grok?
Antwoord: Door de base_url te wijzigen naar https://api.x.ai/v1 en de API-sleutel aan te passen; de compatibiliteit van het formaat regelt de rest, inclusief de OpenAI SDK en Vercel AI SDK.
4. Wat leest u in het antwoord en het gebruik?
Antwoord: choices bevat antwoorden met finish_reason; usage geeft details over tokens, inclusief reasoning_tokens voor redeneermodellen – de basis voor kostenbewaking.
5. Hoe migreert u schoon naar de Responses API?
Antwoord: Geleidelijk: nieuwe ontwikkelingen in Responses, bestaande eindpunten stuk voor stuk converteren met opnieuw testen van de prompt – het vergelijken van de twee formaten stuurt de conversie.
Begrijp het verouderde, bouw voor het moderne: het gefaseerde migratieplan van deze cursus is uw routekaart – zonder een ‘big bang’.