AI Endpoints - Transcription audio avec l’API Gladia
Découvrez comment transcrire de l’audio en temps réel avec Solaria-3, l’API Gladia et les SDK officiels sur OVHcloud AI Endpoints
AI Endpoints est couvert par les Conditions particulières OVHcloud Public Cloud (voir l’Annexe 10 – « Conditions spécifiques – AI Endpoints »).
Objectif
Sur AI Endpoints, utilisez solaria-3 pour transcrire de l’audio en temps réel avec l’API Gladia Live V2. L’API native fournit des transcriptions partielles, des segments de parole définitifs et des étiquettes de locuteurs. Ce guide explique comment créer une session, transmettre l’audio, terminer la session et récupérer les résultats à l’aide de HTTP, de WebSockets et des SDK officiels Gladia.
La disponibilité de solaria-3 en temps réel décrite ici concerne AI Endpoints ; les modèles disponibles peuvent différer sur le service SaaS de Gladia.
Pour transcrire des fichiers avec l’API compatible OpenAI, consultez le guide « AI Endpoints - Transcription via l’API compatible OpenAI ».
Prérequis
- Une clé API AI Endpoints, créée en suivant le guide « AI Endpoints - Premiers pas ».
- Un court enregistrement audio.
- Python ou Node.js pour les exemples facultatifs avec les SDK.
- Pour le protocole brut : cURL,
jqet un client WebSocket. - Facultatif : FFmpeg pour convertir un fichier existant pour les exemples.
Endpoint et authentification
Utilisez votre clé API AI Endpoints, et non une clé API du service SaaS Gladia.
Pour les requêtes natives /gladia/*, authentifiez-vous avec x-gladia-key: <token> (pris en charge pour assurer la compatibilité avec les SDK officiels Gladia) ou avec l’en-tête standard AI Endpoints Authorization: Bearer <token>. Pour les requêtes anonymes, omettez ces deux en-têtes. L’URL de base de l’API native est $AI_ENDPOINTS_BASE_URL/gladia, sans /v1.
Avec un SDK, définissez api_key (Python) ou apiKey (JavaScript) sur votre clé API AI Endpoints. Le SDK l’envoie dans l’en-tête x-gladia-key ; aucune valeur fictive ni en-tête d’autorisation personnalisé n’est nécessaire.
Exemples avec les SDK officiels
Ces exemples créent une session, transmettent un court enregistrement local au rythme du temps réel, arrêtent l’enregistrement, attendent la fin du traitement et interrogent le résultat final avec une durée maximale d’attente. Les délais d’expiration sont définis côté client ; ils ne correspondent pas aux durées de session autorisées par le service. Ces exemples utilisent un enregistrement source en anglais : adaptez language_config à la langue de votre fichier.
Préparer l’audio pour ces exemples
Pour simplifier, ces exemples utilisent de l’audio PCM mono à 16 kHz sur 16 bits. Ce n’est pas le seul format pris en charge : l’encodage, la fréquence d’échantillonnage, la profondeur en bits et le nombre de canaux de la session doivent correspondre à l’audio envoyé. Python lit un conteneur WAV ; Node.js lit des données PCM sans en-tête.
Si nécessaire, convertissez un enregistrement existant avec FFmpeg. Choisissez la sortie correspondant à votre exemple :
Installez le package officiel gladiaio-sdk dans votre environnement Python :
Utilisez un fichier WAV PCM mono sur 16 bits nommé audio.wav :
Fermez toujours les sessions ayant échoué ou abandonnées. Avant de relancer automatiquement une création de session, vérifiez si la requête précédente a déjà créé une session : chaque session supplémentaire occupe un emplacement dans le quota de sessions simultanées.
Protocole natif de transcription en temps réel
1. Créer une session
Cet exemple utilise un enregistrement en anglais au format PCM mono à 16 kHz, signé sur 16 bits en petit-boutiste (little-endian). Adaptez language_config à la langue de votre audio.
Précisez explicitement model: "solaria-3" dans chaque requête de création de session, sans vous fier au modèle par défaut. Précisez le format de votre audio : l’encodage, la fréquence d’échantillonnage, la profondeur en bits et le nombre de canaux doivent correspondre aux échantillons envoyés.
Une réponse réussie renvoie le code 201 et contient les champs id et url. L’URL WebSocket renvoyée est signée : conservez-la telle quelle et traitez-la comme un identifiant d’accès confidentiel. Ne consignez pas dans les journaux la réponse, l’URL ou les erreurs du SDK susceptibles de la contenir. N’ajoutez pas /gladia ou /v1 à cette URL.
2. Envoyer l’audio et recevoir les événements
Connectez un client WebSocket à WEBSOCKET_URL ou utilisez l’un des exemples de SDK ci-dessus, qui crée sa propre session. Pour la configuration ci-dessus :
- Envoyez l’audio sous forme de messages WebSocket binaires, avec l’encodage indiqué lors de la création de la session. Ces exemples envoient des échantillons PCM bruts, et non un conteneur WAV ou des données MP3 compressées ; le module Python
wavelit le conteneur WAV et envoie uniquement les échantillons PCM. - Transmettez l’audio à un rythme proche du temps réel. Par exemple, 3 200 octets représentent 100 ms d’audio mono à 16 kHz sur 16 bits.
- Lisez les événements en parallèle de l’envoi de l’audio. Pour
type="transcript", examinezdata.is_finaletdata.utterance.text. Les transcriptions partielles peuvent évoluer : remplacez les transcriptions partielles précédentes ayant le mêmedata.id, plutôt que d’ajouter des doublons. - Une fois tout l’audio envoyé, transmettez le message texte
{"type":"stop_recording"}. Continuez à lire les événements jusqu’à la fin du post-traitement et à la fermeture de la connexion WebSocket. Un segment de parole définitif ne marque pas la fin de la session. Ne fermez pas la connexion immédiatement après l’arrêt de l’enregistrement.
Le guide de démarrage Gladia Live décrit le protocole sous-jacent. Les limitations du service présentées dans ce guide prévalent sur les exemples du service SaaS Gladia.
3. Récupérer le résultat
Après avoir terminé la session ci-dessus, récupérez son résultat avec la même clé API AI Endpoints :
Le champ status du résultat vaut queued, processing, done ou error. S’il vaut queued ou processing, interrogez à nouveau l’API en espaçant les requêtes et en fixant une durée maximale d’attente. Le statut done indique que le traitement est terminé ; arrêtez les requêtes et gérez l’échec si le statut vaut error. Le booléen failed présent dans le détail de la session n’est pas un statut du résultat. La transcription complète est disponible dans result.transcription.full_transcript.
Les résultats sont isolés par projet authentifié ou par adresse IP anonyme. Réutilisez une clé API du même projet ou la même adresse IP pour un accès anonyme. Une ressource inaccessible ou qui ne vous appartient pas renvoie 404.
Intelligence audio
Précisez explicitement "model": "solaria-3" lors de la création d’une session : les SDK peuvent sélectionner un autre modèle par défaut, tel que solaria-1. Les fonctionnalités ci-dessous sont disponibles via l’API native en temps réel. audio_to_llm et la génération de résumés restent indisponibles.
Configurer les fonctionnalités et lire les résultats
Regroupez les fonctionnalités activées dans un seul objet realtime_processing, en respectant les chemins des champs ci-dessous. Les champs natifs diarization et diarization_config restent à la racine du corps JSON, comme indiqué dans Diarisation et latence. Avec le SDK Python 2.2 ou ultérieur, utilisez un dictionnaire pour les champs Enterprise absents de l’initialiseur typé.
Par exemple, ajoutez ces paramètres de traduction au corps de création de la session pour traduire l’audio source en français :
Activez messages_config.receive_realtime_processing_events: true pour recevoir les événements d’intelligence audio et conservez receive_final_transcripts: true. Les événements associés aux fonctionnalités peuvent arriver après la transcription source : continuez à lire jusqu’à la fin de la session. Appliquez la configuration lors de la création d’une nouvelle session.
Pour plus de détails sur les concepts et les paramètres, consultez Gladia Audio Intelligence. Certains exemples de cette documentation concernent les enregistrements ou le service SaaS Gladia : respectez le placement des champs pour le temps réel et les limitations présentées dans ce guide. Affichez les transcriptions et les entités comme du texte non fiable, et non comme du HTML, et évitez de journaliser des données personnelles lorsque le masquage PII est activé.
Diarisation et latence
La diarisation attribue des étiquettes de locuteurs à la transcription. Pour les requêtes natives de transcription en temps réel, ajoutez "diarization": true à la racine du corps JSON et, si nécessaire, "diarization_config": {"min_speakers": 2, "max_speakers": 4}. Utilisez un audio mono ; les nombres de locuteurs configurés sont des indications, pas des garanties.
Avec gladiaio-sdk>=2.2, transmettez un dictionnaire Python à live.start_session() pour envoyer les champs de diarisation Enterprise absents de LiveV2InitRequest. En JavaScript, ajoutez les mêmes champs à l’objet transmis à live.startSession().
Dans l’exemple du SDK Python ci-dessus, remplacez l’initialisation de la session et la fonction on_message par le code suivant. Conservez le reste de l’exemple sans modification :
L’exemple du SDK ci-dessus gère le rythme d’envoi de l’audio et attend les résultats finaux après stop_recording(). Ne transmettez pas diarization comme mot-clé au constructeur typé.
La diarisation distingue les voix, mais n’identifie pas les personnes, et augmente la latence de traitement, notamment pour les résultats finaux. Les étiquettes de locuteurs au niveau des mots sont plus précises qu’une étiquette unique pour un segment de parole contenant plusieurs locuteurs.
Quotas et erreurs
La limite native correspond à la durée réelle écoulée depuis la création de la session avec POST /gladia/v2/live, et non depuis l’ouverture de la connexion WebSocket ni à la quantité d’audio transmise. Par exemple, si la connexion WebSocket d’une session anonyme est ouverte 20 secondes après sa création, il ne reste que 40 secondes pour transmettre l’audio. À l’expiration, le service arrête proprement l’enregistrement avec stop_recording, ce qui permet de produire les transcriptions finales. Le client doit cesser d’envoyer de l’audio et continuer à lire les événements jusqu’à la fin du traitement et à la fermeture de la connexion.
maximum_duration_without_endpointing contrôle le moment où un segment de parole est finalisé ; il ne modifie pas la limite de durée de la session. Les utilisateurs partageant une même adresse IP publique derrière un NAT partagent également une identité anonyme. Plusieurs clés API d’un même projet ne créent pas de quotas distincts. La fermeture d’une session libère un emplacement dans le quota de sessions simultanées ; les requêtes GET de récupération des résultats ne créent pas de session.
La consommation native multicanal est mesurée en durée audio multipliée par le nombre de canaux.
Limitations du service
Seules les routes de transcription en temps réel répertoriées ici sont disponibles, et non l’ensemble de l’API Gladia.
Dépannage
Commencez par de courts échantillons audio.
Aller plus loin
- AI Endpoints - Transcription via l’API compatible OpenAI
- AI Endpoints - Premiers pas
- Guide de démarrage Gladia Live — référence du protocole, sous réserve des limitations ci-dessus.
Votre avis nous intéresse !
N’hésitez pas à nous faire part de vos questions, retours et suggestions dans le canal #ai-endpoints du serveur Discord OVHcloud, où vous pouvez échanger avec la communauté et les équipes OVHcloud.
Échangez avec notre communauté d'utilisateurs.