Responses API vs Chat Completions: Waarom migreren
Op deze pagina
Responses API vs Chat Completions
De Chat Completions API was jarenlang de standaard en veel code die u online vindt, maakt er nog steeds gebruik van. Sinds 2025 heeft OpenAI deze echter aangemerkt als verouderd (legacy) en beveelt het de Responses API aan voor alle nieuwe projecten. Deze les vergelijkt de twee interfaces, met de nadruk op verschillen die daadwerkelijk invloed hebben op uw code.
Fundamentele wijzigingen
Bij Chat Completions bouwde u een lijst met berichten op en verzond u bij elke oproep de volledige lijst. De conversatiestatus leefde in uw applicatie, nooit op de server:
from openai import OpenAI
client = OpenAI()
# Oud model — Chat Completions (verouderd)
response = client.chat.completions.create(
model="gpt-5.6-terra",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "What is the capital of France?"},
]
)
print(response.choices[0].message.content)
# Resultaat: "The capital of France is Paris."
De Responses API reduceert dezezelfde oproep tot twee parameters en biedt directe toegang tot de gegenereerde tekst. Het systeembericht wordt de parameter instructions, en voor het extraheren van inhoud hoeft u niet langer door choices[0].message.content te navigeren:
from openai import OpenAI
client = OpenAI()
# Nieuw model — Responses API
response = client.responses.create(
model="gpt-5.6-terra",
input="What is the capital of France?"
)
print(response.output_text)
# Resultaat: "The capital of France is Paris."
Sessiebeheer aan serverzijde
Dit biedt het meest directe voordeel. De API onderhoudt de conversatiestatus, dus u hoeft alleen maar via de ID te verwijzen naar het vorige antwoord. Stel u een ondersteuningsassistent voor: bij de tiende beurt dwong de Chat Completions-aanpak u om de vorige negen uitwisselingen opnieuw te verzenden, wat betekende dat u voor die tokens opnieuw betaalde. Hier volstaat één veld:
# Eerste vraag
response = client.responses.create(
model="gpt-5.6-terra",
input="My name is Marie."
)
# Tweede vraag — context wordt automatisch behouden
followup = client.responses.create(
model="gpt-5.6-terra",
input="What is my name?",
previous_response_id=response.id
)
print(followup.output_text)
# Resultaat: "Your name is Marie."
Gegarandeerde JSON, geen hoopvolle JSON
De tweede grote verbetering betreft gestructureerde uitvoer. U beschrijft het verwachte formaat en de Responses API garandeert dat het antwoord voldoet aan uw JSON-schema, waardoor u kunt deserialiseren zonder veiligheidsnetten. Een registratieformulier dat informatie uit vrije tekst haalt, werkt niet meer stuk alleen omdat het model besluit een inleidende zin aan de JSON toe te voegen:
from pydantic import BaseModel
class City(BaseModel):
name: str
country: str
population: int
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me information about Paris.",
text={"format": {"type": "json_schema", "json_schema": {
"name": "city",
"strict": True,
"schema": City.model_json_schema()
}}}
)
print(response.output_text)
# Resultaat: {"name": "Paris", "country": "France", "population": 2161000}
Functieaanroepen en streaming
Het declareren van tools volgt dezelfde logica van vereenvoudiging: de functiedescriptor wordt plat gedeclareerd in tools, en de door het model gevraagde aanroep verschijnt direct in response.output, zonder extra nestingsniveaus.
response = client.responses.create(
model="gpt-5.6-terra",
input="What is the weather like in Lyon?",
tools=[{
"type": "function",
"name": "get_meteo",
"description": "Get the weather for a city",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "Name of the city"}
},
"required": ["city"]
}
}]
)
# De API retourneert direct de uit te voeren functieaanroep
for item in response.output:
if item.type == "function_call":
print(f"Function: {item.name}, Arguments: {item.arguments}")
# Resultaat: Function: get_meteo, Arguments: {"city": "Lyon"}
Streaming retourneert niet langer een stroom van niet-gedifferentieerde chunks, maar getypte events. U filtert op event.type en weet precies wat u behandelt: een tekstfragment, een functieargument of het einde van de generatie:
stream = client.responses.create(
model="gpt-5.6-terra",
input="Tell a short story.",
stream=True
)
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
Snelle migratiegids
| Chat Completions | Responses API |
|---|---|
client.chat.completions.create() | client.responses.create() |
messages=[...] | input="..." of input=[...] |
response.choices[0].message.content | response.output_text |
| Handmatige geschiedenis | previous_response_id |
response_format | text={"format": {...}} |
tools + tool_choice | tools (vereenvoudigd) |
Moet u direct migreren?
De Chat Completions API blijft functioneel en wordt niet verwijderd. Bestaande code die werkt, vereist geen wijzigingen en levert niets op door een haastige herschrijving als deze steunt op een testpijplijn die rond het oude formaat is gebouwd. Als u bovendien afhankelijk bent van een bibliotheek van derden die de Responses API nog niet ondersteunt, wacht dan op de update daarvan. Voor elk nieuw project is het antwoord echter duidelijk: de Responses API is het startpunt en de rest van deze cursus gaat uit van die veronderstelling.
Belangrijkste punten
- De Responses API vervangt Chat Completions met een eenvoudigere interface
- Sessiebeheer aan serverzijde elimineert de noodzaak om geschiedenis opnieuw te verzenden
- Gestructureerde uitvoer en functieaanroepen zijn native geïntegreerd
- Migratie is eenvoudig: de concepten blijven hetzelfde, alleen de syntaxis verandert