Asynkron Speech to Text

Översikt

Med webhooks kan du få automatiska aviseringar när dina transkriberingsuppgifter i Speech to Text är klara, så att du slipper kontinuerligt fråga API:t efter statusuppdateringar. Det är särskilt användbart för långvariga transkriberingsjobb eller när du bearbetar stora mängder ljudfiler.

När en transkribering är klar skickar ElevenLabs en POST-begäran till den webhook-URL du har angett med transkriberingsresultaten, inklusive transkriptionstexten, språkidentifiering och metadata.

Använda webhooks

1

Skapa eller redigera en webhook

Gå till Developers > Webhooks i ElevenLabs-kontrollpanelen. Klicka på Create webhook eller redigera en befintlig webhook.

Konfigurera webhooken med:

• Name: Ett beskrivande namn för din webhook
• Callback URL: Din offentligt tillgängliga HTTPS-slutpunkt
• Webhook Auth Method: Antingen HMAC eller OAuth. Det är upp till klienten att implementera verifieringsmekanismen. ElevenLabs skickar headers som möjliggör verifiering, men vi kräver inte det.
• Events: Välj Transcription completed.

2

Gör API-anrop med webhook-parametern aktiverad

När du gör API-anrop för tal-till-text ska du inkludera parametern webhook satt till true för att aktivera webhook-aviseringar för just den begäran.

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

När en transkribering är klar får din webhook-slutpunkt en POST-begäran med transkriberings- och webhookdata:

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

Se Speech-to-text API-referensen för mer information om svarsstrukturens detaljer.

Om begäran innehöll en transcript_edit-instruktion innehåller objektet transcription även fältet edited_transcript med den redigerade texten.

Om transkriberingen misslyckas får din slutpunkt i stället händelsen webhook_error. Den har inget data-objekt: den innehåller ett request_id på toppnivå (samma id som returnerades när begäran godkändes), ett error_message och begärans webhook_metadata.

Implementera din webhook-slutpunkt

Här är ett exempel på hur du implementerar en webhook-slutpunkt för att hantera inkommande aviseringar:

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

Säkerhetsaspekter

Signaturverifiering

Verifiera alltid webhook-signaturer för att säkerställa att begäranden kommer från ElevenLabs.

HTTPS-krav

Webhook-URL:er måste använda HTTPS för att säkerställa säker överföring av transkriberingsdata.

Hastighetsbegränsning

Implementera hastighetsbegränsning på din webhook-slutpunkt för att förhindra missbruk:

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

Felrespons

Returnera en 2xx-statuskod för att bekräfta webhooken.

Som standard levereras Speech to Text-transkriberingswebhooks en gång. Varje svar som inte är 2xx räknas som en misslyckad leverans, och upprepade fel inaktiverar webhooken automatiskt.

Om du aktiverar återförsök för webhooken försöker systemet igen med misslyckade leveranser (5xx, 408, 429 eller anslutningsfel) upp till 5 gånger till, ungefär 30 sekunder, 2 minuter, 8 minuter, 30 minuter och 30 minuter efter föregående försök. Andra 4xx-svar försöker systemet inte igen med. Varje försök för samma händelse har samma header ElevenLabs-Webhook-Delivery-Id, så din hanterare kan ignorera dubbletter.

Begäranden där enable_logging är satt till false (läge utan lagring) får upp till 2 snabba återförsök, 5 sekunder och 30 sekunder efter föregående försök, när återförsök är aktiverade. Transkriptionen lagras aldrig.

Om en leverans fortfarande misslyckas hämtar du resultatet med Get transcript och använder transcription_id som returnerades när begäran godkändes. Transkriptioner lagras inte för begäranden där enable_logging är satt till false.

Testa webhooks

Lokal utveckling

För lokal testning kan du använda verktyg som ngrok för att exponera din lokala server:

ngrok http 3000

Använd den angivna HTTPS-URL:en som webhook-slutpunkt under utvecklingen.

Webhook-testning

Du kan testa din webhook-implementering genom att göra en transkriberingsbegäran och övervaka din slutpunkt:

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ästa steg