Speech to Text asincrono

Panoramica

I webhook ti permettono di ricevere notifiche automatiche quando le attività di trascrizione di Speech to Text sono completate, eliminando la necessità di interrogare continuamente l’API per gli aggiornamenti di stato. Sono particolarmente utili per le attività di trascrizione di lunga durata o quando elabori grandi volumi di file audio.

Quando una trascrizione è completata, ElevenLabs invia una richiesta POST all’URL webhook specificato con i risultati della trascrizione, inclusi il testo trascritto, il rilevamento della lingua ed eventuali metadati.

Uso dei webhook

1

Crea o modifica un webhook

Nella dashboard di ElevenLabs, vai a Sviluppatori > Webhook. Fai clic su Crea webhook oppure modifica un webhook esistente.

Configura il webhook con:

• Nome: un nome descrittivo per il webhook
• URL callback: l’endpoint HTTPS accessibile pubblicamente
• Metodo di autenticazione del webhook: HMAC oppure OAuth. Spetta al client implementare il meccanismo di verifica. ElevenLabs invia header che consentono la verifica, ma non la imponiamo.
• Eventi: seleziona Trascrizione completata.

2

Effettua chiamate API con il parametro webhook abilitato

Quando effettui chiamate API Speech to Text, includi il parametro webhook impostato su true per abilitare le notifiche webhook per quella specifica richiesta.

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

Payload del webhook

Quando una trascrizione è completata, l’endpoint webhook riceverà una richiesta POST con i dati della trascrizione e del webhook:

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

Consulta il riferimento dell’API Speech to Text per conoscere i dettagli della struttura della risposta.

Se la richiesta includeva un’istruzione transcript_edit, l’oggetto transcription contiene anche un campo edited_transcript con il testo modificato.

Se la trascrizione non riesce, l’endpoint riceve invece un evento webhook_error. Non contiene alcun oggetto data: include un request_id di primo livello (lo stesso ID restituito quando la richiesta è stata accettata), un error_message e il webhook_metadata della richiesta.

Implementazione dell’endpoint webhook

Ecco un esempio di come implementare un endpoint webhook per gestire le notifiche in arrivo:

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

Considerazioni sulla sicurezza

Verifica della firma

Verifica sempre le firme dei webhook per assicurarti che le richieste provengano da ElevenLabs.

Requisito HTTPS

Gli URL webhook devono usare HTTPS per garantire la trasmissione sicura dei dati di trascrizione.

Limitazione della frequenza

Implementa la limitazione della frequenza sull’endpoint webhook per prevenire abusi:

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

Risposte agli errori

Restituisci un codice di stato 2xx per confermare la ricezione del webhook.

Per impostazione predefinita, i webhook di trascrizione Speech to Text vengono inviati una sola volta. Ogni risposta diversa da 2xx viene conteggiata come invio non riuscito e gli errori ripetuti disabilitano automaticamente il webhook.

Se attivi i tentativi per il webhook, gli invii non riusciti (5xx, 408, 429 o errori di connessione) vengono ritentati fino ad altre 5 volte, circa 30 secondi, 2 minuti, 8 minuti, 30 minuti e 30 minuti dopo il tentativo precedente. Le altre risposte 4xx non vengono ritentate. Ogni tentativo per lo stesso evento include lo stesso header ElevenLabs-Webhook-Delivery-Id, quindi il tuo handler può ignorare i duplicati.

Le richieste effettuate con enable_logging impostato su false (modalità di conservazione zero) ricevono fino a 2 tentativi rapidi, 5 secondi e 30 secondi dopo il tentativo precedente, quando i tentativi sono attivati. La trascrizione non viene mai archiviata.

Se un invio continua a non riuscire, recupera il risultato con Ottieni trascrizione usando il transcription_id restituito quando la richiesta è stata accettata. Le trascrizioni non vengono archiviate per le richieste effettuate con enable_logging impostato su false.

Test dei webhook

Sviluppo locale

Per i test locali, usa strumenti come ngrok per esporre il server locale:

ngrok http 3000

Durante lo sviluppo, usa l’URL HTTPS fornito come endpoint webhook.

Test del webhook

Puoi testare l’implementazione del webhook effettuando una richiesta di trascrizione e monitorando l’endpoint:

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

Passaggi successivi