Intégration de l’API Speech to Text : Guide développeur

Une API Speech to Text permet aux développeurs d’intégrer la reconnaissance et la transcription vocale directement dans leurs applications. Avant de connecter l’API STT, il est toutefois nécessaire de prendre quelques décisions d’architecture.

Quel mode de transcription allez-vous utiliser ? Comment allez-vous gérer les fichiers audio longs ? Comment garantir l’orthographe correcte des noms de produits ou des noms propres ? Un peu d’anticipation et de préparation permet de créer une solution évolutive de API Speech to Text dans vos applications.

Ce guide couvre tout ce dont vous avez besoin pour une intégration de l’API Speech to Text ElevenLabs, avec des exemples de code clairs à intégrer directement en production. Pour référence, gardez à portée de main le guide de démarrage rapide Speech to Text et le Guide de l’API dans une autre fenêtre.

Résumé

• Il existe deux modes Speech to Text chez ElevenLabs : batch (pour l’audio préenregistré) et realtime (pour les flux audio en direct via WebSocket).
• Scribe v2 gère la transcription batch dans plus de 90 langues, avec diarisation des locuteurs, keyterm prompting, détection d’entités, timecodes au mot et prise en charge multicanal.
• Scribe v2 Realtime gère le streaming en direct avec une latence d’environ 150 ms, en fournissant des transcriptions partielles à mesure que vous parlez et des transcriptions validées à la fin de chaque segment.
• Pour les fichiers de plus de 8 minutes, Scribe v2 segmente et transcrit automatiquement en parallèle. Pour les traitements longs, privilégiez les webhooks plutôt que d’attendre une réponse synchrone.
• Le keyterm prompting oriente le modèle vers certains termes grâce au contexte — plus fiable que de simples listes de mots-clés pour les noms de produits, le jargon technique ou les noms propres inhabituels.

Intégration API Speech to Text : Batch vs. realtime

Chaque intégration de l’API STT ElevenLabs commence par un choix d’architecture : batch ou realtime. Les deux modes offrent un modèle STT performant à votre environnement de développement, mais ce choix impacte les fonctionnalités accessibles et la latence de bout en bout.

Voici comment comparer les deux modes :

• Batch (Scribe v2) : Prend un fichier audio ou vidéo complet, le transcrit et renvoie la transcription complète en une seule réponse. Il offre l’ensemble des fonctionnalités : jusqu’à 1 000 keyterms, jusqu’à 32 locuteurs pour la diarisation, détection d’entités, mode multicanal et webhooks pour la livraison asynchrone. Les fichiers jusqu’à 3 Go et 10 heures sont pris en charge en mode standard.
• Realtime (Scribe v2 Realtime) : Accepte un flux audio en direct via WebSocket et renvoie des transcriptions partielles et validées à mesure que l’audio arrive, avec une latence d’environ 150 ms. Jusqu’à 50 keyterms et timecodes au mot sont pris en charge. Ce mode est idéal pour les assistants vocaux, le sous-titrage en direct ou toute application nécessitant une réponse immédiate à la parole de l’utilisateur.

Voyons plus en détail les différences.

En résumé : utilisez le mode batch lorsque l’audio est complet avant la transcription, et le mode realtime pour transcrire l’audio en temps réel.

Quand choisir Scribe v2 ou Scribe v2 Realtime

Batch et realtime répondent à des besoins différents ; choisir le mauvais mode au départ conduit souvent à devoir tout revoir plus tard.

Pour mieux choisir, voici comment adapter le modèle à votre cas d’usage :

• Scribe v2 est adapté à tout ce qui nécessite que l’audio soit complet avant le traitement : enregistrements de réunions, transcription de podcasts, fichiers médias ou tout traitement hors ligne. Il prend en charge toutes les fonctionnalités, dont la diarisation, la détection d’entités et jusqu’à 1 000 keyterms.
• Scribe v2 Realtime est conçu pour l’audio en direct. Il accepte un flux WebSocket et renvoie les transcriptions à mesure que l’audio arrive, ce qui en fait le choix idéal pour les assistants vocaux ou tout scénario où l’application doit répondre avant la fin de la prise de parole.

Un autre point à prendre en compte : la précision varie selon la langue. Il est recommandé de vérifier le taux d’erreur de transcription avant de choisir une combinaison de langues. Scribe v2 publie des niveaux de Word Error Rate (WER) pour les plus de 90 langues prises en charge.

Une excellente précision (≤5 % WER) couvre les principales langues européennes, le japonais, l’indonésien, le vietnamien, entre autres. Une précision élevée (5-10 % WER) concerne l’hindi, le bengali, le mandarin, le coréen, le géorgien, etc. Consultez la répartition par catégorie dans la documentation sur la prise en charge des langues pour plus de détails.

Configuration de l’API Speech to Text ElevenLabs

Obtenir un client fonctionnel ne nécessite que deux étapes simples. D’abord, installez le SDK. Ensuite, stockez vos identifiants de façon sécurisée.

Voici comment procéder avant d’envoyer votre première requête de transcription.

Installez le SDK et stockez votre clé API comme secret géré, via un fichier .env ou le gestionnaire de secrets de votre plateforme. Ne codez jamais votre clé API en dur dans l’application.

Python

pip install elevenlabs
pip install python-dotenv

TypeScript

npm install @elevenlabs/elevenlabs-js

Créez un fichier .env :

ELEVENLABS_API_KEY=<your_api_key_here>

Initialisez le client :

Python

import os
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)

TypeScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

Votre première transcription batch avec l’API STT ElevenLabs

Votre client est prêt, vous pouvez envoyer votre premier fichier.

L’API batch prend un fichier, le transcrit et renvoie le résultat complet de façon synchrone. L’exemple ci-dessous transcrit un fichier audio distant avec diarisation des locuteurs et détection d’événements audio activées.

Python

# example.py
import os
from dotenv import load_dotenv
from io import BytesIO
import requests
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)

audio_url = (
    "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3"
)
response = requests.get(audio_url)
audio_data = BytesIO(response.content)

transcription = elevenlabs.speech_to_text.convert(
    file=audio_data,
    model_id="scribe_v2",          # Model to use
    tag_audio_events=True,          # Tag audio events like laughter, applause, etc.
    language_code="eng",            # Language of the audio file. If set to None, the model will detect the language automatically.
    diarize=True,                   # Whether to annotate who is speaking
)

print(transcription)

Exécutez :

python example.py

L’objet de réponse inclut le texte complet de la transcription, les mots avec timecodes et identifiants de locuteur, ainsi que les événements audio détectés.

Chaque entrée de mot comporte un champ type avec l’une des trois valeurs suivantes :

• word : Pour les mots transcrits dans l’audio.
• spacing : Pour les espaces entre les mots dans les langues qui en utilisent. Ce type ne s’applique pas à certaines langues comme le japonais, le cantonais ou le birman.
• audio_event : Balise pour tout son non verbal, comme un rire ou une toux.

Voici à quoi ressemble la structure de la réponse :

{
  "language_code": "en",
  "language_probability": 1,
  "text": "With a soft and whispery American accent, I'm the ideal choice for creating ASMR content, meditative guides, or adding an intimate feel to your narrative projects.",
  "words": [
    {
      "text": "With",
      "start": 0.119,
      "end": 0.259,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 0.239,
      "end": 0.299,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "a",
      "start": 0.279,
      "end": 0.359,
      "type": "word",
      "speaker_id": "speaker_0"
    }
  ]
}

Le champ language_probability indique le niveau de confiance du modèle dans la détection de la langue, sur une échelle de 0,00 à 1,00.

Intégration API STT en temps réel

STT en temps réel suit un schéma légèrement différent. Au lieu d’une requête et d’une réponse, vous ouvrez une connexion WebSocket et lisez les transcriptions à mesure qu’elles arrivent.

L’API realtime utilise un WebSocket pour recevoir un flux audio en direct et renvoyer les transcriptions à mesure de l’arrivée de l’audio. Deux types de transcription sont délivrés :

• Transcriptions partielles : Résultats intermédiaires mis à jour au fil du traitement de l’audio. Ils peuvent évoluer.
• Transcriptions validées : Résultats finalisés pour un segment de parole terminé. Ils ne changent plus. Ils peuvent aussi inclure des timecodes au mot si l’option « inclure les timecodes » est activée.

L’implémentation côté client utilise un jeton à usage unique plutôt que la clé API. Ce jeton temporaire expire au bout de 15 minutes et est généré côté serveur, de sorte que votre clé API n’est jamais exposée au navigateur.

Étape 1 : Générez un jeton à usage unique (côté serveur)

// Node.js server
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

app.get("/scribe-token", yourAuthMiddleware, async (req, res) => {
  const token = await elevenlabs.tokens.singleUse.create("realtime_scribe");

  res.json(token);
});

Étape 2 : Connectez-vous et transcrivez (côté client, React)

import { useScribe } from "@elevenlabs/react";

function MyComponent() {
  const scribe = useScribe({
    modelId: "scribe_v2_realtime",
    onPartialTranscript: (data) => {
      console.log("Partial:", data.text);
    },
    onCommittedTranscript: (data) => {
      console.log("Committed:", data.text);
    },
    onCommittedTranscriptWithTimestamps: (data) => {
      console.log("Committed with timestamps:", data.text);
      console.log("Timestamps:", data.words);
    },
  });

  const handleStart = async () => {
    // Fetch a single use token from the server
    const token = await fetchTokenFromServer();

    await scribe.connect({
      token,
      microphone: {
        echoCancellation: true,
        noiseSuppression: true,
      },
    });
  };

  return (
    <div>
      <button onClick={handleStart} disabled={scribe.isConnected}>
        Start Recording
      </button>
      <button onClick={scribe.disconnect} disabled={!scribe.isConnected}>
        Stop
      </button>

      {scribe.partialTranscript && <p>Live: {scribe.partialTranscript}</p>}

      <div>
        {scribe.committedTranscripts.map((t) => (
          <p key={t.id}>{t.text}</p>
        ))}
      </div>
    </div>
  );
}

Le hook useScribe gère le cycle de vie de la connexion WebSocket, l’accès au micro et l’état de la transcription. partialTranscript contient le texte en cours ; committedTranscripts est le tableau des segments finalisés.

Pour le streaming côté serveur (transcription d’un flux audio depuis une URL ou un fichier plutôt qu’un micro), consultez le guide de streaming côté serveur.

Concurrence et scalabilité pour les fichiers longs

Les fichiers longs nécessitent un modèle de scalabilité différent de la plupart des APIs. Il est utile de le comprendre avant de concevoir votre solution.

La gestion de la concurrence pour la transcription batch diffère de la plupart des APIs. Plutôt que de limiter le nombre de requêtes simultanées, Scribe v2 segmente automatiquement les fichiers longs et les traite en parallèle.

Les fichiers de plus de 8 minutes sont découpés en segments et transcrits simultanément. Le nombre de segments concurrents est calculé ainsi :

Concurrency = min(4, round_up(audio_duration_secs / 480))

Concrètement :

• Un fichier de 15 minutes utilise une concurrence de 2
• Un fichier de 120 minutes utilise une concurrence de 4 (maximum)

Les fichiers jusqu’à 10 heures et 3 Go sont pris en charge en mode standard. Remarque : le mode multicanal a une limite de durée inférieure — voir la section sur la transcription multicanal ci-dessous.

Côté formats, l’API STT accepte les formats audio et vidéo les plus courants :

• Audio : AAC, AIFF, OGG, MP3, OPUS, WAV, FLAC, M4A, WebM.
• Vidéo : MP4, AVI, MKV, MOV, WMV, FLV, WebM, MPEG, 3GPP.

Vous pouvez transmettre un fichier vidéo directement et obtenir la transcription de sa piste audio sans prétraitement.

Saisie de mots-clés

Les modèles génériques ont tendance à mal transcrire les noms de marque et le jargon technique. Le keyterm prompting vise à corriger cela.

Le keyterm prompting oriente le modèle vers certains mots ou expressions lors de la transcription. C’est l’outil adapté si votre audio contient des noms de produits, des termes techniques ou des noms propres à l’orthographe inhabituelle.

Un avantage du keyterm prompting est l’utilisation du contexte, ce qui le rend plus fiable qu’une simple liste de mots-clés. Si vous indiquez « ElevenLabs » comme keyterm, le modèle le transcrira correctement lorsque le nom de l’entreprise est prononcé. Sans cela, il pourrait mal transcrire « J’ai travaillé chez eleven labs pendant un an ».

Sans keyterm prompting :

I work at eleven labs.

Avec keyterms=["ElevenLabs"] :

I work at ElevenLabs.

Le mode batch accepte jusqu’à 1 000 keyterms (50 caractères chacun). Le mode realtime accepte jusqu’à 50 keyterms (20 caractères chacun).

Transcription batch avec keyterms

Python

import os
from dotenv import load_dotenv
from io import BytesIO
import requests
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)

audio_url = (
    "https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/stt-keyterm-prompting.mp3"
)
response = requests.get(audio_url)
audio_data = BytesIO(response.content)

transcription = elevenlabs.speech_to_text.convert(
    file=audio_data,
    model_id="scribe_v2",
    # Keyterms to prompt the model with.
    # Up to 1,000 keyterms can be provided, with a maximum length of 50 characters each
    keyterms=["ElevenLabs"],
)

print(transcription)

Streaming en temps réel avec keyterms

Transmettez les keyterms lors de la connexion au WebSocket realtime :

Python

connection = await elevenlabs.speech_to_text.realtime.connect(RealtimeUrlOptions(
    model_id="scribe_v2_realtime",
    keyterms=["ElevenLabs"],
))

Ou passez-les en paramètres de requête directement dans l’URL du WebSocket :

wss://api.elevenlabs.io/v1/speech-to-text/realtime?model_id=scribe_v2_realtime&keyterms=ElevenLabs&keyterms=AnotherTerm

Le keyterm prompting entraîne un coût supplémentaire. Consultez la page de tarification de l’API pour plus d’informations.

Fonctionnalités avancées

Au-delà du flux de transcription principal, plusieurs fonctionnalités enrichissent le résultat final. Voici quelques options avancées à exploiter dans votre API Speech to Text :

• Diarisation des locuteurs pour identifier qui parle
• Mode no-verbatim pour nettoyer les transcriptions
• Détection d’entités pour signaler les données sensibles
• Transcription multicanal pour séparer les pistes audio

Voyons ces fonctionnalités plus en détail.

Diarisation des locuteurs

Activez diarize=True dans votre requête batch pour annoter qui parle. Scribe v2 prend en charge jusqu’à 32 locuteurs. Chaque mot de la réponse inclut un champ speaker_id (ex. speaker_0, speaker_1) permettant de séparer les segments par locuteur.

La diarisation est utile pour la transcription de réunions, d’entretiens ou tout enregistrement multi-locuteurs où l’attribution correcte des paroles est essentielle.

Mode no-verbatim

Avec no_verbatim=True, le modèle supprime les hésitations, faux départs et disfluences de la transcription. « Euh, P-peut-être qu’on devrait, euh, choisir l’option A » devient « Peut-être qu’on devrait choisir l’option A. »

Cela produit un rendu plus lisible pour les sous-titres, résumés ou tout cas d’usage où la clarté prime sur l’exhaustivité. Disponible en batch (scribe_v2) et en temps réel (scribe_v2_realtime).

Détection et masquage d’entités

Scribe v2 peut détecter et annoter les entités dans la transcription, avec timecodes précis pour chaque entité détectée. Les catégories incluent les PII (noms, numéros de carte, numéros de sécurité sociale), PHI (informations médicales), PCI (données de paiement), etc. Pour la liste complète des entités prises en charge, consultez la documentation sur la détection d’entités.

C’est particulièrement utile pour les usages réglementaires, afin d’identifier et masquer automatiquement les informations sensibles avant stockage ou affichage.

La détection d’entités entraîne un coût additionnel de 0,070 $ (par heure) en plus du coût de transcription. Consultez la page de tarification de l’API pour plus d’informations.

Transcription multicanal

Avec use_multi_channel=True, chaque canal audio est transcrit indépendamment et reçoit un speaker ID basé sur son numéro de canal. Jusqu’à 5 canaux sont pris en charge. La durée maximale d’un fichier en mode multicanal est de 1 heure.

Le mode multicanal est utile si vous disposez d’une piste audio par intervenant — par exemple, un enregistrement d’appel téléphonique où chaque participant est sur son propre canal. Cela permet une attribution plus précise des locuteurs qu’une diarisation sur un fichier mono mixé.

Livraison asynchrone avec webhooks

Le polling fonctionne à faible volume mais ne passe pas à l’échelle avec des fichiers longs ou des pipelines à haut débit. Les webhooks résolvent ce problème en vous envoyant le résultat dès qu’il est prêt.

Pour les fichiers longs ou les pipelines volumineux, attendre une réponse synchrone n’est pas toujours viable. Les webhooks permettent de soumettre une demande de transcription et de recevoir le résultat sur votre endpoint dès que le traitement est terminé, sans polling.

Configuration d’un webhook

Dans le Dashboard ElevenLabs, rendez-vous dans Développeurs > Webhooks, cliquez sur Créer un webhook et configurez :

• Nom : Saisissez un nom descriptif et mémorable pour votre webhook.
• URL de callback : Ajoutez une URL HTTPS publique accessible pour le webhook.
• Méthode d’authentification du webhook : Sélectionnez HMAC ou OAuth (optionnel mais fortement recommandé pour la sécurité).
• Événements : Sélectionnez « Transcription terminée » dans les options.

Soumettre une transcription avec livraison par webhook

Python

from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)

def transcribe_with_webhook(audio_file):
    try:
        result = elevenlabs.speech_to_text.convert(
            file=audio_file,
            model_id="scribe_v2",
            webhook=True,
        )
        print(f"Transcription started: {result.request_id}")
        return result
    except Exception as e:
        print(f"Error starting transcription: {e}")
        raise e

Avec webhook=True, la requête retourne immédiatement sans la transcription. La transcription complète est envoyée à votre endpoint via une requête POST à la fin du traitement.

Implémentation de votre endpoint webhook

import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';
import 'dotenv/config';
import express from 'express';

const elevenlabs = new ElevenLabsClient();
const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

app.post('/webhook/speech-to-text', (req, res) => {
  try {
    const signature = req.headers['elevenlabs-signature'];
    const payload = JSON.stringify(req.body);
    let event;

    try {
      // Verify the webhook signature.
      event = await elevenlabs.webhooks.constructEvent(payload, signature, WEBHOOK_SECRET);
    } catch (error) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    if (event.type === 'speech_to_text.completed') {
      const { requestId, status, text, language_code } = event.data;

      console.log(`Transcription ${requestId} completed`);
      console.log(`Language: ${language_code}`);
      console.log(`Text: ${text}`);

      processTranscription(requestId, text, language_code);
    } else if (status === 'failed') {
      console.error(`Transcription ${requestId} failed`);
      handleTranscriptionError(requestId);
    }

    res.status(200).json({ received: true });
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

Structure du payload webhook

Votre endpoint reçoit un POST avec la structure suivante :

{
  "type": "speech_to_text_transcription",
  "data": {
    "request_id": "some-request-id-123",
    "webhook_metadata": {},
    "transcription": {
      "language_code": "en",
      "language_probability": 0.98,
      "text": "Hello world!",
      "words": [
        {
          "text": "Hello",
          "start": 0.0,
          "end": 0.5,
          "type": "word",
          "speaker_id": "speaker_1"
        }
      ]
    }
  }
}

Bonnes pratiques de sécurité pour les webhooks

Lors de l’utilisation des webhooks, quelques mesures de sécurité permettent de garantir la bonne réception et le bon traitement des événements.

• Vérifiez la signature du webhook : Vérifiez toujours la signature du webhook avec elevenlabs.webhooks.constructEvent() pour confirmer l’origine ElevenLabs.
• Utilisez des endpoints HTTPS : Les URLs de webhook doivent être en HTTPS pour protéger les données en transit.
• Retournez le code HTTP approprié : Retournez 200-299 pour un traitement réussi, 400-499 pour une erreur côté client (pas de nouvelle tentative), et 500-599 pour une erreur serveur (nouvelle tentative automatique).
• Utilisez un outil de tunneling pour le développement local : Pour le développement local, utilisez un outil comme ngrok pour exposer votre serveur local via une URL HTTPS publique.

Avec ces stratégies, vous pouvez utiliser les webhooks en toute confiance.

Points clés pour votre intégration API Speech to Text

Une intégration API Speech to Text en production repose sur quelques décisions structurantes.

Faites les bons choix et tout s’enchaîne :

• Choisissez le mode selon le cas d’usage : Utilisez batch (scribe_v2) si l’audio est complet avant le traitement. Utilisez realtime (scribe_v2_realtime) pour transcrire l’audio en temps réel, par exemple pour des agents, assistants vocaux ou sous-titres en direct.
• Utilisez les keyterms pour la précision sur le vocabulaire spécifique : Transmettez les noms de produits, termes techniques ou noms propres inhabituels comme keyterms. Le modèle utilise le contexte pour les appliquer correctement sans surdéclenchement.
• Laissez l’API gérer les fichiers longs : Les fichiers de plus de 8 minutes sont parallélisés automatiquement, inutile de les découper vous-même. Jusqu’à 10 heures et 3 Go sont pris en charge en mode standard.
• Utilisez les webhooks pour les pipelines asynchrones : Pour les traitements longs ou à fort volume, webhook=True permet de soumettre et de passer à la suite. Vérifiez la signature de chaque payload webhook reçu.
• Activez le mode no-verbatim pour un rendu propre : Pour les sous-titres, résumés ou traitements NLP, no_verbatim=True supprime automatiquement les hésitations et disfluences.
• Utilisez le mode multicanal pour séparer les pistes audio : Si votre enregistrement comporte un canal par intervenant (centre d’appels, interviews…), la transcription multicanal permet une attribution plus précise des locuteurs qu’une diarisation sur un fichier mixé. Attention à la limite de 1 heure dans ce mode.

Pour aller plus loin, explorez la documentation complète de l’API pour démarrer.

Développez votre intégration Speech to Text avec ElevenAPI

Après lecture de ce guide, vous disposez de tous les schémas nécessaires pour une intégration API Speech to Text en production. Entre transcription batch, realtime et fonctionnalités avancées comme le keyterm prompting ou la livraison asynchrone, vous êtes prêt à lancer votre application avec STT intégré.

Pour commencer, découvrez-en plus sur l’API Speech to Text ou inscrivez-vous pour effectuer votre premier appel avec ElevenAPI dès aujourd’hui.

FAQ sur l’intégration de l’API STT