AnleitungenSpeech to TextStapelverarbeitung

Asynchrones Speech to Text

Dieser Leitfaden zeigt Ihnen, wie Sie Webhooks verwenden, um asynchrone Benachrichtigungen zu erhalten, wenn Transkriptionsaufgaben abgeschlossen sind.

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

Überblick

Webhooks ermöglichen automatische Benachrichtigungen, wenn Ihre Speech-to-Text-Transkriptionsaufgaben abgeschlossen sind. So müssen Sie die API nicht kontinuierlich nach Statusupdates abfragen. Das ist besonders nützlich für lang laufende Transkriptionsjobs oder die 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

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

1

Webhook erstellen oder bearbeiten

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

Dialog zum Erstellen eines Webhooks mit ausgewählter Option Transkription abgeschlossen
Wählen Sie beim Erstellen oder Bearbeiten des Webhooks Transkription abgeschlossen aus

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 zur Verifizierung, erzwingt diese jedoch nicht.
  • Ereignisse: Wählen Sie Transkription abgeschlossen.
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.

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 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.

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

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

Sicherheitsaspekte

Signaturverifizierung

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

HTTPS-Anforderung

Webhook-URLs müssen HTTPS verwenden, damit Transkriptionsdaten sicher übertragen werden.

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 passende HTTP-Statuscodes zurück:

  • 200-299: Erfolg – Webhook wurde erfolgreich verarbeitet
  • 400-499: Client-Fehler – Webhook wird nicht erneut versucht
  • 500-599: Serverfehler – Webhook wird erneut versucht

Webhooks testen

Lokale Entwicklung

Für lokale Tests können Sie Tools wie ngrok verwenden, 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 ausführen 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

Serverseitiges Streaming

Transkribieren Sie Audio in Echtzeit mit der WebSocket-basierten Streaming-API.

API-Referenz

Vollständige Speech-to-Text-API-Referenz und Parameter.