Transcription en temps réel

La transcription en temps réel reçoit un flux audio continu sur une connexion WebSocket persistante et renvoie du texte incrémentiel ainsi qu’une transcription finale pour chaque élément audio. Elle convient aux sous-titres en direct, à la prise de notes de réunion, aux transcriptions d’appels et à la saisie vocale. Pour téléverser un enregistrement complet en une fois, utilisez l’interface de transcription audio.

gpt-live-transcribe convient à la transcription incrémentielle à faible latence ; gpt-transcribe convient à une transcription très précise après validation d’un segment vocal complet et peut renvoyer la langue détectée dans l’événement final. Le modèle de connexion doit correspondre à celui de la session.

Authentification et connexion

Les applications serveur doivent utiliser une clé API Bearer pendant le handshake WebSocket :

L’API WebSocket d’un navigateur ordinaire ne permet pas de personnaliser le Header Authorization. N’intégrez donc pas de clé API de longue durée dans le HTML, le JavaScript ou un paquet client. Pour un produit de navigateur, un backend de confiance doit établir la connexion ou fournir un mécanisme contrôlé d’identifiants de courte durée.

Exigences audio d’entrée

Cette documentation utilise de l’audio PCM16 little-endian, 24 kHz, mono, sans en-tête WAV ni autre conteneur. Le champ audio de input_audio_buffer.append est une chaîne Base64 des octets PCM bruts.

Pour l’envoi en temps réel, privilégiez des fragments audio petits et réguliers ; un événement ne doit pas dépasser 15 MiB. Un format, un échantillonnage ou un traitement de conteneur incorrect entraîne un échec de transcription.

Configuration de session

session.type dans session.update est toujours transcription. La configuration de transcription se trouve dans session.audio.input.transcription :

noise_reduction.type=near_field convient à un casque-micro et far_field aux salles de réunion ou microphones d’ordinateur portable ; null désactive la réduction du bruit.

Validation manuelle et VAD côté serveur

• turn_detection: null : le client appelle input_audio_buffer.commit après l’envoi audio ; ce mode convient à une segmentation explicitement contrôlée par l’application.
• VAD côté serveur : configurez le seuil, le préfixe audio et la durée de silence ; le serveur détecte automatiquement le début et la fin de la parole.

En mode manuel, ne validez pas un tampon vide. Avec la VAD, vous pouvez mettre à jour l’interface d’enregistrement selon speech_started et speech_stopped, mais la transcription finale reste celle de l’événement completed.

Exemples de connexion

Les exemples suivants supposent que audio.pcm a été converti en audio brut PCM16, 24 kHz, mono. Une application temps réel doit envoyer continuellement de petits blocs audio plutôt que lire l’enregistrement complet en une fois.

import fs from 'node:fs';
import WebSocket from 'ws';

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

ws.on('open', async () => {
  ws.send(JSON.stringify({
  "type": "session.update",
  "session": {
    "type": "transcription",
    "audio": {
      "input": {
        "format": { "type": "audio/pcm", "rate": 24000 },
        "noise_reduction": { "type": "near_field" },
        "transcription": {
          "model": "MODEL_ID",
          "prompt": "Appel de service client en chinois",
          "keywords": ["AGTCloud", "Passerelle API"],
          "languages": ["zh-cn", "en"]
        },
        "turn_detection": null
      }
    }
  }
}));

  const audio = fs.createReadStream('audio.pcm', { highWaterMark: 4800 });
  for await (const chunk of audio) {
    ws.send(JSON.stringify({
      type: 'input_audio_buffer.append',
      audio: chunk.toString('base64'),
    }));
    await new Promise((resolve) => setTimeout(resolve, 100));
  }
  ws.send(JSON.stringify({ type: 'input_audio_buffer.commit' }));
});

ws.on('message', (message) => {
  const event = JSON.parse(message.toString());
  if (event.type.endsWith('.delta')) process.stdout.write(event.delta);
  if (event.type.endsWith('.completed')) console.log('\n', event.transcript);
});

Référence des événements

Le client contrôle l’entrée avec les événements de session et de tampon audio ; le serveur associe texte incrémentiel, texte final et erreurs avec l’Item ID. Les éléments audio peuvent se terminer dans un ordre différent ; agrégez donc le texte selon item_id.

{
  "event_id": "evt_session_001",
  "type": "session.update",
  "session": {
    "type": "transcription",
    "audio": {
      "input": {
        "format": {
          "type": "audio/pcm",
          "rate": 24000
        },
        "noise_reduction": {
          "type": "near_field"
        },
        "transcription": {
          "model": "MODEL_ID",
          "prompt": "Appel de service client en chinois",
          "keywords": [
            "AGTCloud",
            "Passerelle API"
          ],
          "languages": [
            "zh-cn",
            "en"
          ],
          "delay": "low"
        },
        "turn_detection": null
      }
    }
  }
}

Gestion des erreurs et reprise

Le texte incrémentiel peut être révisé par les résultats suivants ; ne l’enregistrez pas de façon immuable à la réception de delta. Seul transcript dans completed doit être considéré comme le texte final de l’élément audio actuel.