Speech to Text asynchrone | ElevenLabs Documentation

Guide pratique · Suppose que vous avez suivi le guide de démarrage rapide de Speech to Text .

Vue d’ensemble

Les webhooks vous permettent de recevoir des notifications automatiques lorsque vos tâches de transcription Speech to Text sont terminées, sans avoir à interroger continuellement l’API pour connaître leur état. Ils sont particulièrement utiles pour les tâches de transcription longues ou le traitement de grands volumes de fichiers audio.

Lorsqu’une transcription est terminée, ElevenLabs envoie une requête POST à l’URL de webhook spécifiée avec les résultats de la transcription, notamment le texte transcrit, la détection de langue et les métadonnées.

Utiliser les webhooks

Ce guide suppose que vous avez configuré votre clé API et votre SDK. Suivez d’abord le guide de démarrage rapide si ce n’est pas déjà fait.

Créer ou modifier un webhook

Dans le Dashboard ElevenLabs, accédez à Développeurs > Webhooks. Cliquez sur Créer un webhook ou modifiez un webhook existant.

Boîte de dialogue Créer un webhook avec Transcription terminée sélectionné — Sélectionnez Transcription terminée lors de la création ou de la modification du webhook

Configurez le webhook avec :

Nom : un nom descriptif pour votre webhook
URL de rappel : votre point de terminaison HTTPS accessible publiquement
Méthode d’authentification du webhook : HMAC ou OAuth. Il revient au client d’implémenter le mécanisme de vérification. ElevenLabs envoie des en-têtes permettant cette vérification, mais nous ne l’imposons pas.
Événements : sélectionnez Transcription terminée.

Effectuer des appels API avec le paramètre webhook activé

Lors des appels à l’API de conversion de la parole en texte, incluez le paramètre webhook défini sur true afin d’activer les notifications webhook pour cette requête précise.

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

Charge utile du webhook

Lorsqu’une transcription est terminée, votre point de terminaison webhook reçoit une requête POST contenant les données de transcription et du webhook :

{
  type: 'speech_to_text_transcription',
  data: {
    request_id: 'some-request-id-123',
    webhook_metadata: { ... }, // if provided in the convert request
    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"
        },
        {
          "text": " ",
          "start": 0.5,
          "end": 0.5,
          "type": "spacing",
          "speaker_id": "speaker_1"
        },
        {
          "text": "world!",
          "start": 0.5,
          "end": 1.2,
          "type": "word",
          "speaker_id": "speaker_1"
        }
      ]
    }
  }
}

Consultez le guide de l’API Speech to Text pour en savoir plus sur la structure de la réponse.

Si la requête incluait une instruction transcript_edit, l’objet transcription contient également un champ edited_transcript avec le texte modifié.

Implémenter votre point de terminaison webhook

Voici un exemple d’implémentation d’un point de terminaison webhook pour gérer les notifications entrantes :

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' });
  }
});
async function processTranscription(requestId, text, language) {
  console.log('Processing completed transcription...');
}
async function handleTranscriptionError(requestId) {
  console.log('Handling transcription error...');
}
app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

Considérations de sécurité

Vérification de signature

Vérifiez toujours les signatures des webhooks pour vous assurer que les requêtes proviennent d’ElevenLabs.

Exigence HTTPS

Les URL de webhook doivent utiliser HTTPS afin d’assurer la transmission sécurisée des données de transcription.

Limitation du débit

Implémentez une limitation du débit sur votre point de terminaison webhook pour éviter les abus :

import rateLimit from "express-rate-limit";
const webhookLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // limit each IP to 100 requests per windowMs
  message: "Too many webhook requests from this IP",
});
app.use("/webhook", webhookLimiter);

Réponses aux échecs

Renvoyez les codes de statut HTTP appropriés :

200-299 : succès, webhook traité avec succès
400-499 : erreur client, le webhook ne sera pas réessayé
500-599 : erreur serveur, le webhook sera réessayé

Tester les webhooks

Développement local

Pour les tests locaux, utilisez des outils comme ngrok afin d’exposer votre serveur local :

ngrok http 3000

Utilisez l’URL HTTPS fournie comme point de terminaison webhook pendant le développement.

Test de webhook

Vous pouvez tester votre implémentation de webhook en effectuant une requête de transcription et en surveillant votre point de terminaison :

async function testWebhook() {
  const audioFile = new File([audioBuffer], "test.mp3", { type: "audio/mp3" });
  const result = await elevenlabs.speechToText.convert({
    file: audioFile,
    modelId: "scribe_v2",
    webhook: true,
  });
  console.log("Test transcription started:", result.requestId);
}

Étapes suivantes

Streaming côté serveur

Transcrivez l’audio en temps réel avec l’API de streaming basée sur WebSocket.

Guide de l’API

Guide complet de l’API Speech to Text et de ses paramètres.