Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

WebSocket-architectuur van de Realtime API

Les 1 van 18 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. WebSocket-architectuur van de Realtime API
  2. Drie spraakarchitecturen in 2026
  3. WebRTC, WebSocket of SIP
  4. WebSocket versus REST: waarom deze keuze?
  5. Een WebSocket-verbinding tot stand brengen
  6. Architectuur van een Realtime-applicatie
  7. 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 op 6 januari 2027 (vervanger: gpt-realtime-2.1-mini, waarvan de OpenAI TTS-gids aangeeft dat deze niet wordt ondersteund door /v1/audio/speech: migratie van spraaksynthese gaat 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. Addendum 3 november 2026: sectie over OpenAI’s drie spraakarchitecturen (GPT-Live, Realtime API, verwerkingsketen) en transportkeuze (WebRTC, WebSocket, SIP), gebaseerd op de gidsen Voice agents, Audio en spraak en Aan de slag met de Realtime API; maximale sessieduur: 60 minuten (Realtime conversations).

WebSocket-architectuur van de Realtime API

OpenAI’s Realtime API vertegenwoordigt een fundamentele paradigmaverschuiving in hoe u met taalmodellen interacteert. In tegenstelling tot traditionele REST-API’s die werken op basis van een request-response-cyclus, gebruikt de Realtime API het WebSocket-protocol om een persistente, bidirectionele verbinding tot stand te brengen tussen uw applicatie en het model.

Deze architectuur maakt realtime audio-uitwisseling mogelijk: u verzendt audio, het model verwerkt dit en reageert vocaal met lage latentie, waarbij tussenliggende transcriptie- of tekst-naar-spraak-stappen worden overgeslagen. Dit is een van de kernbouwstenen voor conversationele voice agents en het hart van deze cursus.

Drie spraakarchitecturen in 2026

Voordat u een WebSocket opent, plaatst u de Realtime API in de context van OpenAI’s andere oplossingen. De gids Voice agents onderscheidt drie benaderingen:

ArchitectuurHet beste voorWaarom kiezen?
GPT-LiveFull-duplex gesprekken met een aparte backendHet spraakmodel luistert terwijl het spreekt en delegeert redeneren en toolgebruik aan een backend naar keuze; houdt uw bestaande tekstagent intact
Realtime APISpraak, redeneren en tools in één sessieEén model interpreteert audio, beslist wat te doen en spreekt het antwoord uit
VerwerkingsketenGranulaire controle over elke stapTranscriptie, dan tekstagent, dan spraaksynthese: u inspecteert of transformeert tekst tussen stappen en wisselt elk component onafhankelijk uit

Voor nieuwe voice-conversatieapplicaties raadt OpenAI’s pagina Audio en spraak nu aan om te beginnen met GPT-Live. De Realtime API blijft het juiste startpunt wanneer de agent binnen één sessie moet passen, met ondersteuning voor onderbreking door de gebruiker, snelle eerste audiorespons, natuurlijke beurtwisseling en directe tool-aanroepen. De verwerkingsketen werkt het beste wanneer elke stap zichtbaar moet blijven: transcripties behouden, regels afdwingen voordat de agent antwoordt, of spraak pas uitzenden na validatie van het antwoord.

Deze cursus focust op de Realtime API en de verwerkingsketen, waarvan de componenten (transcriptie, spraaksynthese) in volgende secties aan bod komen.

WebRTC, WebSocket of SIP

Uw transportkeuze hangt af van waar de audio vandaan komt. Volgens de documentatie: gebruik WebRTC voor browseraudio, met een ephemeraal clientgeheim gegenereerd door uw server; WebSocket voor server-side audiopipelines; SIP voor telefoongesprekken. Een server-side controleverbinding stelt een vertrouwde backend ook in staat om een mediasessie te observeren en te sturen. Deze les behandelt WebSocket, de eenvoudigste manier om uitgewisselde events te begrijpen; in een browser geeft u de voorkeur aan WebRTC. Een Realtime-sessie duurt maximaal 60 minuten.

WebSocket versus REST: waarom deze keuze?

In een traditionele REST-architectuur vereist elke interactie een compleet HTTP-verzoek: een TCP-verbinding openen, TLS-onderhandeling, headers verzenden, wachten op het antwoord en de verbinding sluiten. Voor realtime audio is deze overhead prohibitief.

Criterium REST (Responses API) WebSocket (Realtime API)
Latentie 200–500 ms per verzoek < 50 ms na verbinding
Richting Alleen client → server Gelijktijdig bidirectioneel
Verbinding Nieuw voor elk verzoek Persistent (sessie)
Audio Volledig bestand vereist Chunk-per-chunk streaming

Het WebSocket-protocol houdt een kanaal continu open. Eenmaal tot stand gebracht, kunnen client en server op elk moment berichten verzenden zonder te wachten tot de ander klaar is.

Een WebSocket-verbinding tot stand brengen

Zo bouwt u een verbinding op met de Realtime API in Python:

import asyncio
import websockets
import json

OPENAI_API_KEY = "sk-..."
URL = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1"

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

    async with websockets.connect(URL, additional_headers=headers) as ws:
        print("Connected to Realtime API")

        # Receive the welcome event
        response = await ws.recv()
        event = json.loads(response)
        print(f"Type: {event['type']}")
        # → "session.created"

        # Keep the connection open
        await asyncio.Future()

asyncio.run(connect_realtime())

De verbindings-URL bevat het model als query-parameter. Sinds de API algemeen beschikbaar is, is alleen de authenticatie-header vereist; de OpenAI-Beta: realtime=v1-header uit de bètafase is verdwenen.

Interface opgemerkt op 5 augustus 2026 — De Realtime API evolueert (modellen, event-namen, sessie-indeling): raadpleeg bij twijfel de officiële documentatie.

Architectuur van een Realtime-applicatie

Een applicatie die de Realtime API gebruikt, volgt een gelaagde architectuur:

1

Audiolaag (capture/playback)

Legt de microfoon vast, speelt audio-antwoorden af. Gebruikt PyAudio, sounddevice of de Web Audio API in de browser.

2

WebSocket-laag (transport)

Beheert de persistente verbinding, codeert/decodeert JSON-events, handelt herverbindingen af.

3

Applicatielaag (business logic)

Orchestreert het gesprek, beheert context, roept tools aan, verwerkt resultaten.

4

Serverlaag (optionele proxy)

In productie beschermt een tussenliggende server de API-sleutel en voegt server-side business logic toe.

De rol van de proxyserver

Tijdens ontwikkeling kunt u uw applicatie direct verbinden met de Realtime API. In productie is een proxyserver essentieel om:

  • Uw API-sleutel te beschermen — exposeer deze nooit aan de clientkant
  • Uw gebruikers te authenticeren — verifieer tokens voordat u de sessie opent
  • Kosten te beheersen — beperk sessieduur en tokengebruik
  • Interacties te loggen — voor debugging en compliance
# Simplified example of a WebSocket proxy with FastAPI
from fastapi import FastAPI, WebSocket
import websockets

app = FastAPI()

@app.websocket("/ws/realtime")
async def proxy_realtime(client_ws: WebSocket):
    await client_ws.accept()

    headers = {"Authorization": f"Bearer {OPENAI_API_KEY}"}

    async with websockets.connect(URL, additional_headers=headers) as openai_ws:
        async def forward_to_openai():
            async for message in client_ws.iter_text():
                await openai_ws.send(message)

        async def forward_to_client():
            async for message in openai_ws:
                await client_ws.send_text(message)

        await asyncio.gather(forward_to_openai(), forward_to_client())

Belangrijkste punten

  • Drie spraakarchitecturen bij OpenAI: GPT-Live (aanbevolen voor nieuwe conversatie-apps), Realtime API (spraak, redeneren en tools in één sessie) en de keten transcriptie → agent → synthese
  • WebRTC voor browseraudio, WebSocket voor server-pipelines, SIP voor telefonie; sessies duren maximaal 60 minuten
  • Realtime API gebruikt WebSocket voor bidirectionele communicatie met lage latentie
  • De verbinding is persistent: één opening voor de hele conversatiesessie
  • Gelaagde architectuur scheidt audio, transport, business logic en server-proxy
  • In productie is een proxyserver essentieel voor beveiliging en kostenbeheersing
  • Het protocol is event-driven: elk bericht is een JSON-object met een type-veld