Vai alla navigazione

Speech to Text asincrono

Questa guida mostra come usare i webhook per ricevere notifiche asincrone al completamento delle attività di trascrizione.

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

Panoramica

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

Quando una trascrizione è completata, ElevenLabs invierà una richiesta POST all’URL webhook specificato con i risultati della trascrizione, inclusi il testo trascritto, il rilevamento della lingua ed 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 ancora fatto.

1

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 selezionato
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 del webhook: HMAC o 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 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_v3",
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 ha un 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.

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();
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 utilizzare 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 in caso di errore

Restituisci un codice di stato 2xx per confermare il webhook.

Per impostazione predefinita, i webhook di trascrizione Speech to Text vengono inviati una sola volta. Ogni risposta non 2xx conta come consegna non riuscita e gli errori ripetuti disabilitano automaticamente il webhook.

Se attivi i tentativi per il webhook, le consegne non riuscite (5xx, 408, 429 o errori di connessione) vengono ritentate fino a 5 volte, approssimativamente 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 memorizzata.

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

Testare i webhook

Sviluppo locale

Per i test locali, usa strumenti come ngrok per esporre il tuo 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_v3",
webhook: true,
});
console.log("Test transcription started:", result.requestId);
}

Passaggi successivi