Zur Navigation springen

Asynchrones Speech to Text

In diesem Leitfaden erfahren Sie, wie Sie Webhooks für asynchrone Benachrichtigungen nach Abschluss von Transkriptionsaufgaben verwenden.

Anleitung · Setzt voraus, dass Sie den Speech to Text- Schnellstart abgeschlossen haben.

Überblick

Mit Webhooks erhalten Sie automatisch Benachrichtigungen, wenn Ihre Speech-to-Text-Transkriptionsaufgaben abgeschlossen sind. So müssen Sie die API nicht kontinuierlich auf Statusupdates abfragen. Das ist besonders nützlich für lang laufende Transkriptionsaufträge oder bei der Verarbeitung großer Mengen an Audiodateien.

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

Webhooks verwenden

Diese Anleitung setzt voraus, dass Sie Ihren API-Schlüssel und das SDK eingerichtet haben. Schließen Sie zuerst den Schnellstart ab, falls Sie dies noch nicht getan haben.

1

Webhook erstellen oder bearbeiten

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

Dialog „Webhook erstellen“ mit ausgewählter Option „Transkription abgeschlossen“
Wählen Sie beim Erstellen oder Bearbeiten des Webhooks Transkription abgeschlossen

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. Der Client implementiert den Verifizierungsmechanismus. ElevenLabs sendet Header, die eine Verifizierung ermöglichen, erzwingt sie aber nicht.
  • Ereignisse: Wählen Sie Transkription abgeschlossen.
2

API-Aufrufe mit aktiviertem Webhook-Parameter durchfü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.

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

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

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

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

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

Ihren 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

Signaturprüfung

Prüfen 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 an Ihrem 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 Nicht-2xx-Antwort zählt als fehlgeschlagene Zustellung, und wiederholte Fehler deaktivieren den Webhook automatisch.

Wenn Sie Wiederholungsversuche für den Webhook aktivieren, werden fehlgeschlagene Zustellungen (5xx, 408, 429 oder Verbindungsfehler) bis zu fünf weitere Male wiederholt: ungefähr 30 Sekunden, 2 Minuten, 8 Minuten, 30 Minuten und 30 Minuten nach dem vorherigen Versuch. Andere 4xx-Antworten werden nicht wiederholt. 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 zwei schnelle Wiederholungen, 5 Sekunden und 30 Sekunden nach dem vorherigen Versuch. Das Transkript wird niemals gespeichert.

Falls eine Zustellung weiterhin fehlschlägt, rufen Sie das Ergebnis mit Transkript abrufen über die transcription_id ab, die bei Annahme 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 verfügbar 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_v3",
webhook: true,
});
console.log("Test transcription started:", result.requestId);
}

Nächste Schritte