For AI agents: the complete documentation index is available at https://docs.ovhcloud.com/fr/llms.txt, the full documentation bundle is available at https://docs.ovhcloud.com/fr/llms-full.txt, and this page is available as Markdown at https://docs.ovhcloud.com/fr/guides/public-cloud/ai-machine-learning/ai-endpoints-gladia-speech-to-text.md.
Aller au contenu

AI Endpoints - Transcription audio avec l’API Gladia

Voir en Markdown

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

Info

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, jq et 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.

export AI_ENDPOINTS_BASE_URL="https://oai.endpoints.kepler.ai.cloud.ovh.net"
export OVH_AI_ENDPOINTS_ACCESS_TOKEN="<your-ai-endpoints-access-token>"

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 :

# Python : PCM dans un conteneur WAV
ffmpeg -i input.m4a -ar 16000 -ac 1 -c:a pcm_s16le audio.wav
# Node.js : PCM sans en-tête
ffmpeg -i input.m4a -ar 16000 -ac 1 -c:a pcm_s16le -f s16le audio.s16le
Python
JavaScript (Node.js)

Installez le package officiel gladiaio-sdk dans votre environnement Python :

pip install 'gladiaio-sdk>=2.2'

Utilisez un fichier WAV PCM mono sur 16 bits nommé audio.wav :

import os
import time
import wave
from gladiaio_sdk import (
    GladiaClient, LiveV2InitRequest,
    LiveV2LanguageConfig, LiveV2MessagesConfig,
)

client = GladiaClient(
    api_key=os.environ["OVH_AI_ENDPOINTS_ACCESS_TOKEN"],
    api_url=os.environ["AI_ENDPOINTS_BASE_URL"].rstrip("/") + "/gladia",
    region="eu-west",
    http_timeout=30,
    ws_timeout=30,
)
live = client.live_v2()

with wave.open("audio.wav", "rb") as audio:
    if (audio.getframerate(), audio.getsampwidth(), audio.getnchannels()) != (16000, 2, 1):
        raise ValueError("Expected 16 kHz, 16-bit mono PCM WAV")
    session = live.start_session(LiveV2InitRequest(
        model="solaria-3",
        encoding="wav/pcm", sample_rate=16000,
        bit_depth=16, channels=1,
        language_config=LiveV2LanguageConfig(languages=["en"]),
        messages_config=LiveV2MessagesConfig(receive_final_transcripts=True),
    ))

    def on_message(message):
        data = getattr(message, "data", None)
        if getattr(message, "type", None) == "transcript" and getattr(data, "is_final", False):
            print(data.utterance.text)

    session.on("message", on_message)
    try:
        if not session.wait_until_ready(timeout=30):
            raise RuntimeError("Live session did not become ready")
        while chunk := audio.readframes(1600):
            if session.status in ("ending", "ended"):
                raise RuntimeError("Live session ended before all audio was sent")
            session.send_audio(chunk)
            time.sleep(len(chunk) / (16000 * 2))
        session.stop_recording()
        if not session.join(timeout=180):
            raise TimeoutError("Live session did not finish")

        deadline = time.monotonic() + 180
        while time.monotonic() < deadline:
            result = live.get(session.session_id)
            if result.status == "done":
                print(result.result.transcription.full_transcript)
                break
            if result.status == "error":
                raise RuntimeError("Live transcription failed")
            time.sleep(2)
        else:
            raise TimeoutError("Result is not ready")
    finally:
        if session.status != "ended":
            session.end_session()

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.

SESSION=$(curl --fail-with-body --silent --show-error --max-time 30 \
  "$AI_ENDPOINTS_BASE_URL/gladia/v2/live?region=eu-west" \
  -H "x-gladia-key: $OVH_AI_ENDPOINTS_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"model":"solaria-3","encoding":"wav/pcm","sample_rate":16000,"bit_depth":16,"channels":1,"language_config":{"languages":["en"]},"messages_config":{"receive_partial_transcripts":true,"receive_final_transcripts":true}}')
SESSION_ID=$(printf '%s' "$SESSION" | jq -er '.id')
WEBSOCKET_URL=$(printf '%s' "$SESSION" | jq -er '.url')

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 :

  1. 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 wave lit le conteneur WAV et envoie uniquement les échantillons PCM.
  2. 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.
  3. Lisez les événements en parallèle de l’envoi de l’audio. Pour type="transcript", examinez data.is_final et data.utterance.text. Les transcriptions partielles peuvent évoluer : remplacez les transcriptions partielles précédentes ayant le même data.id, plutôt que d’ajouter des doublons.
  4. 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 :

curl --fail-with-body --max-time 30 \
  "$AI_ENDPOINTS_BASE_URL/gladia/v2/live/$SESSION_ID" \
  -H "x-gladia-key: $OVH_AI_ENDPOINTS_ACCESS_TOKEN"
unset SESSION WEBSOCKET_URL

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é.

FonctionnalitéChamps de création de sessionRésultats à lire
Vocabulaire personnaliséDans realtime_processing : "custom_vocabulary": true et "custom_vocabulary_config": {"vocabulary": ["OVHcloud"], "default_intensity": 0.4}Termes privilégiés dans les événements transcript définitifs. Le vocabulaire utilise la similarité phonétique ; comparez avec une transcription sans configuration, à partir d’un audio contenant les termes.
Orthographe personnaliséeDans realtime_processing : "custom_spelling": true et "custom_spelling_config": {"spelling_dictionary": {"OVHcloud": ["OVH cloud"]}}Remplacements littéraux dans les transcriptions définitives. Les clés du dictionnaire sont les graphies souhaitées ; les valeurs sont les variantes à remplacer.
Ponctuation et casseÀ la racine : "punctuation": trueTexte définitif dans data.utterance.text ; comparez avec text_raw lorsqu’il est présent. Un même paramètre contrôle la ponctuation et la casse.
Nombres en chiffresÀ la racine : "numerals": trueNombres normalisés dans data.utterance.text. Utilisez des paroles contenant des quantités, des dates ou des montants.
Entités nomméesDans realtime_processing : "named_entity_recognition": trueÉvénements named_entity_recognition : data.results[] contient entity_type, text, un score et des positions. Les segments définitifs peuvent également contenir utterance.entities[] et des balises d’entités dans le texte.
Masquage des données personnellesÀ la racine : "pii": trueTexte définitif masqué dans data.utterance.text, événements pii et métadonnées des entités. Le masquage supprime les transcriptions partielles, même si elles sont demandées. Ce champ Enterprise en temps réel est distinct de pii_redaction pour les enregistrements.
Détection de fin de tourÀ la racine : "end_of_turn": trueÉvénements end_of_turn : data.probability, reason, end et speech_duration. L’événement peut précéder la transcription définitive. Le paramètre endpointing, fondé sur le silence, et les événements speech_end n’indiquent pas une fin de tour sémantique.
Sentiments et émotionsDans realtime_processing : "sentiment_analysis": trueÉvénements sentiment_analysis : data.results[] contient sentiment, emotion, text et des horodatages.
DiarisationÀ la racine : "diarization": true, éventuellement "diarization_config": {"max_speakers": 3}data.utterance.speaker et data.utterance.words[].speaker dans les transcriptions définitives. Utilisez un audio mono ; les nombres de locuteurs configurés sont des indications, pas des garanties.
TraductionDans realtime_processing : "translation": true et "translation_config": {"target_languages": ["fr"]}Événements translation : data.target_language et data.translated_utterance.text. Associez la traduction au segment source à l’aide de data.utterance_id.

Par exemple, ajoutez ces paramètres de traduction au corps de création de la session pour traduire l’audio source en français :

{
  "model": "solaria-3",
  "messages_config": {
    "receive_realtime_processing_events": true,
    "receive_final_transcripts": true
  },
  "realtime_processing": {
    "translation": true,
    "translation_config": {"target_languages": ["fr"]}
  }
}

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 :

session = live.start_session({
  "model": "solaria-3",
  "encoding": "wav/pcm", "sample_rate": 16000,
  "bit_depth": 16, "channels": 1,
  "language_config": {"languages": ["en"]},
  "messages_config": {"receive_final_transcripts": True},
  "diarization": True,
  "diarization_config": {"max_speakers": 3},
})

def on_message(message):
  if message.type == "transcript" and message.data.is_final:
    utterance = message.data.utterance
    print(f"Speaker {utterance.speaker}: {utterance.text}")

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é.

Warning

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

LimiteAnonymeAuthentifié avec une clé API
Débit des requêtes HTTP2 requêtes par minute, par IP et par modèle400 requêtes par minute, par projet Public Cloud et par modèle
Sessions de transcription en temps réel simultanées1 session par IP25 sessions par projet Public Cloud
Durée maximale d’une session native de transcription en temps réel60 secondes8 heures

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

FonctionnalitéDisponibilité sur cet endpoint
Transcription native en temps réelPOST /gladia/v2/live, l’URL WebSocket renvoyée et GET /gladia/v2/live/{id}.
Envoi de fichiers et transcription native d’enregistrementsDésactivés, notamment /gladia/v2/upload, /gladia/v2/pre-recorded et /gladia/v2/transcription. N’utilisez pas les méthodes de transcription d’enregistrements du SDK.
RégionEurope uniquement. Omettez region ou utilisez ?region=eu-west lors de la création de la session. us-west renvoie 400.
Callbacks et webhooksDésactivés ; leur configuration renvoie 501. Recevez les événements WebSocket et récupérez les résultats à la place.
URL audio distantesBloquées. Transmettez des échantillons audio en flux plutôt qu’une URL audio_url externe.
Suppression d’une sessionDELETE /gladia/v2/live/{id} renvoie 202 une fois la session tracée. Sinon, l’API renvoie 409 ; patientez avant de réessayer. Utilisez une clé API du même projet ou la même adresse IP pour un accès anonyme.

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.

CodeAction
400Vérifiez les paramètres, la région et les métadonnées, et assurez-vous que l’audio envoyé est valide et peut être décodé. Ne définissez pas de clés custom_metadata réservées, telles que project_id ou request_id.
403Supprimez une option native désactivée, telle que la génération de résumés ou audio_to_llm.
404Vérifiez la route, l’identifiant de la ressource et vos droits d’accès à cette ressource.
405La méthode n’est pas prise en charge.
409La session ne peut pas encore être supprimée. Patientez avant de réessayer.
429Espacez vos tentatives : la limite de débit des requêtes ou de sessions simultanées a été dépassée. Fermez les sessions abandonnées avant de réessayer d’en créer une.
501Supprimez les champs non pris en charge, les callbacks ou les URL externes interdites.
502Une requête vers Gladia a échoué ou dépassé le délai imparti. Vérifiez l’état de la session avant de réessayer.

Aller plus loin

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.

Cette page vous a-t-elle aidé ?