Voz a Texto asíncrona

Descripción general

Los webhooks te permiten recibir notificaciones automáticas cuando se completan tus tareas de transcripción de Voz a Texto, lo que elimina la necesidad de consultar continuamente la API para obtener actualizaciones de estado. Esto resulta especialmente útil para trabajos de transcripción largos o al procesar grandes volúmenes de archivos de audio.

Cuando se completa una transcripción, ElevenLabs enviará una solicitud POST a la URL de webhook que hayas especificado con los resultados de la transcripción, incluido el texto transcrito, la detección de idioma y cualquier metadato.

Usar webhooks

1

Crear o editar un webhook

En el panel de ElevenLabs, ve a Desarrolladores > Webhooks. Haz clic en Crear webhook o edita uno existente.

Configura el webhook con:

• Nombre: un nombre descriptivo para tu webhook
• URL de callback: tu ruta HTTPS de acceso público
• Método de autenticación del webhook: HMAC u OAuth. El cliente debe implementar el mecanismo de verificación. ElevenLabs envía encabezados que permiten realizar la verificación, pero no la exigimos.
• Eventos: selecciona Transcripción completada.

2

Hacer llamadas a la API con el parámetro webhook activado

Al hacer llamadas a la API de Voz a Texto, incluye el parámetro webhook con el valor true para activar las notificaciones de webhook para esa solicitud concreta.

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

Carga útil del webhook

Cuando se completa una transcripción, tu ruta de webhook recibirá una solicitud POST con los datos de la transcripción y 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 la referencia de la API de Voz a Texto para conocer los detalles de la estructura de la respuesta.

Si la solicitud incluía una instrucción transcript_edit, el objeto transcription también contiene un campo edited_transcript con el texto editado.

Si la transcripción falla, tu ruta recibe un evento webhook_error en su lugar. No tiene un objeto data: incluye un request_id de nivel superior (el mismo id devuelto cuando se aceptó la solicitud), un error_message y los webhook_metadata de la solicitud.

Implementar tu ruta de webhook

Aquí tienes un ejemplo de cómo implementar una ruta de webhook para gestionar las notificaciones entrantes:

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

Consideraciones de seguridad

Verificación de firma

Verifica siempre las firmas de los webhooks para asegurarte de que las solicitudes proceden de ElevenLabs.

Requisito de HTTPS

Las URL de webhook deben usar HTTPS para garantizar la transmisión segura de los datos de transcripción.

Limitación de frecuencia

Implementa una limitación de frecuencia en tu ruta de webhook para evitar abusos:

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

Respuestas ante fallos

Devuelve un código de estado 2xx para confirmar la recepción del webhook.

De forma predeterminada, los webhooks de transcripción de Voz a Texto se entregan una sola vez. Cada respuesta que no sea 2xx cuenta como una entrega fallida, y los fallos repetidos desactivan automáticamente el webhook.

Si activas los reintentos para el webhook, las entregas fallidas (5xx, 408, 429 o errores de conexión) se reintentan hasta 5 veces más, aproximadamente 30 segundos, 2 minutos, 8 minutos, 30 minutos y 30 minutos después del intento anterior. No se reintentan otras respuestas 4xx. Cada intento para el mismo evento incluye el mismo encabezado ElevenLabs-Webhook-Delivery-Id, por lo que tu controlador puede ignorar los duplicados.

Las solicitudes realizadas con enable_logging establecido en false (modo de retención cero) reciben hasta 2 reintentos rápidos, 5 segundos y 30 segundos después del intento anterior, cuando los reintentos están activados. La transcripción nunca se almacena.

Si una entrega sigue fallando, obtén el resultado con Obtener transcripción usando el transcription_id devuelto cuando se aceptó la solicitud. Las transcripciones no se almacenan para las solicitudes realizadas con enable_logging establecido en false.

Probar webhooks

Desarrollo local

Para realizar pruebas locales, usa herramientas como ngrok para exponer tu servidor local:

ngrok http 3000

Usa la URL HTTPS proporcionada como ruta de tu webhook durante el desarrollo.

Pruebas de webhooks

Puedes probar la implementación de tu webhook haciendo una solicitud de transcripción y supervisando tu ruta:

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

Próximos pasos