PoradnikiMowa na tekstWsadowe

Asynchroniczne Speech to Text

Ten przewodnik pokazuje, jak używać webhooków do odbierania asynchronicznych powiadomień po zakończeniu zadań transkrypcji.

Przewodnik krok po kroku · Zakłada, że ukończono krótki przewodnik po Speech to Text .

Omówienie

Webhooki pozwalają otrzymywać automatyczne powiadomienia po ukończeniu zadań transkrypcji Speech to Text, więc nie musisz stale odpytywać API o aktualizacje statusu. Jest to szczególnie przydatne przy długich zadaniach transkrypcji lub przetwarzaniu dużych ilości plików audio.

Po ukończeniu transkrypcji ElevenLabs wyśle żądanie POST na wskazany adres URL webhooka z wynikami transkrypcji, w tym tekstem, wykrytym językiem i metadanymi.

Korzystanie z webhooków

Ten przewodnik zakłada, że skonfigurowano klucz API i SDK. Jeśli jeszcze tego nie zrobiono, najpierw ukończ krótki przewodnik.

1

Utwórz lub edytuj webhook

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

Okno tworzenia webhooka z wybraną opcją Transcription completed
Wybierz Transcription completed podczas tworzenia lub edycji webhooka

Skonfiguruj webhook:

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

Wywołuj API z włączonym parametrem webhook

Podczas wywołań API mowa-mowa dodaj parametr webhook ustawiony na true, aby włączyć powiadomienia webhook dla danego żądania.

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

Ładunek webhooka

Po ukończeniu transkrypcji punkt końcowy 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"
        }
      ]
    }
  }
}

Więcej informacji o strukturze odpowiedzi znajdziesz w dokumentacji Speech-to-text API.

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

Implementacja punktu końcowego webhooka

Oto przykład implementacji punktu końcowego webhooka do obsługi przychodzących powiadomień:

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

Kwestie bezpieczeństwa

Weryfikacja podpisu

Zawsze weryfikuj podpisy webhooków, aby mieć pewność, że żądania pochodzą od ElevenLabs.

Wymóg HTTPS

Adresy URL webhooków muszą używać HTTPS, aby zapewnić bezpieczne przesyłanie danych transkrypcji.

Ograniczanie liczby żądań

Wprowadź ograniczanie liczby żądań w punkcie końcowym 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 na błędy

Zwracaj odpowiednie kody statusu HTTP:

  • 200-299: Sukces — webhook przetworzony pomyślnie
  • 400-499: Błąd klienta — webhook nie zostanie ponowiony
  • 500-599: Błąd serwera — webhook zostanie ponowiony

Testowanie webhooków

Programowanie lokalne

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

ngrok http 3000

Podczas programowania użyj podanego adresu URL HTTPS jako punktu końcowego webhooka.

Testowanie webhooka

Możesz przetestować implementację webhooka, wysyłając żądanie transkrypcji i monitorując punkt końcowy:

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

Kolejne kroki

Strumieniowanie po stronie serwera

Transkrybuj audio w czasie rzeczywistym za pomocą streamingowego API opartego na WebSocket.

Dokumentacja API

Pełna dokumentacja Speech to Text API i parametry.