Notes pour les développeurs sur Realtime API

Nous avons récemment annoncé notre dernier modèle de parole à parole, gpt-realtime, ainsi que la disponibilité générale de Realtime API et de nombreuses nouvelles fonctionnalités de l’API. Realtime API et le modèle de parole à parole (s2s) sont passés en disponibilité générale (GA), avec des améliorations majeures de la qualité du modèle, de la fiabilité et de l’ergonomie pour les développeurs.

Vous pouvez découvrir les nouvelles fonctionnalités de l’API dans la documentation et la référence de l’API. Nous souhaitons ici présenter quelques fonctionnalités qui vous ont peut-être échappé et vous indiquer quand les utiliser. Si vous intégrez Realtime API, nous espérons que ces notes vous intéresseront.

Améliorations du modèle

Le nouveau modèle apporte plusieurs améliorations pour mieux répondre aux besoins des applications vocales en production. Cet article se concentre sur les changements de l’API. Pour mieux comprendre et utiliser le modèle, nous vous recommandons l’article d’annonce et le guide de conception de prompts pour Realtime. Nous allons toutefois aborder quelques points précis.

Quelques conseils essentiels pour utiliser ce modèle :

• Testez différents prompts dans le Playground Realtime.
• Utilisez les voix marin ou cedar pour obtenir la meilleure qualité vocale pour l’assistant.
• Réécrivez vos prompts pour le nouveau modèle. Grâce aux améliorations du suivi des instructions, les consignes précises ont désormais beaucoup plus d’effet.
  • Par exemple, l’ancien modèle pouvait interpréter un prompt comme « Dites toujours X lorsque Y » comme une vague indication, tandis que le nouveau modèle peut l’appliquer dans des situations inattendues.
  • Prêtez attention aux consignes précises que vous donnez. Partez du principe qu’elles seront suivies.

Changements de structure de l’API

Nous avons modifié la structure de Realtime API lors du lancement en disponibilité générale : il existe donc une interface bêta et une interface GA. Nous recommandons de migrer les clients vers l’interface GA, qui offre de nouvelles fonctionnalités, car l’interface bêta sera à terme dépréciée.

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

Vous pouvez accéder au nouveau modèle gpt-realtime via l’interface bêta, mais certaines fonctionnalités peuvent ne pas être prises en charge. Vous trouverez plus de détails ci-dessous.

Disponibilité des fonctionnalités

La version GA de Realtime API comprend plusieurs nouvelles fonctionnalités. Certaines sont activées sur les anciens modèles, d’autres non.

*Le modèle bêta ne prenant pas en charge l’appel de fonction asynchrone, il peut mal gérer les appels d’outils MCP en attente qui n’ont pas encore renvoyé de résultat. Nous recommandons d’utiliser le modèle GA avec MCP.

Changements concernant la température

L’interface GA ne propose plus temperature comme paramètre du modèle, et 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 les utilisateurs ne peuvent-ils pas régler librement la température, par exemple pour rendre la réponse plus déterministe ? » La température se comporte différemment avec cette architecture de modèle, et le réglage recommandé de 0.8 donne presque toujours 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 des températures plus élevées produisent des anomalies audio. Nous recommandons de tester différents prompts pour contrôler ces aspects du comportement du modèle.

Nouvelles fonctionnalités

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

Toutes les fonctionnalités sont décrites dans la documentation et la référence de l’API. Nous allons ici expliquer comment aborder les nouvelles fonctionnalités lors de l’intégration et de la migration.

Délais d’inactivité de la conversation

Dans certaines applications, un long silence de l’utilisateur serait inhabituel. Imaginez un appel téléphonique : si vous n’entendiez plus votre interlocuteur, vous lui demanderiez si tout va bien. Le modèle a peut-être manqué ce que l’utilisateur a dit, ou l’utilisateur ne sait peut-être pas si le modèle a fini de parler. Nous avons ajouté une fonctionnalité qui déclenche automatiquement une intervention du modèle, par exemple : « Vous êtes toujours là ? »

Activez cette fonctionnalité en définissant idle_timeout_ms dans les paramètres server_vad de détection des tours de parole. Le délai commence à courir à la fin de la lecture audio de la dernière réponse du modèle. Il expire donc à l’instant response.done, auquel s’ajoutent la durée de lecture audio et le délai configuré. Si la détection d’activité vocale (VAD) ne se déclenche pas pendant cette période, le délai d’inactivité est atteint.

Lorsque le délai d’inactivité est atteint, le serveur envoie un événement input_audio_buffer.timeout_triggered, qui ajoute alors le segment audio vide à l’historique de la conversation et déclenche une réponse du modèle. L’ajout de ce segment audio vide permet au modèle de vérifier si la détection d’activité vocale (VAD) a échoué et si l’utilisateur a parlé pendant la période concernée.

Les clients peuvent activer cette fonctionnalité comme suit :

{
  "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 façon dont Realtime API gère les sessions longues. Voici quelques points à retenir :

• Les sessions Realtime peuvent désormais durer jusqu’à 60 minutes, contre 30 minutes auparavant.
• Le modèle gpt-realtime dispose d’une fenêtre de 32 768 tokens. Les réponses peuvent consommer au maximum 4 096 tokens. Le modèle accepte donc au maximum 28 672 tokens en entrée.
• Les instructions de session et les outils peuvent totaliser au maximum 16 384 tokens.
• Le service tronque automatiquement la conversation en supprimant des messages lorsque la session atteint 28 672 tokens, mais ce comportement est configurable.
• La version en disponibilité générale du service supprime automatiquement certains tokens audio lorsqu’une transcription est disponible, afin d’économiser des tokens.

Configuration de la troncature

Lorsque la fenêtre de contexte de la conversation atteint la limite de tokens, la Realtime API commence automatiquement à tronquer la conversation en supprimant les messages du début de la session, c’est-à-dire les plus anciens. Vous pouvez désactiver ce comportement avec le paramètre "truncation": "disabled". Une erreur est alors renvoyée lorsqu’une réponse comporte trop de tokens en entrée. La troncature reste toutefois utile, car elle permet à la session de continuer même si le volume d’entrée devient trop important pour le modèle. La Realtime API n’effectue ni résumé ni compactage des messages supprimés, mais vous pouvez mettre en œuvre ces mécanismes vous-même.

La troncature a un inconvénient : la modification des messages au début de la conversation invalide le cache des tokens du prompt. La mise en cache des prompts repose sur l’identification de contenus strictement identiques au début de vos prompts. À chaque tour suivant, seuls les tokens qui n’ont pas changé sont mis en cache. Lorsque la troncature modifie le début de la conversation, elle réduit le nombre de tokens pouvant être mis en cache.

Nous avons mis en place une fonctionnalité qui atténue cet inconvénient en supprimant plus de contenu que nécessaire à chaque troncature. Définissez le taux de conservation sur 0.8 pour supprimer 20 % de la fenêtre de contexte, plutôt que de supprimer juste assez de contenu pour maintenir le nombre de tokens en entrée sous la limite. L’idée est de supprimer davantage de contenu de la fenêtre de contexte en une seule fois, plutôt qu’un peu à chaque fois, afin d’invalider le cache moins souvent. Cette approche préserve mieux le cache et peut limiter les coûts des longues sessions qui atteignent les limites d’entrée.

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

Appel de fonction asynchrone

Alors que l’API Responses exige une réponse de fonction immédiatement après l’appel de fonction, la Realtime API permet aux clients de poursuivre une session pendant qu’un appel de fonction est en attente. Cela améliore l’expérience utilisateur en permettant aux conversations en temps réel de se poursuivre naturellement, mais le modèle invente parfois le contenu d’une réponse de fonction inexistante.

Pour atténuer ce problème, la version en disponibilité générale de l’API Responses ajoute des réponses d’attente dont nous avons évalué et ajusté le contenu lors d’expérimentations, afin que le modèle réagisse de manière appropriée même lorsqu’il attend une réponse de fonction. Si vous demandez au modèle les résultats d’un appel de fonction, il répondra par exemple : « J’attends encore les résultats. » Cette fonctionnalité est automatiquement activée pour les nouveaux modèles ; vous n’avez aucune modification à effectuer.

Résidence des données dans l’UE

La résidence des données dans l’UE est désormais prise en charge spécifiquement pour gpt-realtime-2025-08-28 et gpt-4o-realtime-preview-2025-06-03. Elle doit être explicitement activée pour l’organisation, et les requêtes doivent passer par https://eu.api.openai.com.

Traçage

La Realtime API consigne des traces dans la console développeur en enregistrant les événements clés d’une session Realtime, ce qui peut faciliter les investigations et le débogage. À l’occasion du passage en disponibilité générale, nous avons ajouté quelques 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 que le code de votre application fasse facilement référence à un prompt modifiable séparément. Les prompts comprennent à la fois les instructions et la configuration de la session, notamment les paramètres de détection des tours de parole.

Vous pouvez créer un prompt dans le Playground Realtime, l’améliorer progressivement et en gérer les versions selon vos besoins. Un client peut ensuite faire référence à ce prompt par son identifiant, comme suit :

{
  "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 paramètre du prompt est également défini dans la configuration transmise à la session, comme dans l’exemple ci-dessus, la configuration de la session est prioritaire. Un client peut donc utiliser la configuration du prompt ou la modifier au moment de la session.

Connexions hors bande

La Realtime API permet aux clients de se connecter directement au serveur de l’API via WebRTC ou SIP. Vous souhaiterez toutefois probablement conserver l’utilisation des 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.

Sécurisez l’utilisation des outils, la logique métier et les autres détails côté serveur en vous connectant via un canal de contrôle hors bande. Nous proposons désormais des options hors bande pour les connexions SIP et WebRTC.

Avec une connexion hors bande, deux connexions sont actives sur la même session Realtime : l’une depuis le client de l’utilisateur, l’autre depuis votre serveur d’application. La connexion du serveur permet de surveiller 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 hors bande.

Commencez à développer

Nous espérons que cet aperçu vous a aidé à comprendre les nouveautés de la Realtime API en disponibilité générale et des nouveaux modèles temps réel.

Maintenant que vous connaissez ces évolutions, consultez la documentation Realtime pour créer un agent vocal, établir une connexion ou commencer à concevoir des prompts pour les modèles temps réel.