Speech to Text asynchrone

Vue d’ensemble

Les webhooks vous permettent de recevoir des notifications automatiques lorsque vos tâches de transcription Speech to Text sont terminées. Vous n’avez ainsi plus besoin d’interroger continuellement l’API pour obtenir des mises à jour de statut. Cette approche est particulièrement utile pour les tâches de transcription longues ou le traitement de volumes importants de fichiers audio.

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

Utiliser les webhooks

1

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.

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 appartient au client d’implémenter le mécanisme de vérification. ElevenLabs envoie des en-têtes permettant la vérification, mais nous ne l’imposons pas.
• Événements : sélectionnez Transcription terminée.

2

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

Lorsque vous effectuez des appels API de conversion de parole en texte, incluez le paramètre webhook défini sur true afin d’activer les notifications par webhook pour cette requête spécifique.

PythonTypeScript

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 de 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 inclut une instruction transcript_edit, l’objet transcription contient également un champ edited_transcript avec le texte modifié.

Si la transcription échoue, votre point de terminaison reçoit à la place un événement webhook_error. Il ne contient pas d’objet data : il comprend un request_id de premier niveau, identique à l’identifiant renvoyé lors de l’acceptation de la requête, un error_message et les webhook_metadata de la requête.

Implémenter votre point de terminaison de webhook

Voici un exemple d’implémentation d’un point de terminaison de 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();
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;
// The raw body is required: verification runs over the exact bytes sent.
app.post("/webhook/speech-to-text", express.raw({ type: "application/json" }), async (req, res) => {
  const signature = req.headers["elevenlabs-signature"];
  let event;
  try {
    event = await elevenlabs.webhooks.constructEvent(
      req.body.toString(),
      signature,
      WEBHOOK_SECRET
    );
  } catch (error) {
    return res.status(401).json({ error: "Invalid signature" });
  }
  if (event.type === "speech_to_text_transcription") {
    const { request_id, transcription } = event.data;
    console.log(`Transcription ${request_id} completed`);
    console.log(`Language: ${transcription.language_code}`);
    console.log(`Text: ${transcription.text}`);
    processTranscription(request_id, transcription);
  } else if (event.type === "webhook_error") {
    console.error(`Transcription ${event.request_id} failed: ${event.error_message}`);
    handleTranscriptionError(event.request_id, event.webhook_metadata, event.error_message);
  }
  res.status(200).json({ received: true });
});
async function processTranscription(requestId, transcription) {
  console.log("Processing completed transcription...");
}
async function handleTranscriptionError(requestId, webhookMetadata, errorMessage) {
  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 de garantir une 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 de webhook afin d’é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 en cas d’échec

Renvoyez un code de statut 2xx pour accuser réception du webhook.

Par défaut, les webhooks de transcription Speech to Text ne sont envoyés qu’une fois. Toute réponse autre que 2xx est considérée comme un échec de livraison, et les échecs répétés désactivent automatiquement le webhook.

Si vous activez les nouvelles tentatives pour le webhook, les livraisons échouées (5xx, 408, 429 ou erreurs de connexion) font l’objet de cinq nouvelles tentatives au maximum, environ 30 secondes, 2 minutes, 8 minutes, 30 minutes et 30 minutes après la tentative précédente. Les autres réponses 4xx ne font pas l’objet de nouvelle tentative. Chaque tentative pour le même événement comporte le même en-tête ElevenLabs-Webhook-Delivery-Id, votre gestionnaire peut donc ignorer les doublons.

Les requêtes effectuées avec enable_logging défini sur false (mode zéro rétention) bénéficient au maximum de deux nouvelles tentatives rapides, 5 secondes puis 30 secondes après la tentative précédente, lorsque les nouvelles tentatives sont activées. La transcription n’est jamais stockée.

Si une livraison échoue toujours, récupérez le résultat avec Obtenir la transcription à l’aide de transcription_id, renvoyé lorsque la requête a été acceptée. Les transcriptions ne sont pas stockées pour les requêtes effectuées avec enable_logging défini sur false.

Tester les webhooks

Développement local

Pour les tests en local, utilisez des outils tels que ngrok afin d’exposer votre serveur local :

ngrok http 3000

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

Test des webhooks

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