Voz a Texto asíncrona | ElevenLabs Documentation

Guía práctica · Da por hecho que has completado la guía de inicio rápido de Voz a Texto .

Resumen

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 de larga duración o cuando procesas 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.

Uso de webhooks

Esta guía da por hecho que has configurado tu clave de API y SDK. Completa primero la guía de inicio rápido si aún no lo has hecho.

Crear o editar un webhook

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

Diálogo de creación de webhook con Transcription completed seleccionado — Selecciona Transcription completed al crear o editar el webhook

Configura el webhook con lo siguiente:

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 cabeceras que permiten verificarlo, pero no lo imponemos.
Eventos: selecciona Transcription completed.

Hacer llamadas a la API con el parámetro de 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.

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.

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

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 velocidad

Implementa una limitación de velocidad 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 de error

Devuelve códigos de estado HTTP adecuados:

200-299: Éxito: el webhook se ha procesado correctamente
400-499: Error del cliente: no se volverá a intentar el webhook
500-599: Error del servidor: se volverá a intentar el webhook

Probar webhooks

Desarrollo local

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

ngrok http 3000

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

Prueba de webhooks

Puedes probar tu implementación de 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

Streaming del lado del servidor

Transcribe audio en tiempo real con la API de streaming basada en WebSocket.

Referencia de la API

Referencia y parámetros completos de la API de Voz a Texto.