Asynchrones Speech to Text

Überblick

Webhooks ermöglichen Ihnen, automatische Benachrichtigungen zu erhalten, wenn Ihre Speech to Text-Transkriptionsaufgaben abgeschlossen sind. So müssen Sie die API nicht fortlaufend nach Statusaktualisierungen abfragen. Das ist besonders nützlich für lang laufende Transkriptionsaufgaben oder bei der Verarbeitung großer Mengen an Audiodateien.

Wenn eine Transkription abgeschlossen ist, sendet ElevenLabs eine POST-Anfrage mit den Transkriptionsergebnissen an Ihre angegebene Webhook-URL, einschließlich Transkripttext, Spracherkennung und Metadaten.

Webhooks verwenden

1

Webhook erstellen oder bearbeiten

Öffnen Sie im ElevenLabs-Dashboard Entwickler > Webhooks. Klicken Sie auf Webhook erstellen oder bearbeiten Sie einen vorhandenen Webhook.

Konfigurieren Sie den Webhook mit:

• Name: Ein aussagekräftiger Name für Ihren Webhook
• Callback-URL: Ihr öffentlich zugänglicher HTTPS-Endpunkt
• Webhook-Authentifizierungsmethode: Entweder HMAC oder OAuth. Die Implementierung des Verifizierungsmechanismus liegt beim Client. ElevenLabs sendet Header, die eine Verifizierung ermöglichen, erzwingt sie jedoch nicht.
• Ereignisse: Wählen Sie Transkription abgeschlossen aus.

2

API-Aufrufe mit aktiviertem Webhook-Parameter ausführen

Fügen Sie bei Speech-to-Text-API-Aufrufen den Parameter webhook mit dem Wert true hinzu, um Webhook-Benachrichtigungen für diese Anfrage zu aktivieren.

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

Webhook-Payload

Wenn eine Transkription abgeschlossen ist, erhält Ihr Webhook-Endpunkt eine POST-Anfrage mit den Transkriptions- und Webhook-Daten:

{
  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"
        }
      ]
    }
  }
}

Weitere Informationen zur Struktur der Antwort finden Sie in der Referenz zur Speech-to-Text-API.

Wenn die Anfrage eine transcript_edit-Anweisung enthielt, enthält das Objekt transcription außerdem ein Feld edited_transcript mit dem bearbeiteten Text.

Wenn die Transkription fehlschlägt, erhält Ihr Endpunkt stattdessen ein webhook_error-Ereignis. Es enthält kein data-Objekt: Es übermittelt eine request_id auf oberster Ebene (dieselbe ID, die beim Akzeptieren der Anfrage zurückgegeben wurde), eine error_message und die webhook_metadata der Anfrage.

Webhook-Endpunkt implementieren

Hier ist ein Beispiel für die Implementierung eines Webhook-Endpunkts zur Verarbeitung eingehender Benachrichtigungen:

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");
});

Sicherheitsaspekte

Signaturverifizierung

Verifizieren Sie immer Webhook-Signaturen, um sicherzustellen, dass Anfragen von ElevenLabs stammen.

HTTPS-Anforderung

Webhook-URLs müssen HTTPS verwenden, um die sichere Übertragung von Transkriptionsdaten zu gewährleisten.

Ratenbegrenzung

Implementieren Sie eine Ratenbegrenzung für Ihren Webhook-Endpunkt, um Missbrauch zu verhindern:

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);

Fehlerantworten

Geben Sie einen 2xx-Statuscode zurück, um den Webhook zu bestätigen.

Standardmäßig werden Speech to Text-Transkriptionswebhooks einmal zugestellt. Jede Antwort, die nicht 2xx ist, gilt als fehlgeschlagene Zustellung. Wiederholte Fehler deaktivieren den Webhook automatisch.

Wenn Sie Wiederholungsversuche für den Webhook aktivieren, werden fehlgeschlagene Zustellungen (5xx, 408, 429 oder Verbindungsfehler) bis zu 5-mal erneut versucht: etwa 30 Sekunden, 2 Minuten, 8 Minuten, 30 Minuten und 30 Minuten nach dem vorherigen Versuch. Andere 4xx-Antworten werden nicht erneut versucht. Jeder Versuch für dasselbe Ereignis enthält denselben Header ElevenLabs-Webhook-Delivery-Id, sodass Ihr Handler Duplikate ignorieren kann.

Anfragen mit enable_logging auf false (Modus ohne Speicherung) erhalten bei aktivierten Wiederholungsversuchen bis zu 2 schnelle Wiederholungen: 5 Sekunden und 30 Sekunden nach dem vorherigen Versuch. Das Transkript wird niemals gespeichert.

Wenn eine Zustellung weiterhin fehlschlägt, rufen Sie das Ergebnis mit Transkript abrufen über die transcription_id ab, die beim Akzeptieren der Anfrage zurückgegeben wurde. Transkripte werden für Anfragen mit enable_logging auf false nicht gespeichert.

Webhooks testen

Lokale Entwicklung

Verwenden Sie für lokale Tests Tools wie ngrok, um Ihren lokalen Server öffentlich zugänglich zu machen:

ngrok http 3000

Verwenden Sie während der Entwicklung die bereitgestellte HTTPS-URL als Ihren Webhook-Endpunkt.

Webhook-Tests

Sie können Ihre Webhook-Implementierung testen, indem Sie eine Transkriptionsanfrage stellen und Ihren Endpunkt überwachen:

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);
}

Nächste Schritte