Notes pour les développeurs sur la Realtime API

Nous avons récemment annoncé notre dernier modèle parole à parole, gpt-realtime, ainsi que la disponibilité générale de la Realtime API et plusieurs nouvelles fonctionnalités de l’API. Le passage en disponibilité générale (GA) de la Realtime API et du modèle parole à parole (s2s) s’accompagne d’améliorations importantes en matière de qualité du modèle, de fiabilité et de facilité d’intégration.

Vous trouverez les nouvelles fonctionnalités dans la documentation et la référence de l’API. Nous souhaitons revenir sur quelques fonctionnalités qui ont pu vous échapper et préciser dans quels cas les utiliser. Si vous intégrez la Realtime API à votre application, nous espérons que ces notes vous seront utiles.

Améliorations du modèle

Le nouveau modèle apporte plusieurs améliorations pour les applications vocales en production. Cet article porte principalement sur les changements apportés à l’API. Pour mieux comprendre et utiliser le modèle, nous vous recommandons de lire l’article d’annonce et le guide de rédaction des prompts pour les modèles temps réel. Quelques points méritent toutefois d’être précisés ici.

Quelques conseils pour utiliser ce modèle :

• Testez différentes formulations de prompts dans le Playground temps réel.
• Utilisez l’une des voix marin ou cedar pour obtenir la meilleure qualité vocale possible pour l’assistant.
• Réécrivez vos prompts pour le nouveau modèle. Il suit mieux les instructions, ce qui donne beaucoup plus de poids aux consignes précises.
  • Par exemple, l’ancien modèle pouvait interpréter « Dites toujours X lorsque Y se produit » comme une simple indication. Le nouveau modèle risque d’appliquer cette consigne dans des situations que vous n’aviez pas prévues.
  • Examinez attentivement les consignes précises que vous donnez. Partez du principe que le modèle les suivra.

Évolution de l’interface de l’API

Nous avons fait évoluer l’interface de la Realtime API lors du passage en disponibilité générale. Il existe désormais une interface bêta et une interface GA. Nous vous recommandons de migrer vos clients vers l’interface GA pour bénéficier des nouvelles fonctionnalités. À terme, l’interface bêta sera déclarée obsolète.

Vous trouverez la liste complète des changements nécessaires dans le guide de migration de la bêta vers la version GA.

Vous pouvez accéder au nouveau modèle gpt-realtime depuis l’interface bêta, mais certaines fonctionnalités risquent d’être indisponibles. Le tableau ci-dessous précise les différences.

Disponibilité des fonctionnalités

La version GA de la Realtime API apporte plusieurs fonctionnalités. Certaines sont également disponibles sur les modèles plus anciens.

*Le modèle bêta ne prend pas en charge les appels de fonction asynchrones. Il risque donc de mal gérer les appels d’outils MCP en attente qui n’ont encore renvoyé aucun résultat. Nous recommandons d’utiliser le modèle GA avec MCP.

Changements concernant la température

L’interface GA ne propose plus le paramètre de modèle temperature. L’interface bêta limite la température à la plage 0.6 - 1.2, avec une valeur par défaut de 0.8.

Vous vous demandez peut-être : « Pourquoi ne peut-on pas régler librement la température, par exemple pour rendre la réponse plus déterministe ? » Avec cette architecture de modèle, la température agit différemment. Dans la quasi-totalité des cas, la valeur recommandée de 0.8 donne les meilleurs résultats.

D’après nos observations, une température basse ne permet pas de rendre ces réponses audio déterministes, et une température plus élevée produit des anomalies dans le son. Pour agir sur ces aspects du comportement du modèle, nous recommandons de tester différentes formulations de prompts.

Nouvelles fonctionnalités

Outre les changements liés au passage de la bêta à la version GA, nous avons ajouté plusieurs fonctionnalités à la Realtime API.

La documentation et la référence de l’API couvrent toutes les fonctionnalités. Nous allons ici préciser comment tirer parti des nouveautés lors d’une intégration ou d’une migration.

Délais d’inactivité dans une conversation

Dans certaines applications, un long silence de l’utilisateur est inhabituel. Au téléphone, par exemple, si vous n’entendez plus votre interlocuteur, vous lui demandez s’il est toujours là. Le modèle a peut-être manqué une intervention de l’utilisateur, ou l’utilisateur se demande si le modèle a fini de parler. Nous avons ajouté une fonctionnalité qui permet au modèle de relancer automatiquement la conversation en demandant, par exemple : « Vous êtes toujours là ? »

Pour activer cette fonctionnalité, définissez idle_timeout_ms dans les paramètres server_vad de détection des tours de parole. Le délai commence à la fin de la lecture audio de la dernière réponse du modèle. Pour obtenir l’heure d’expiration, ajoutez à l’heure de l’événement response.done la durée de lecture audio, puis le délai d’inactivité. Si le détecteur d’activité vocale (VAD) ne se déclenche pas pendant ce délai, celui-ci expire.

À l’expiration du délai, le serveur envoie un événement input_audio_buffer.timeout_triggered, qui entraîne l’ajout du segment audio vide à l’historique de la conversation et déclenche une réponse du modèle. L’ajout de ce segment permet au modèle de vérifier si le détecteur a manqué une intervention de l’utilisateur pendant la période concernée.

Pour activer cette fonctionnalité côté client, utilisez la configuration suivante :

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "instructions": "You are a helpful assistant.",
    "audio": {
      "input": {
        "turn_detection": {
          "type": "server_vad",
          "idle_timeout_ms": 6000
        }
      }
    }
  }
}

Conversations longues et gestion du contexte

Nous avons ajusté la manière dont la Realtime API gère les sessions longues. Voici les points à retenir :

• Une session en temps réel peut désormais durer jusqu’à 60 minutes, contre 30 auparavant.
• Le modèle gpt-realtime dispose d’une fenêtre de contexte de 32 768 tokens. Une réponse peut utiliser jusqu’à 4 096 tokens, ce qui laisse au maximum 28 672 tokens en entrée.
• Les instructions de la session et les outils peuvent occuper au total jusqu’à 16 384 tokens.
• Par défaut, le service tronque automatiquement le contexte en supprimant des messages lorsque la session atteint 28 672 tokens. Ce comportement est configurable.
• Lorsqu’une transcription est disponible, le service GA supprime automatiquement une partie des tokens audio pour économiser des tokens.

Configuration de la troncature

Lorsque la fenêtre de contexte de la conversation atteint sa limite de tokens, la Realtime API commence automatiquement à supprimer les messages les plus anciens, en partant du début de la session. Vous pouvez désactiver la troncature avec "truncation": "disabled". L’API renvoie alors une erreur si le nombre de tokens en entrée est trop élevé pour générer une réponse. La troncature permet toutefois de poursuivre la session même lorsque la taille de l’entrée dépasse la capacité du modèle. La Realtime API ne produit ni résumé ni compactage des messages supprimés, mais vous pouvez mettre en œuvre ces mécanismes dans votre application.

La troncature présente un inconvénient : modifier les messages au début de la conversation invalide les entrées du cache utilisées pour la mise en cache des prompts. La mise en cache des prompts repose sur la détection d’un préfixe strictement identique au début de vos prompts. À chaque nouveau tour de parole, seuls les tokens inchangés sont mis en cache. Quand la troncature modifie le début de la conversation, moins de tokens peuvent être mis en cache.

Pour limiter cet effet, nous avons ajouté une option qui permet de supprimer davantage de contexte à chaque troncature. Réglez la proportion de contexte à conserver sur 0.8 pour supprimer 20 % de la fenêtre de contexte au lieu de supprimer juste assez de tokens pour repasser sous la limite d’entrée. En supprimant davantage de contexte en une seule fois, plutôt qu’une petite quantité à chaque tour, vous invalidez le cache moins souvent. Cette approche permet de limiter les coûts des sessions longues qui atteignent la limite de tokens en entrée.

{
  "type": "session.update",
  "session": {
    "truncation": {
      "type": "retention_ratio",
      "retention_ratio": 0.8
    }
  }
}

Appels de fonction asynchrones

La Responses API exige que le résultat d’un appel de fonction soit fourni immédiatement après l’appel. La Realtime API, elle, permet au client de poursuivre la session pendant que l’appel est en attente. L’utilisateur peut ainsi continuer à converser naturellement en temps réel, mais il arrive que le modèle invente le contenu d’une réponse que la fonction n’a pas encore renvoyée.

Pour atténuer ce problème, la version GA de la Responses API ajoute des réponses provisoires. Nous avons testé et ajusté leur formulation pour que le modèle réponde de manière appropriée même lorsqu’il attend le résultat d’un appel de fonction. Si vous lui demandez le résultat de l’appel, il répondra par exemple : « J’attends encore le résultat. » Cette fonctionnalité est activée automatiquement pour les nouveaux modèles. Vous n’avez rien à modifier.

Résidence des données dans l’UE

La résidence des données dans l’UE est désormais prise en charge pour les modèles gpt-realtime-2025-08-28 et gpt-4o-realtime-preview-2025-06-03. Pour en bénéficier, vous devez l’activer explicitement pour votre organisation et accéder à l’API via https://eu.api.openai.com.

Traçage

La Realtime API consigne les événements importants d’une session en temps réel dans des traces consultables dans la console développeur. Ces traces facilitent les investigations et le débogage. Avec la version GA, nous avons ajouté de nouveaux types d’événements :

• Mise à jour de la session (lorsque des événements session.updated sont envoyés au client)
• Génération de texte en sortie (pour le texte généré par le modèle)

Prompts hébergés

Vous pouvez désormais utiliser des prompts avec la Realtime API pour référencer dans le code de votre application un prompt que vous pouvez modifier séparément. Un prompt contient à la fois des instructions et des paramètres de session, notamment ceux de détection des tours de parole.

Vous pouvez créer un prompt dans le Playground temps réel, l’affiner et en créer de nouvelles versions selon vos besoins. Le client peut ensuite le référencer par son identifiant :

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {
      "id": "pmpt_123", // your stored prompt ID
      "version": "89", // optional: pin a specific version
      "variables": {
        "city": "Paris" // example variable used by your prompt
      }
    },
    // You can still set direct session fields; these override prompt fields if they overlap:
    "instructions": "Speak clearly and briefly. Confirm understanding before taking actions."
  }
}

Si un même paramètre figure dans le prompt et dans la configuration transmise à la session, comme dans l’exemple ci-dessus, la valeur définie pour la session prévaut. Le client peut donc reprendre la configuration du prompt ou l’ajuster pendant la session.

Connexions sur un canal auxiliaire

La Realtime API permet aux clients de se connecter directement au serveur de l’API via WebRTC ou SIP. Vous souhaiterez toutefois probablement gérer les appels d’outils et le reste de la logique métier sur votre serveur d’application afin que cette logique reste privée et indépendante du client.

Pour garder les appels d’outils, la logique métier et les autres détails d’implémentation à l’abri côté serveur, connectez votre serveur via un canal de contrôle auxiliaire. Ce canal est désormais disponible pour les connexions SIP et WebRTC.

Avec un canal auxiliaire, deux connexions sont actives pour la même session en temps réel : celle du client de l’utilisateur et celle de votre serveur d’application. La connexion du serveur permet de suivre la session, de mettre à jour les instructions et de répondre aux appels d’outils.

Pour en savoir plus, consultez la documentation sur les connexions via un canal auxiliaire.

Premiers pas

Nous espérons que ces notes vous ont aidé à comprendre les changements apportés par la version GA de la Realtime API et les nouveaux modèles temps réel.

Pour passer à la pratique, consultez la documentation de la Realtime API afin de créer un agent vocal, d’établir une connexion ou d’envoyer vos premiers prompts aux modèles temps réel.