Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Migratie naar de Responses API in fasen

Les 12 van 12 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Waarom en wanneer migreren
  2. Stap 1: Breng uw gebruikte functies in kaart
  3. Stap 2: Migreer basisaanroepen
  4. Stap 3: Migreer conversaties met meerdere beurten
  5. Stap 4: Profiteer van nieuwe functies
  6. Aanbevolen migratiestrategie
  7. Belangrijkste punten
  8. Test uw kennis

Bijgewerkt op 3 november 2026: De eerdere parametermapping gaf aan dat max_tokens zijn naam behoudt in de Responses API; de tabel van xAI wijzigt dit echter naar max_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:

  • messages met rol system → instructions (dedicated parameter)
  • messages met rol user → input (eenvoudige string)
  • response.choices[0].message.content → response.output_text
  • max_tokens → max_output_tokens, volgens de mapping-tabel van xAI; temperature behoudt zijn naam
  • response.usage.prompt_tokens en completion_tokens → input_tokens en output_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:

  1. Identificeer Chat Completions-aanroepen in uw code
  2. Classificeer ze op complexiteit (basis → streaming → function calling)
  3. Migreer eerst nieuwe eindpunten of functies (greenfield)
  4. Migreer daarna de eenvoudigste bestaande aanroepen
  5. 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’.