Hoppa till navigering
InstruktionsguiderTal till textBatch

Asynkron Speech to Text

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

Instruktionsguide · Förutsätter att du har slutfört snabbstarten för Speech to Text .

Översikt

Med webhooks kan du ta emot automatiska aviseringar när dina Speech to Text-transkriberingsuppgifter är klara, så att du slipper fråga API:t kontinuerligt efter statusuppdateringar. Detta ä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 transkriptionstexten, språkidentifiering och eventuell 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-instrumentpanelen. Klicka på Skapa webhook eller redigera en befintlig webhook.

Dialogrutan Skapa webhook med Transcription completed valt
Välj Transcription completed när du skapar eller redigerar webhooken

Konfigurera webhooken med:

  • Namn: Ett beskrivande namn för din webhook
  • Callback-URL: Din publikt tillgängliga HTTPS-slutpunkt
  • Webhook-autentiseringsmetod: Antingen HMAC eller OAuth. Det är upp till klienten att implementera verifieringsmekanismen. ElevenLabs skickar headers som möjliggör verifiering, men vi kräver den inte.
  • Händelser: 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 med värdet 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_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-data

När en transkribering är klar tar din webhook-slutpunkt emot en POST-begäran med transkriberings- och webhook-data:

{
  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 referensen för Speech-to-text API för information om svarstrukturens detaljer.

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

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

Säkerhetsaspekter

Signaturverifiering

Verifiera alltid webhook-signaturer för att säkerställa att begärningarna 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 lämpliga HTTP-statuskoder:

  • 200-299: Lyckades – webhooken bearbetades
  • 400-499: Klientfel – webhooken försöks inte igen
  • 500-599: Serverfel – webhooken försöks igen

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 din 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

Streaming på serversidan

Transkribera ljud i realtid med det WebSocket-baserade streaming-API:t.

API-referens

Fullständig API-referens och parametrar för Speech to Text.