Bien démarrer avec Realtime API

Créez un agent vocal fonctionnant de parole à parole avec Realtime API. Le modèle traite directement l’audio, maintient l’état de la conversation et peut appeler des outils. Ce guide commence par l’utilisation du SDK Agents pour une application dans le navigateur. Consultez les guides de connexion de plus bas niveau si vous avez besoin d’un contrôle direct.

Pour des conversations en duplex intégral avec un backend délégué distinct, consultez GPT-Live. Pour comparer les architectures vocales et les pipelines en chaîne, consultez Agents vocaux.

Créez un agent vocal fonctionnant de parole à parole

Utilisez Realtime API lorsque l’interaction doit offrir la fluidité et l’immédiateté d’une conversation. C’est le meilleur point de départ pour les agents vocaux qui doivent permettre à l’utilisateur de les interrompre, produire rapidement les premiers sons de leur réponse, gérer naturellement les tours de parole et utiliser des outils en temps réel.

Dans le navigateur, le déroulement habituel est le suivant :

1. Votre serveur applicatif crée un secret client éphémère pour la session Realtime.
2. Votre frontend crée une RealtimeSession.
3. La session se connecte via WebRTC dans le navigateur ou via WebSocket sur le serveur.
4. L’agent gère les tours de parole, les outils, les interruptions et les transferts entre agents au sein de cette session.

1
2
3
4
5
6
7
8
9
10
11
12
13
14import { RealtimeAgent, RealtimeSession } from "@openai/agents/realtime";

const agent = new RealtimeAgent({
  name: "Assistant",
  instructions: "You are a helpful voice assistant.",
});

const session = new RealtimeSession(agent, {
  model: "gpt-realtime-2.1",
});

await session.connect({
  apiKey: "ek_...(ephemeral key from your server)",
});

Ajoutez ensuite des outils, des transferts entre agents et des garde-fous au RealtimeAgent, comme vous le feriez pour un agent textuel. Gardez la gestion du transport audio dans la couche session et la logique métier dans la définition de l’agent.

Commencez par la documentation sur le transport si vous avez besoin d’un contrôle de plus bas niveau :

• Vue d’ensemble de l’audio et de la voix
• Realtime API avec WebRTC
• Realtime API avec WebSocket

Identifiants de sécurité

Si votre application identifie les utilisateurs finaux individuellement, incluez un identifiant de sécurité dans les requêtes à la Realtime API. OpenAI recommande ces identifiants sans les imposer. Ils aident OpenAI à détecter les comportements nuisibles et à appliquer les mesures à un utilisateur en particulier plutôt qu’à l’ensemble de votre organisation. Utilisez une valeur stable qui préserve la confidentialité, telle qu’un identifiant utilisateur interne haché.

Pour les requêtes à la Realtime API, envoyez l’identifiant dans l’en-tête OpenAI-Safety-Identifier. Si vous utilisez des tokens éphémères, définissez cet en-tête dans la requête côté serveur qui crée le secret client afin d’associer l’identifiant à la session. Si vous vous connectez depuis un serveur de confiance avec WebSocket ou l’interface WebRTC unifiée, définissez cet en-tête dans la requête de connexion.

Les identifiants de sécurité ne sont pas repris des requêtes à l’API Responses ni des autres sessions. Si vous utilisez le paramètre safety_identifier de l’API Responses ailleurs dans votre application, transmettez la même valeur stable lors de la création de chaque session Realtime ou de la connexion à celle-ci.

Migration de la version bêta vers la disponibilité générale (GA)

Si votre intégration Realtime utilise encore la version bêta, migrez-la vers l’interface en disponibilité générale (GA) avant de poursuivre vos développements. Voici les principaux changements :

• Supprimez l’en-tête OpenAI-Beta: realtime=v1 lors des appels à l’interface GA.
• Utilisez POST /v1/realtime/client_secrets pour créer des identifiants éphémères destinés aux clients web ou mobiles.
• Utilisez /v1/realtime/calls pour établir des sessions WebRTC.
• Adaptez la structure des sessions et des événements à l’interface GA. En particulier, définissez session.type, déplacez la configuration audio de sortie sous session.audio.output et utilisez les nouveaux noms d’événements de réponse, comme response.output_text.delta, response.output_audio.delta et response.output_audio_transcript.delta.
• Pour faire évoluer une application fonctionnant de parole à parole, partez de l’exemple pour navigateur. Pour faire évoluer un workflow de transcription, utilisez le guide Transcription en temps réel.

Consultez la référence des événements client Realtime, la référence des sessions Realtime et l’exemple pour navigateur pour connaître le fonctionnement actuel de l’interface GA.

Étapes suivantes

• Gestion des conversations : configurez les sessions et gérez l’audio, le texte et les événements.
• Détection de l’activité vocale : configurez la détection automatique des tours de parole.
• Outils et MCP : ajoutez des fonctions, des serveurs MCP et des connecteurs.
• Conception de prompts pour les modèles vocaux : utilisez le guide correspondant à votre modèle Realtime.
• Optimisation des coûts : comprenez le décompte de l’utilisation et la mise en cache dans Realtime.
• Contrôles côté serveur : conservez l’exécution des outils et le contrôle des sessions sur votre serveur.

Autres workflows audio

Le sélecteur de workflow et le vocabulaire commun à l’audio se trouvent désormais dans Audio et voix. Pour la traduction en continu, utilisez le guide Traduction en direct. Pour les sous-titres en direct, utilisez le guide Transcription en direct ; pour les enregistrements audio, utilisez le guide Transcription de fichiers.