Speech to Text asincrono | ElevenLabs Documentation

Guida pratica · Presuppone che tu abbia completato la guida rapida di Speech to Text .

Panoramica

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

Quando una trascrizione è completata, ElevenLabs invierà una richiesta POST all’URL del webhook specificato con i risultati della trascrizione, inclusi il testo trascritto, il rilevamento della lingua e gli eventuali metadati.

Utilizzare i webhook

Questa guida presuppone che tu abbia configurato la chiave API e l’SDK. Completa prima la guida rapida, se non l’hai già fatto.

Crea o modifica un webhook

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

Finestra di dialogo Crea webhook con Trascrizione completata selezionata — Seleziona Trascrizione completata durante la creazione o la modifica del webhook

Configura il webhook con:

Nome: un nome descrittivo per il webhook
URL di callback: il tuo endpoint HTTPS accessibile pubblicamente
Metodo di autenticazione 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.

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 richiesta specifica.

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, il tuo 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.

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

Considerazioni sulla sicurezza

Verifica della firma

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

Requisito HTTPS

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

Limitazione della frequenza

Implementa una limitazione della frequenza sul tuo 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 in caso di errore

Restituisci codici di stato HTTP appropriati:

200-299: successo - webhook elaborato correttamente
400-499: errore del client - il webhook non verrà ritentato
500-599: errore del server - il webhook verrà ritentato

Testare i webhook

Sviluppo locale

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

ngrok http 3000

Durante lo sviluppo, utilizza 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

Streaming lato server

Trascrivi l’audio in tempo reale usando l’API di streaming basata su WebSocket.

Riferimento API

Riferimento completo e parametri dell’API Speech to Text.