Tutoriel API GPT-Realtime-2 : trois tests, trois verdicts

Notre article d’introduction à GPT-Realtime-2 présentait le lancement, les benchmarks annoncés et la raison pour laquelle OpenAI a scindé la voix temps réel en une petite famille de modèles. Ce tutoriel reprend là où l’article s’arrêtait : se connecter à l’API, envoyer de l’audio et voir ce qui change côté code.

Cette séparation a un vrai impact pratique. Le test 1 utilise gpt-realtime-whisper pour la transcription, le test 2 utilise gpt-realtime-translate pour la traduction en direct, et le test 3 utilise gpt-realtime-2 pour un assistant vocal. Le modèle principal peut aussi gérer des tâches plus simples comme la traduction ou la transcription, mais vous paieriez pour un niveau de raisonnement et des modes de réponse non nécessaires : ce serait disproportionné.

Configuration de l’API GPT-Realtime-2 en Python

Avant les tests, il est utile de séparer le transport, l’authentification et le format audio. Ces détails restent globalement identiques d’un exemple à l’autre. Les différences portent sur les endpoints de modèle et les noms d’événements, au fil du passage d’une sortie texte à une parole traduite, puis à une boucle vocale complète.

Choisir entre WebRTC et WebSocket

La documentation OpenAI donne une règle simple : utilisez WebRTC pour les clients navigateur et mobile, et WebSockets pour les applications côté serveur. WebRTC gère le jitter buffering et le transport audio. Les WebSockets sont pertinents quand le back-end reçoit déjà de l’audio brut d’un fournisseur de téléphonie ou d’une chaîne média.

Deux chemins de transport pour l’API Realtime. Image par l’auteur.

Pour cette raison, les trois tests Python utilisent des WebSockets. Ce chemin expose directement les noms d’événements, ce qui rend les différences de modèle visibles dans le code. Pour un build navigateur, utilisez des secrets clients éphémères afin que votre clé API n’atteigne jamais le frontend.

Environnement Python et packages

Utilisez Python 3.9 ou plus récent. Le code complet des quatre scripts est disponible sur github.com/KhalidAbdelaty/gpt-realtime-api. Clonez-le d’abord, puis installez les dépendances :

git clone https://github.com/KhalidAbdelaty/gpt-realtime-api.git\ncd gpt-realtime-api\npip install websocket-client sounddevice numpy python-dotenv

websocket-client gère le socket. sounddevice capture l’audio du micro, numpy convertit le buffer, et python-dotenv charge la clé API. Sur macOS, vous devrez peut-être exécuter brew install portaudio avant que sounddevice ne fonctionne. Sous Linux, installez portaudio19-dev.

Créez un fichier .env à la racine de votre projet :

OPENAI_API_KEY=sk-...

Puis chargez-la dans chaque script :

import os\nfrom dotenv import load_dotenv\n\nload_dotenv()\nOPENAI_API_KEY = os.environ.get(\"OPENAI_API_KEY\")

Authentification et URL WebSocket

Les connexions côté serveur utilisent un en-tête Authorization: Bearer lors du handshake WebSocket. Ajoutez OpenAI-Safety-Identifier si votre application suit des utilisateurs individuels. Voici les chemins utilisés plus loin dans les tests :

# Agent vocal\nwss://api.openai.com/v1/realtime?model=gpt-realtime-2\n\n# Traduction\nwss://api.openai.com/v1/realtime/translations?model=gpt-realtime-translate\n\n# Transcription\nwss://api.openai.com/v1/realtime?intent=transcription

Ce chemin de traduction est important dans le test 2, car c’est le seul endpoint qui n’utilise pas directement /v1/realtime.

Test 1 : transcription audio en temps réel avec GPT-Realtime-Whisper

La transcription est un cas classique de surconception. Si la sortie attendue est uniquement du texte, le modèle de transcription suffit.

Ce que nous testons

gpt-realtime-whisper prend de l’audio en entrée et émet des deltas de transcription. Il ne raisonne pas, n’appelle pas d’outils et ne parle pas en retour. Ce périmètre plus restreint explique la facturation à la durée audio, plutôt que le modèle de jetons utilisé par gpt-realtime-2. Nous revenons sur ces tarifs plus loin.

Parcours du code

Le champ clé est session.type: \"transcription\". Il indique à l’API d’ignorer les réponses de l’assistant et d’émettre uniquement des événements de transcription. Le script complet gère aussi la capture micro et le threading. Voici la partie qui modifie le comportement de session Realtime :

session_config = {\n    \"type\": \"session.update\",\n    \"session\": {\n        \"type\": \"transcription\",\n        \"audio\": {\n            \"input\": {\n                \"format\": {\"type\": \"audio/pcm\", \"rate\": 24000},\n                \"transcription\": {\n                    \"model\": \"gpt-realtime-whisper\",\n                    \"language\": \"en\"\n                },\n                \"turn_detection\": None\n            }\n        }\n    }\n}\n\nws.send(json.dumps(session_config))\nws.send(json.dumps({\n    \"type\": \"input_audio_buffer.append\",\n    \"audio\": audio_b64\n}))\nws.send(json.dumps({\"type\": \"input_audio_buffer.commit\"}))

Utilisez de l’audio PCM16 mono à 24 kHz, encodé en base64. Contrairement à la session d’agent vocal, le script valide le buffer d’entrée manuellement à intervalles réguliers au lieu d’utiliser la détection de tours server_vad. Les validations vides lèvent input_audio_buffer_commit_empty, c’est pourquoi le script complet ne valide qu’après l’envoi d’audio réel.

Les deltas de transcription arrivent mot à mot en temps réel. Image par l’auteur.

Comportement observé

Sur mes tests locaux, les résultats de transcription apparaissaient dans la fenêtre de commit, environ 3 à 4 secondes après le début de la prise de parole. Comme cette configuration repose sur des commits manuels plutôt que sur la VAD, la latence dépend de l’intervalle de commit. 

Attention aussi à l’ordre : les événements de complétion issus de tours qui se chevauchent peuvent arriver dans le désordre ; si vous construisez une interface autour du flux, réconciliez-les avec item_id.

La transcription est déclenchée par un commit manuel périodique, pas par détection de silence. Image par l’auteur.

Verdict : validé. Pour de la transcription en direct côté serveur, gpt-realtime-whisper a rempli le cahier des charges. Je testerais néanmoins avec de vrais micros, des accents et du bruit ambiant avant de fixer une cible de latence.

Test 2 : traduction en temps réel avec GPT-Realtime-Translate

La traduction vocale en direct ressemble d’abord à la transcription, mais le cycle de session est différent. L’endpoint de traduction supprime la boucle de réponse de l’assistant, ce qui raccourcit l’exemple.

Ce que nous testons

Les sessions de traduction n’ont pas de boucle de tours avec assistant et pas de response.create. Le modèle agit comme un interprète en direct, pas comme un agent conversationnel. Pour du questions-réponses, des outils ou un état de conversation, l’article bascule sur gpt-realtime-2 au test 3.

Les sessions de traduction utilisent un endpoint dédié et séparé. Image par l’auteur.

Le modèle prend en charge plus de 70 langues en entrée et 13 langues en sortie. Vous définissez la cible via session.audio.output.language ; la détection de la langue source est automatique. Les limites sont claires : pas de prompt personnalisé, pas de sélection de voix, pas de glossaires métier.

Parcours du code

Comme indiqué plus haut, la traduction utilise l’URL WebSocket /translations. Deux autres détails changent aussi : le champ cible session.audio.output.language et le nom d’événement session.input_audio_buffer.append. Notez le préfixe session.. Les sessions de traduction l’emploient ici.

url = \"wss://api.openai.com/v1/realtime/translations?model=gpt-realtime-translate\"\n\nsession_config = {\n    \"type\": \"session.update\",\n    \"session\": {\n        \"audio\": {\n            \"output\": {\"language\": \"es\"},\n            \"input\": {\n                \"transcription\": {\"model\": \"gpt-realtime-whisper\"},\n                \"noise_reduction\": {\"type\": \"near_field\"}\n            }\n        }\n    }\n}\n\nws.send(json.dumps(session_config))\nws.send(json.dumps({\n    \"type\": \"session.input_audio_buffer.append\",\n    \"audio\": audio_b64\n}))

L’audio traduit arrive via session.output_audio.delta, et les octets audio se trouvent dans event[\"delta\"], pas event[\"audio\"]. Les transcriptions source et traduite arrivent séparément :

if event_type == \"session.output_audio.delta\":\n    audio_out_queue.put(base64.b64decode(event[\"delta\"]))\nelif event_type == \"session.input_transcript.delta\":\n    print(\"[EN]\", event.get(\"delta\", \"\"), end=\"\")\nelif event_type == \"session.output_transcript.delta\":\n    print(\"[ES]\", event.get(\"delta\", \"\"), end=\"\")

Un cas limite : si l’audio source est déjà dans la langue cible, le modèle peut produire du silence plutôt que de le laisser passer tel quel.

Comportement observé

Pour de courtes phrases anglais → espagnol, l’audio traduit commençait avant la fin de l’énoncé source. Le terminal affichait des lignes [EN] et [ES] entrelacées au fil des deltas. Des paires de langues plus éloignées peuvent attendre davantage de contexte. Je pouvais suivre la voix traduite sans difficulté, mais la sélection de voix personnalisée n’est pas disponible.

Verdict : validé, avec réserve. gpt-realtime-translate fonctionne pour la traduction directe en live. Il est moins indiqué quand le contrôle terminologique ou l’identité vocale sont essentiels.

Test 3 : construire un assistant vocal avec tours de parole et interruption

C’est le test gpt-realtime-2 : un agent vocal qui écoute, parle, conserve le contexte et peut appeler des outils. C’est aussi le point où le code client compte davantage, car la lecture et l’état des tours peuvent se désynchroniser.

Ce que nous testons

gpt-realtime-2 est un modèle de raisonnement de parole à parole. Il évite une chaîne STT → LLM → TTS séparée, et sa fenêtre de contexte de 128K offre plus d’aisance aux longues sessions. Le raisonnement se règle via reasoning.effort ; commencez à low sauf si la tâche exige plus, car des réglages plus élevés ajoutent de la latence.

Parcours du code

La configuration ci-dessous utilise semantic_vad, qui s’appuie sur des indices de parole plutôt que sur le simple silence. eagerness contrôle la vitesse à laquelle le modèle décide que l’utilisateur a fini. À noter : le nom du modèle, les paramètres de sortie audio, le response.create manuel et le nom de l’événement audio de l’assistant :

session_config = {\n    \"type\": \"session.update\",\n    \"session\": {\n        \"type\": \"realtime\",\n        \"model\": \"gpt-realtime-2\",\n        \"output_modalities\": [\"audio\"],\n        \"audio\": {\n            \"input\": {\n                \"format\": {\"type\": \"audio/pcm\", \"rate\": 24000},\n                \"transcription\": {\"model\": \"gpt-realtime-whisper\", \"language\": \"en\"},\n                \"turn_detection\": {\n                    \"type\": \"semantic_vad\",\n                    \"eagerness\": \"medium\",\n                    \"create_response\": False,\n                    \"interrupt_response\": True\n                }\n            },\n            \"output\": {\n                \"format\": {\"type\": \"audio/pcm\", \"rate\": 24000},\n                \"voice\": \"marin\"\n            }\n        },\n        \"instructions\": \"You are a helpful voice assistant. Keep answers short.\",\n        \"reasoning\": {\"effort\": \"low\"}\n    }\n}

Quand la transcription de l’utilisateur se termine, le client crée la réponse de l’assistant. L’audio de l’assistant arrive ensuite via response.output_audio.delta, et non response.audio.delta.

if event_type == \"conversation.item.input_audio_transcription.completed\":\n    ws.send(json.dumps({\"type\": \"response.create\"}))\n\nelif event_type == \"response.output_audio.delta\":\n    audio_out_queue.put(base64.b64decode(event[\"delta\"]))

Gérer l’interruption (barge-in)

La séquence d’interruption est facile à rater. Quand l’utilisateur parle par-dessus l’assistant, le serveur envoie input_audio_buffer.speech_started. Le client stoppe la lecture, enregistre la portion déjà jouée, puis envoie conversation.item.truncate avec audio_end_ms pour indiquer où la coupure a eu lieu. Sinon, le serveur continue à transcrire du texte que l’utilisateur n’a jamais entendu, et le tour suivant peut être décalé.

if current_response_item_id and playback_position_ms > 0:\n    ws.send(json.dumps({\n        \"type\": \"conversation.item.truncate\",\n        \"item_id\": current_response_item_id,\n        \"content_index\": 0,\n        \"audio_end_ms\": playback_position_ms\n    }))

Un point pratique avec les haut-parleurs d’ordinateur portable : le micro peut reprendre l’audio de l’assistant et le renvoyer au modèle. Le script d’exemple utilise MUTE_MIC_DURING_ASSISTANT = True pour couper le flux d’entrée pendant que l’assistant parle et un court délai après. Passez-le à False uniquement si vous portez un casque et souhaitez la prise en charge de l’interruption.

La troncature maintient la synchronisation serveur-client. Image par l’auteur.

WebRTC et SIP gèrent davantage de buffering. Avec la voie WebSocket utilisée ici, c’est au client de le faire. Le compteur du script suffit pour une démo ; en production, suivez les horodatages du flux de sortie audio.

Configurer des préambules pour la latence de raisonnement

Quand reasoning.effort dépasse low, le silence devient perceptible. Vous pouvez ajouter de courts préambules parlés dans le prompt système :

# Preambles\nUse a short spoken update before longer tasks.\nKeep preambles under five seconds.\nSkip preambles for short factual questions.

Ce comportement est documenté pour gpt-realtime-2.

Comportement observé

La prise de tours a fonctionné avec les réglages par défaut dans une pièce calme. Avec les haut-parleurs du portable, j’ai dû couper le micro ; sans cela, le modèle entendait sa propre sortie et créait une boucle d’écho. 

Dans des pièces plus bruyantes, les réglages VAD et le placement du micro comptaient davantage. La mémoire de conversation est restée cohérente sur un test de dix minutes, mais je ne publierais pas une application plus longue sans plan de reconnexion.

Verdict : validé pour la boucle vocale principale. gpt-realtime-2 a géré un assistant à faible effort de raisonnement dans mon test. Le travail supplémentaire se situe côté client : lecture, gestion des interruptions, reconnexions et appels d’outils si nécessaire.

Démo Streamlit : trois modèles dans une même interface

L’application Streamlit place les tests derrière un sélecteur d’onglets. Elle permet d’enregistrer de l’audio, de choisir une langue cible et de comparer les chemins des modèles sans modifier les scripts. Je l’ai gardée comme application de démo plutôt que fil conducteur principal, car les scripts en terminal montrent plus directement les événements.

Trois modèles dans une interface à onglets. Image par l’auteur.

La vidéo de démonstration ci-dessous montre les onglets avec une clé API active. Chaque onglet utilise de vrais appels Realtime via WebSocket.