Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Sessies, gebeurtenissen en levenscyclus

Les 2 van 18 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Sessies, gebeurtenissen en levenscyclus
  2. De levenscyclus van een sessie
  3. Een sessie configureren
  4. Het gebeurtenissysteem
  5. Foutafhandeling
  6. Belangrijkste punten

Bijgewerkt op 2 november 2026 — Audiomodellen. Verschillende modellen in deze cursus zijn verouderd: tts-1, tts-1-hd en gpt-4o-mini-tts stoppen met werken op 6 januari 2027 (vervanging: gpt-realtime-2.1-mini, waarvan de OpenAI TTS-gids aangeeft dat deze niet wordt ondersteund door /v1/audio/speech: migratie van spraaksynthese verschuift naar de Realtime API); gpt-realtime, gpt-4o-realtime en legacy audiomodellen op 20 januari 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe en /v1/audio/translations op 26 februari 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Voor full-duplex spraak is GPT-Live 1 beschikbaar in de API sinds 10 september 2026.

Gecorrigeerd op 3 november 2026. Input-transcriptie gebruikte gpt-live-transcribe, wat alleen werkt in een transcriptie-sessie en noch server_vad noch semantic_vad ondersteunt. In een conversatiesessie zoals deze, waar VAD elke beurt valideert, specificeert de documentatie gpt-transcribe, dat gevalideerde beurten transcribeert en eerdere beurten als context gebruikt. Bronnen: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.

Sessies, gebeurtenissen en levenscyclus

Elke WebSocket-verbinding met de Realtime API creëert een sessie. Deze sessie is de fundamentele beheerseenheid: deze kapselt de modelconfiguratie, de conversatiegeschiedenis, beschikbare tools en de huidige staat van de interactie in. Inzicht in de levenscyclus hiervan is essentieel voor het bouwen van robuuste spraakagenten.

De levenscyclus van een sessie

Zodra de WebSocket-verbinding tot stand is gebracht, zendt de server een session.created-gebeurtenis uit. De sessie doorloopt verschillende fasen:

1

Verbinding → session.created

De server bevestigt de sessie met een unieke ID en standaardconfiguratie.

2

Configuratie → session.update

U verzendt session.update om instructies, stem, tools en modaliteiten te definiëren.

3

Actieve conversatie

Uitwisseling van audio- en tekstgebeurtenissen tussen client en server.

4

Afsluiting → WebSocket disconnect

De sessie wordt vernietigd wanneer de verbinding sluit. Er wordt geen staat op de server bewaard.

Een sessie configureren

Na session.created verzendt u een session.update-gebeurtenis om het gedrag van het model te configureren. Het transcriberen van wat de gebruiker zegt (audio.input.transcription) is optioneel: zonder dit ontvangt u de stem maar niet de tekst. languages specificeert de verwachte talen en verbetert de herkenning:

import asyncio
import websockets
import json

async def configure_session():
    headers = {
        "Authorization": f"Bearer {OPENAI_API_KEY}"
    }

    async with websockets.connect(URL, additional_headers=headers) as ws:
        # Wacht op session.created
        event = json.loads(await ws.recv())
        session_id = event["session"]["id"]
        print(f"Session created: {session_id}")

        # Configureer de sessie
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "type": "realtime",
                "output_modalities": ["audio"],
                "instructions": "You are a French-speaking voice assistant. "
                                "Respond concisely and naturally.",
                "audio": {
                    "input": {
                        "format": {"type": "audio/pcm", "rate": 24000},
                        "transcription": {"model": "gpt-transcribe", "languages": ["fr"]},
                        "turn_detection": {
                            "type": "server_vad",
                            "threshold": 0.5,
                            "prefix_padding_ms": 300,
                            "silence_duration_ms": 500
                        }
                    },
                    "output": {
                        "format": {"type": "audio/pcm", "rate": 24000},
                        "voice": "marin"
                    }
                },
                "tools": []
            }
        }))

        # Wacht op bevestiging (andere gebeurtenissen kunnen eerder arriveren)
        while True:
            event = json.loads(await ws.recv())
            if event["type"] == "session.updated":
                print("Session updated")
                break
            if event["type"] == "error":
                raise RuntimeError(event["error"]["message"])

Belangrijke sessieparameters

Parameter Beschrijving Aanbevolen waarde
output_modalities Uitvoermodaliteiten ["audio"] (of ["text"])
audio.output.voice Synthesestem marin, cedar, alloy, echo, enz.
audio.input.turn_detection Detectie einde spraak server_vad met drempelwaarde 0.5
audio.input.format Formaat binnenkomende audio {"type": "audio/pcm", "rate": 24000}

Het gebeurtenissysteem

De Realtime API is volledig event-driven. Elk uitgewisseld bericht is een JSON-object met een type-veld dat de aard ervan bepaalt. Gebeurtenissen vallen in twee categorieën:

Clientgebeurtenissen (u → server)

# De belangrijkste gebeurtenissen die u verzendt
client_events = {
    "session.update":              "Configuratie wijzigen",
    "input_audio_buffer.append":   "Een audiofragment verzenden",
    "input_audio_buffer.commit":   "De audiobuffer committen",
    "input_audio_buffer.clear":    "De audiobuffer wissen",
    "conversation.item.create":    "Handmatig een bericht toevoegen",
    "conversation.item.truncate":  "Een antwoord inkorten",
    "conversation.item.delete":    "Een bericht verwijderen",
    "response.create":             "Een antwoord triggeren",
    "response.cancel":             "Het huidige antwoord annuleren",
}

Servergebeurtenissen (server → u)

# De belangrijkste gebeurtenissen die u ontvangt
server_events = {
    "session.created":             "Sessie geïnitialiseerd",
    "session.updated":             "Configuratie toegepast",
    "input_audio_buffer.speech_started":  "Spraak gedetecteerd",
    "input_audio_buffer.speech_stopped":  "Stilte gedetecteerd",
    "conversation.item.created":   "Nieuw bericht in geschiedenis",
    "response.created":            "Generatie gestart",
    "response.output_audio.delta":        "Audiofragment van antwoord",
    "response.output_audio_transcript.delta": "Transcriptiefragment",
    "response.done":               "Antwoord voltooid",
    "error":                       "Fout",
}

Foutafhandeling

Fouten worden uitgezonden via een gebeurtenis van het type error. U moet deze altijd onderscheppen:

async def handle_events(ws):
    async for raw_message in ws:
        event = json.loads(raw_message)
        event_type = event["type"]

        if event_type == "error":
            error = event["error"]
            print(f"Fout [{error['type']}]: {error['message']}")

            if error["type"] == "invalid_request_error":
                # Configuratiefout, herstellen en opnieuw proberen
                pass
            elif error["type"] == "server_error":
                # Probleem aan de kant van OpenAI, opnieuw verbinden
                pass

        elif event_type == "session.updated":
            print("Configuratie succesvol toegepast")

        elif event_type == "response.done":
            usage = event["response"].get("usage", {})
            print(f"Gebruikte tokens: {usage}")

Belangrijkste punten

  • Een sessie wordt automatisch gemaakt bij het tot stand brengen van de WebSocket-verbinding en vernietigd bij het verbreken ervan
  • session.update configureert de sessie na session.created; wacht op session.updated voordat u vertrouwt op de nieuwe configuratie
  • Gebruik voor het transcriberen van input in een conversatiesessie gpt-transcribe; gpt-live-transcribe is gereserveerd voor transcriptiesessies
  • Het protocol is puur event-driven: elk bericht heeft een type dat de verwerking bepaalt
  • Clientgebeurtenissen sturen de interactie aan; servergebeurtenissen rapporteren resultaten
  • Foutafhandeling is cruciaal: luister altijd naar error-gebeurtenissen