Architecture WebSocket de la Realtime API

Mise à jour du 2 novembre 2026 — modèles audio. Plusieurs modèles de ce cours sont dépréciés : tts-1, tts-1-hd et gpt-4o-mini-tts s’arrêtent le 6 janvier 2027 (remplaçant indiqué : gpt-realtime-2.1-mini, que le guide TTS d’OpenAI déclare non pris en charge par /v1/audio/speech : la migration de la synthèse vocale passe par l’API Realtime) ; gpt-realtime, gpt-4o-realtime et les anciens modèles audio le 20 janvier 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5) ; whisper-1, gpt-4o-transcribe et /v1/audio/translations le 26 février 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Pour la voix full-duplex, GPT-Live 1 est disponible dans l’API depuis le 10 septembre 2026. Complément du 3 novembre 2026 : section sur les trois architectures vocales d’OpenAI (GPT-Live, API Realtime, chaîne de traitement) et sur le choix du transport (WebRTC, WebSocket, SIP), d’après les guides Voice agents, Audio and voice et Getting started with the Realtime API ; durée maximale d’une session : 60 minutes (Realtime conversations).

Architecture WebSocket de la Realtime API

La Realtime API d’OpenAI représente un changement de paradigme fondamental dans l’interaction avec les modèles de langage. Contrairement aux API REST classiques qui fonctionnent en requête-réponse, la Realtime API utilise le protocole WebSocket pour établir une connexion bidirectionnelle persistante entre votre application et le modèle.

Cette architecture permet des échanges audio en temps réel : vous envoyez de l’audio, le modèle le traite et répond vocalement, avec une latence faible, sans étape intermédiaire de transcription ni de synthèse vocale. C’est l’une des briques pour construire des agents vocaux conversationnels, et le cœur de ce cours.

Trois architectures pour la voix en 2026

Avant d’ouvrir un WebSocket, situez la Realtime API parmi les solutions d’OpenAI. Le guide Voice agents en distingue trois :

Pour une nouvelle application de conversation vocale, la page Audio and voice d’OpenAI conseille désormais de commencer par GPT-Live. L’API Realtime reste le bon point de départ quand l’agent doit tenir dans une seule session, avec interruption par l’utilisateur, première réponse audio rapide, prise de parole naturelle et outils appelés en direct. La chaîne convient quand chaque étape doit rester visible : conserver la transcription, vérifier une règle avant que l’agent réponde, n’émettre la voix qu’une fois la réponse validée.

Ce cours se concentre sur l’API Realtime et sur la chaîne, dont les briques (transcription, synthèse vocale) font l’objet de ses parties suivantes.

WebRTC, WebSocket ou SIP

Le transport dépend de l’endroit où se trouve l’audio. D’après la documentation : WebRTC pour l’audio d’un navigateur, avec un secret client éphémère créé par votre serveur ; WebSocket pour un pipeline audio côté serveur ; SIP pour les appels téléphoniques. Une connexion de contrôle côté serveur permet en plus à un backend de confiance d’observer et de piloter une session média. Cette leçon détaille le WebSocket, le plus simple pour comprendre les événements échangés ; dans un navigateur, préférez WebRTC. Une session Realtime dure au plus 60 minutes.

WebSocket vs REST : pourquoi ce choix ?

Dans une architecture REST traditionnelle, chaque interaction nécessite une requête HTTP complète : ouverture de connexion TCP, négociation TLS, envoi des headers, attente de la réponse, fermeture. Pour de l’audio en temps réel, cette surcharge est rédhibitoire.

Le protocole WebSocket maintient un canal ouvert en permanence. Une fois la connexion établie, client et serveur peuvent s’envoyer des messages à tout moment, sans attendre que l’autre ait terminé.

Établir une connexion WebSocket

Voici comment établir une connexion à la Realtime API en 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("Connecté à la Realtime API")

        # Recevoir l'événement de bienvenue
        response = await ws.recv()
        event = json.loads(response)
        print(f"Type: {event['type']}")
        # → "session.created"

        # Maintenir la connexion ouverte
        await asyncio.Future()

asyncio.run(connect_realtime())

L’URL de connexion inclut le modèle comme paramètre de requête. Depuis le passage de l’API en disponibilité générale, seul l’en-tête d’authentification est requis — le header OpenAI-Beta: realtime=v1 de la phase beta n’existe plus.

Interface relevée le 5 août 2026 — la Realtime API évolue (modèles, noms d’événements, format de session) : en cas de doute, vérifiez la documentation officielle.

Architecture d’une application Realtime

Une application utilisant la Realtime API suit une architecture en couches :

Le rôle du serveur proxy

En développement, vous pouvez connecter directement votre application à la Realtime API. En production, un serveur proxy est indispensable pour :

• Protéger votre clé API — ne jamais l’exposer côté client
• Authentifier vos utilisateurs — vérifier les tokens avant d’ouvrir la session
• Contrôler les coûts — limiter la durée des sessions et le nombre de tokens
• Logger les interactions — pour le débogage et la conformité

# Exemple simplifié d'un proxy WebSocket avec 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())

Points clés à retenir

• Trois architectures vocales chez OpenAI : GPT-Live (conseillée pour une nouvelle application conversationnelle), l’API Realtime (parole, raisonnement et outils dans une session), la chaîne transcription → agent → synthèse
• WebRTC pour l’audio du navigateur, WebSocket pour un pipeline serveur, SIP pour le téléphone ; une session dure au plus 60 minutes
• La Realtime API utilise WebSocket pour une communication bidirectionnelle à faible latence
• La connexion est persistante : une seule ouverture pour toute la session conversationnelle
• L’architecture en couches sépare audio, transport, logique métier et proxy serveur
• En production, un serveur proxy est indispensable pour la sécurité et le contrôle des coûts
• Le protocole est événementiel : chaque message est un objet JSON avec un champ type