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, sans avoir à interroger continuellement l’API pour obtenir des mises à jour de statut. Ils sont particulièrement utiles pour les tâches de transcription de longue durée 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 que vous avez indiquée avec les résultats de transcription, notamment le texte transcrit, la détection de 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 ne l’impose pas.
• Événements : sélectionnez Transcription terminée.

2

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

Lors d’appels API de conversion de la parole en texte, incluez le paramètre webhook défini sur true afin d’activer les notifications de 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_v3",
      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 incluait 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 comporte pas d’objet data : il contient un request_id de niveau supérieur, identique à l’identifiant renvoyé lorsque la requête a été acceptée, 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 de webhook afin de 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 de 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 en cas d’échec

Renvoyez un code d’état 2xx pour accuser réception du webhook.

Par défaut, les webhooks de transcription Speech to Text sont envoyés une seule 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 ayant échoué (5xx, 408, 429 ou erreurs de connexion) sont relancées jusqu’à 5 fois supplémentaires, 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 nouvelles tentatives. Chaque tentative pour un même événement comporte le même en-tête ElevenLabs-Webhook-Delivery-Id, ce qui permet à votre gestionnaire d’ignorer les doublons.

Les requêtes effectuées avec enable_logging défini sur false (mode zéro rétention) bénéficient d’un maximum de 2 nouvelles tentatives rapides, 5 secondes et 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 du 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 locaux, utilisez des outils comme ngrok pour 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_v3",
    webhook: true,
  });
  console.log("Test transcription started:", result.requestId);
}

Étapes suivantes