Asynchroniczna zamiana mowy na tekst

Omówienie

Webhooki pozwalają otrzymywać automatyczne powiadomienia po zakończeniu zadań transkrypcji Speech to Text, więc nie musisz stale odpytywać API o aktualizacje statusu. Jest to szczególnie przydatne w przypadku długich zadań transkrypcji lub przetwarzania dużej liczby plików audio.

Po zakończeniu transkrypcji ElevenLabs wysyła żądanie POST na wskazany adres URL webhooka wraz z wynikami transkrypcji, w tym tekstem transkrypcji, wykrytym językiem i metadanymi.

Korzystanie z webhooków

1

Utwórz lub edytuj webhook

W panelu ElevenLabs przejdź do Deweloperzy > Webhooki. Kliknij Utwórz webhook lub edytuj istniejący webhook.

Skonfiguruj webhook:

• Nazwa: Opisowa nazwa webhooka
• Adres URL wywołania zwrotnego: Publicznie dostępny endpoint HTTPS
• Metoda uwierzytelniania webhooka: HMAC lub OAuth. To klient wdraża mechanizm weryfikacji. ElevenLabs wysyła nagłówki umożliwiające weryfikację, ale jej nie wymuszamy.
• Zdarzenia: Wybierz Transcription completed.

2

Wykonuj wywołania API z włączonym parametrem webhook

Podczas wywoływania API zamiany mowy na tekst dodaj parametr webhook ustawiony na true, aby włączyć powiadomienia webhook dla tego żądania.

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

Dane webhooka

Po zakończeniu transkrypcji endpoint webhooka otrzyma żądanie POST z danymi transkrypcji i webhooka:

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

Szczegóły struktury odpowiedzi znajdziesz w dokumentacji API zamiany mowy na tekst.

Jeśli żądanie zawierało instrukcję transcript_edit, obiekt transcription zawiera też pole edited_transcript z edytowanym tekstem.

Jeśli transkrypcja się nie powiedzie, endpoint otrzyma zamiast tego zdarzenie webhook_error. Nie ma ono obiektu data: zawiera najwyższego poziomu request_id (to samo id, które zwrócono po przyjęciu żądania), error_message oraz webhook_metadata żądania.

Implementacja endpointu webhooka

Oto przykład implementacji endpointu webhooka obsługującego przychodzące powiadomienia:

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

Kwestie bezpieczeństwa

Weryfikacja podpisu

Zawsze weryfikuj podpisy webhooków, aby upewnić się, że żądania pochodzą od ElevenLabs.

Wymaganie HTTPS

Adresy URL webhooków muszą korzystać z HTTPS, aby zapewnić bezpieczne przesyłanie danych transkrypcji.

Ograniczanie liczby żądań

Wdróż ograniczanie liczby żądań w endpoincie webhooka, aby zapobiec nadużyciom:

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

Odpowiedzi w razie błędu

Zwróć kod statusu 2xx, aby potwierdzić odbiór webhooka.

Domyślnie webhooki transkrypcji Speech to Text są dostarczane raz. Każda odpowiedź inna niż 2xx jest uznawana za nieudane dostarczenie, a powtarzające się błędy automatycznie wyłączają webhook.

Jeśli włączysz ponawianie prób dla webhooka, nieudane dostarczenia (5xx, 408, 429 lub błędy połączenia) są ponawiane maksymalnie 5 razy — około 30 sekund, 2 minuty, 8 minut, 30 minut i 30 minut po poprzedniej próbie. Inne odpowiedzi 4xx nie są ponawiane. Każda próba dla tego samego zdarzenia ma ten sam nagłówek ElevenLabs-Webhook-Delivery-Id, więc handler może ignorować duplikaty.

Żądania z enable_logging ustawionym na false (tryb zerowej retencji) otrzymują maksymalnie 2 szybkie ponowienia — 5 sekund i 30 sekund po poprzedniej próbie — jeśli ponawianie jest włączone. Transkrypcja nigdy nie jest przechowywana.

Jeśli dostarczenie nadal się nie powiedzie, pobierz wynik przez Get transcript, używając transcription_id zwróconego po przyjęciu żądania. Transkrypcje nie są przechowywane w przypadku żądań z enable_logging ustawionym na false.

Testowanie webhooków

Lokalny development

Do testów lokalnych użyj narzędzi takich jak ngrok, aby udostępnić lokalny serwer:

ngrok http 3000

Podczas developmentu użyj podanego adresu HTTPS jako endpointu webhooka.

Testowanie webhooka

Możesz przetestować implementację webhooka, wysyłając żądanie transkrypcji i monitorując endpoint:

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

Kolejne kroki