Hoppa till navigering

Asynkron Speech to Text

Den här guiden visar hur du använder webhooks för att få asynkrona aviseringar när transkriberingsuppgifter är klara.

Guide · Förutsätter att du har slutfört snabbstarten för 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 fråga API:et kontinuerligt om 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 angivna webhook-URL:en med transkriberingsresultaten, inklusive transkriptionstext, språkidentifiering och metadata.

Använda webhooks

Den här guiden förutsätter att du har konfigurerat din API-nyckel och SDK. Slutför snabbstarten först om du inte redan har gjort det.

1

Skapa eller redigera en webhook

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

Dialogrutan Skapa webhook med Transkribering klar vald
Välj Transkribering klar när du skapar eller redigerar webhooken

Konfigurera webhooken med:

  • Namn: Ett beskrivande namn för din webhook
  • Callback-URL: Din offentligt tillgängliga HTTPS-slutpunkt
  • Webhook-autentiseringsmetod: Antingen HMAC eller OAuth. Det är upp till klienten att implementera verifieringsmekanismen. ElevenLabs skickar rubriker som möjliggör verifiering, men vi framtvingar den inte.
  • Händelser: Välj Transkribering klar.
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 inställd på true för att aktivera webhook-aviseringar för just den begäran.

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

När en transkribering är klar tar din webhook-slutpunkt emot 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 API-referensen för tal till text för mer information om svarsstrukturen.

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

Om transkriberingen misslyckas tar din slutpunkt i stället emot en webhook_error-händelse. 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 kom 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);

Svar vid fel

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

Som standard levereras webhooks för Speech to Text-transkribering 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 görs upp till fem ytterligare försök vid misslyckade leveranser (5xx, 408, 429 eller anslutningsfel), 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öks inte igen. Varje försök för samma händelse har samma ElevenLabs-Webhook-Delivery-Id-rubrik, så din hanterare kan ignorera dubbletter.

Begäranden med enable_logging inställt på false (läge utan lagring) får upp till två 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 Hämta transkription med transcription_id som returnerades när begäran godkändes. Transkriptioner lagras inte för begäranden där enable_logging är inställt på 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_v3",
webhook: true,
});
console.log("Test transcription started:", result.requestId);
}

Nästa steg