Interaction en temps réel

OpenAI Realtime utilise une connexion persistante et des événements bidirectionnels pour traiter le texte, l’audio et les appels de fonctions en temps réel. Le client envoie des événements de session, de tampon audio, d’éléments de conversation et de contrôle des réponses ; le serveur renvoie continuellement l’état de session, les transcriptions, le texte, l’audio, les arguments de fonction et les erreurs.

Cette page utilise principalement WebSocket. Lors de la connexion, remplacez MODEL_ID par l’ID d’un modèle visible pour le compte actuel et compatible avec Realtime.

Les usages courants comprennent les conversations vocales en temps réel, la transcription de réunions et les assistants vocaux, la traduction en temps réel, la transcription vocale, les interactions de code en temps réel et les intégrations serveur en temps réel. Une connexion peut transporter du texte et de l’audio, et gérer la VAD, les appels de fonctions et les mises à jour d’état par événements.

Authentification et connexion

Authentification WebSocket

Les applications serveur établissent une connexion WSS avec une clé API Bearer et transmettent le Header Realtime Beta dans la requête de handshake.

Utilisez les clés API de longue durée uniquement sur des serveurs de confiance ; ne les intégrez pas dans un navigateur, un paquet mobile ou un dépôt public. Toutes les connexions doivent utiliser HTTPS/WSS.

Jetons temporaires

Pour connecter un client, un serveur de confiance peut d’abord créer un jeton temporaire valable une minute et destiné à une seule connexion.

POST https://api.agtcloud.cn/v1/realtime/sessions
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "model": "MODEL_ID",
  "voice": "verse"
}

Déroulement de la connexion

Dans le flux WebSocket principal, le serveur établit directement la connexion avec une clé API ; une fois le handshake réussi, il envoie les événements client et reçoit les événements serveur sur cette même connexion.

Dans le flux WebRTC, le client demande d’abord un jeton temporaire à son propre serveur applicatif, qui appelle l’interface de session pour le créer. Le client génère ensuite une SDP Offer, l’envoie à l’endpoint Realtime et reçoit une SDP Answer, puis échange des événements JSON via le canal de données oai-events.

Exemples de connexion WebSocket

Les exemples suivants présentent Node.js, Python, l’envoi et la réception d’événements. Après connexion, le client envoie des événements JSON et le serveur renvoie continuellement les résultats sous la même forme.

import WebSocket from 'ws';

const ws = new WebSocket('wss://api.agtcloud.cn/v1/realtime?model=MODEL_ID', {
  headers: {
    Authorization: 'Bearer your-api-key',
    'OpenAI-Beta': 'realtime=v1',
  },
});

ws.on('open', () => {
  console.log('Connexion au serveur établie.');
});

ws.on('message', (message) => {
  console.log(JSON.parse(message.toString()));
});

Intégration WebRTC

WebSocket est actuellement recommandé. Avant d’utiliser WebRTC, vérifiez que le modèle cible le prend en charge ; les exemples suivants illustrent la structure de connexion avec jeton temporaire, SDP, pistes audio et canal de données.

async function init() {
  const tokenResponse = await fetch('/session');
  const data = await tokenResponse.json();
  const ephemeralKey = data.client_secret.value;

  const pc = new RTCPeerConnection();
  const audioElement = document.createElement('audio');
  audioElement.autoplay = true;
  pc.ontrack = (event) => {
    audioElement.srcObject = event.streams[0];
  };

  const mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true });
  pc.addTrack(mediaStream.getTracks()[0]);

  const dataChannel = pc.createDataChannel('oai-events');
  dataChannel.addEventListener('message', (event) => {
    console.log(JSON.parse(event.data));
  });

  const offer = await pc.createOffer();
  await pc.setLocalDescription(offer);

  const response = await fetch(
    'https://api.agtcloud.cn/v1/realtime?model=MODEL_ID',
    {
      method: 'POST',
      body: offer.sdp,
      headers: {
        Authorization: `Bearer ${ephemeralKey}`,
        'Content-Type': 'application/sdp',
      },
    },
  );

  await pc.setRemoteDescription({
    type: 'answer',
    sdp: await response.text(),
  });
}

init();

import express from 'express';

const app = express();

app.get('/session', async (_request, response) => {
  const result = await fetch('https://api.agtcloud.cn/v1/realtime/sessions', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer your-api-key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'MODEL_ID',
      voice: 'verse',
    }),
  });

  response.send(await result.json());
});

app.listen(3000);

const dataChannel = pc.createDataChannel('oai-events');

dataChannel.addEventListener('message', (event) => {
  const realtimeEvent = JSON.parse(event.data);
  console.log(realtimeEvent);
});

dataChannel.send(JSON.stringify({
  type: 'response.create',
  response: {
    modalities: ['text'],
    instructions: 'Écrivez un haïku sur le code',
  },
}));

const ws = new WebSocket(
  'wss://api.agtcloud.cn/v1/realtime?model=MODEL_ID',
  [
    'realtime',
    'openai-insecure-api-key.your-api-key',
    'openai-organization.ORGANIZATION_ID',
    'openai-project.PROJECT_ID',
    'openai-beta.realtime-v1',
  ],
);

ws.addEventListener('open', () => {
  console.log('Connexion au serveur établie.');
});

ws.addEventListener('message', (event) => {
  console.log(JSON.parse(event.data));
});

Session, audio et conversation

Realtime prend en charge les conversations textuelles, vocales et combinant texte et audio. La configuration de session peut inclure les formats audio d’entrée et de sortie, la voix, la température, la longueur maximale de sortie, les outils et les paramètres VAD.

• Formats audio d’entrée et de sortie : pcm16, g711_ulaw, g711_alaw.
• Exemples de voix : alloy, echo, shimmer.
• La configuration VAD comprend le seuil, le préfixe audio avant la parole et la durée de silence.
• La conversation progresse via la session, les éléments de conversation, les parties de contenu et les événements de réponse.

Consultez les champs précis dans le navigateur d’événements ci-dessous ; les paramètres et domaines de valeurs partagés sont regroupés dans « Types communs ».

Référence des événements

Sélectionnez un événement pour consulter ses champs et son exemple JSON. Vous pouvez changer de direction, filtrer par catégorie ou rechercher un nom d’événement.

{
  "event_id": "event_123",
  "type": "session.update",
  "modalities": [
    "text",
    "audio"
  ],
  "instructions": "Répondez de manière concise et précise.",
  "voice": "alloy, echo, shimmer",
  "input_audio_format": "pcm16, g711_ulaw, g711_alaw",
  "output_audio_format": "pcm16, g711_ulaw, g711_alaw",
  "input_audio_transcription": {
    "model": "whisper-1"
  },
  "turn_detection": {
    "type": "server_vad",
    "threshold": 0.8,
    "prefix_padding_ms": 500,
    "silence_duration_ms": 1000
  },
  "tools": [],
  "tool_choice": "auto",
  "temperature": 0.8,
  "max_output_tokens": "inf"
}

Types communs

Les sections repliables suivantes regroupent les paramètres des limites de débit, appels de fonctions, audio, VAD, outils, modèles, événements, sessions, éléments de conversation, contenu, réponses, transcription, flux audio et WebRTC.

Gestion des erreurs et reprise

Les erreurs Realtime relèvent généralement de quatre catégories : connexion, authentification, audio ou session.

La reprise peut comprendre la reconnexion automatique, la restauration de session, des tentatives limitées et un mode dégradé. En cas d’erreur, lisez d’abord l’événement error, conservez event_id, error.type, error.code, error.message et les informations d’événement associées, puis décidez si un renvoi est nécessaire.