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.
Skapa eller redigera en webhook
Gå till Utvecklare > Webhooks i ElevenLabs-kontrollpanelen. Klicka på Skapa webhook eller redigera en befintlig webhook.

Konfigurera webhooken med:
- Namn: Ett beskrivande namn för din webhook
- Callback-URL: Din offentligt tillgängliga HTTPS-slutpunkt
- Webhook-autentiseringsmetod: Antingen
HMACellerOAuth. 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.
Webhook-payload
När en transkribering är klar tar din webhook-slutpunkt emot en POST-begäran med transkriberings- och webhookdata:
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:
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:
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:
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: