Integración de la API Voz a Texto: Guía para desarrolladores

Una API Voz a Texto permite a desarrolladores integrar reconocimiento y transcripción de voz directamente en sus aplicaciones. Pero antes de conectar la API STT, primero tienes que tomar algunas decisiones de arquitectura.

¿Qué modo de transcripción vas a usar? ¿Cómo vas a gestionar archivos de audio largos? ¿Y cómo asegurar que los nombres de productos o nombres propios se escriban correctamente? Un poco de planificación aquí ayuda mucho a crear una integración escalable de API Voz a Texto en tus apps para desarrolladores.

Esta guía cubre todo lo que necesitas para una integración de la API Voz a Texto de ElevenLabs, con ejemplos de código claros que puedes pegar directamente en producción. Como referencia, ten a mano el inicio rápido de Voz a Texto de ElevenLabs y la guía de la API en otra ventana.

Resumen

• Hay dos modos de Voz a Texto en ElevenLabs: batch (para audio pregrabado) y tiempo real (para audio en directo vía WebSocket).
• Scribe v2 gestiona transcripción batch en más de 90 idiomas con diarización de hablantes, prompting de palabras clave, detección de entidades, marcas de tiempo por palabra y soporte multicanal.
• Scribe v2 en Tiempo Real gestiona streaming en directo con una latencia de unos 150 ms, entregando transcripciones parciales mientras hablas y transcripciones finales cuando termina un segmento de voz.
• Para archivos de más de 8 minutos, Scribe v2 divide y transcribe automáticamente en paralelo. Para trabajos largos, usa webhooks en vez de esperar la respuesta síncrona.
• El prompting de palabras clave orienta el modelo hacia términos concretos usando contexto; es más fiable que una lista de palabras clave para nombres de productos, jerga técnica o nombres propios poco comunes.

Integración de la API Voz a Texto: Batch vs. tiempo real

Toda integración de la API STT de ElevenLabs empieza con una decisión de arquitectura: batch o tiempo real. Ambos te dan acceso a un modelo STT potente en tu entorno de desarrollo, pero tu elección afecta desde las funciones disponibles hasta la latencia de extremo a extremo.

Así se comparan los dos modos:

• Por lotes (Scribe v2): Recibe un archivo de audio o vídeo completo, lo transcribe y devuelve la transcripción entera en una sola respuesta. Soporta el mayor conjunto de funciones: hasta 1.000 palabras clave, hasta 32 hablantes para diarización, detección de entidades, modo multicanal y webhooks para entrega asíncrona. Archivos de hasta 3 GB y 10 horas están soportados en modo estándar.
• Tiempo real (Scribe v2 Realtime): Recibe un stream de audio en directo por WebSocket y devuelve transcripciones parciales y finales a medida que llega el audio, con una latencia de unos 150 ms. Soporta hasta 50 palabras clave y marcas de tiempo por palabra, y es la mejor opción para asistentes de voz, subtítulos en directo o cualquier app donde el usuario habla y espera respuesta.

Vamos a ver las diferencias con más detalle.

Como regla rápida: usa batch cuando el audio está completo antes de empezar la transcripción y tiempo real cuando transcribes audio mientras se produce.

Cuándo elegir Scribe v2 o Scribe v2 Realtime

Batch y tiempo real cubren necesidades distintas, así que elegir mal al principio suele acabar en tener que rehacer trabajo después.

Para más claridad, así puedes ajustar el modelo a tu caso de uso:

• Scribe v2 es la mejor opción cuando el audio está completo antes de procesar, como grabaciones de reuniones, transcripción de podcasts, archivos multimedia o cualquier cosa que proceses offline. Soporta todas las funciones, incluyendo diarización, detección de entidades y hasta 1.000 palabras clave.
• Scribe v2 Realtime está pensado para audio en directo. Recibe un stream por WebSocket y devuelve transcripciones a medida que llega el audio, ideal para asistentes de voz o cualquier situación donde el usuario habla y tu app debe responder antes de que termine.

Otro factor a tener en cuenta es que la precisión varía según el idioma. Merece la pena revisar la tasa de error de transcripción antes de decidirte por una combinación de idiomas. Scribe v2 publica tasas de error por palabra (WER) para los más de 90 idiomas soportados.

Precisión excelente (≤5% WER) cubre los principales idiomas europeos, japonés, indonesio y vietnamita, entre otros. Alta precisión (5-10% WER) cubre hindi, bengalí, mandarín, coreano y georgiano, entre otros. Consulta el desglose por categorías en la documentación de soporte de idiomas para más detalles.

Configurar la API Voz a Texto de ElevenLabs

Tener un cliente funcional solo requiere dos pasos sencillos. Primero, instala el SDK. Segundo, guarda tus credenciales de forma segura.

Así puedes hacer ambos antes de enviar tu primera petición de transcripción.

Instala el SDK y guarda tu clave de API como un secreto gestionado usando un archivo .env o el gestor de secretos de tu plataforma. Nunca incluyas tu clave de API directamente en tu app.

Python

pip install elevenlabs
pip install python-dotenv

TypeScript

npm install @elevenlabs/elevenlabs-js

Crea un archivo .env:

ELEVENLABS_API_KEY=<your_api_key_here>

Inicializa el cliente:

Python

import os
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)

TypeScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

Tu primera transcripción batch con la API STT de ElevenLabs

Ahora que has inicializado el cliente, ya puedes enviar tu primer archivo.

La API batch recibe un archivo, lo transcribe y devuelve el resultado completo de forma síncrona. El ejemplo de abajo transcribe un archivo de audio remoto con diarización de hablantes y etiquetado de eventos de audio activados.

Python

# example.py
import os
from dotenv import load_dotenv
from io import BytesIO
import requests
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)

audio_url = (
    "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3"
)
response = requests.get(audio_url)
audio_data = BytesIO(response.content)

transcription = elevenlabs.speech_to_text.convert(
    file=audio_data,
    model_id="scribe_v2",          # Model to use
    tag_audio_events=True,          # Tag audio events like laughter, applause, etc.
    language_code="eng",            # Language of the audio file. If set to None, the model will detect the language automatically.
    diarize=True,                   # Whether to annotate who is speaking
)

print(transcription)

Ejecuta el código:

python example.py

El objeto de respuesta incluye el texto completo de la transcripción, entradas por palabra con marcas de tiempo e IDs de hablante, y eventos de audio detectados.

Cada entrada de palabra lleva un campo type con uno de estos tres valores:

• palabra: Para palabras transcritas en el audio.
• espaciado: Cualquier espacio entre palabras en idiomas que usan espacios. Este tipo no se aplica a varios idiomas, como japonés, cantonés o birmano.
• evento_audio: Etiqueta para cualquier sonido que no sea voz, como una risa o tos.

Así es la estructura de la respuesta:

{
  "language_code": "en",
  "language_probability": 1,
  "text": "With a soft and whispery American accent, I'm the ideal choice for creating ASMR content, meditative guides, or adding an intimate feel to your narrative projects.",
  "words": [
    {
      "text": "With",
      "start": 0.119,
      "end": 0.259,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 0.239,
      "end": 0.299,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "a",
      "start": 0.279,
      "end": 0.359,
      "type": "word",
      "speaker_id": "speaker_0"
    }
  ]
}

El campo language_probability indica el nivel de confianza del modelo en la detección de idioma, en una escala de 0,00 a 1,00.

Integración de la API STT en tiempo real

STT en tiempo real sigue un patrón algo distinto. En vez de una petición y una respuesta, abres una conexión WebSocket y lees las transcripciones a medida que llegan.

La API en tiempo real usa un WebSocket para recibir un stream de audio en directo y devolver transcripciones según llega el audio. Entrega dos tipos de transcripción:

• Transcripciones parciales: Resultados provisionales que se actualizan mientras el modelo procesa el audio entrante. Pueden cambiar.
• Transcripciones finales: Resultados definitivos de un segmento de voz completado. No cambian. También pueden incluir marcas de tiempo por palabra si activas la opción "incluir marcas de tiempo".

La implementación en el cliente usa un token de un solo uso en vez de tu clave de API directamente. Es una credencial temporal que caduca a los 15 minutos, generada en el servidor para que tu clave de API nunca se exponga en el navegador.

Paso 1: Genera un token de un solo uso (en el servidor)

// Node.js server
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

app.get("/scribe-token", yourAuthMiddleware, async (req, res) => {
  const token = await elevenlabs.tokens.singleUse.create("realtime_scribe");

  res.json(token);
});

Paso 2: Conecta y transcribe (en el cliente, React)

import { useScribe } from "@elevenlabs/react";

function MyComponent() {
  const scribe = useScribe({
    modelId: "scribe_v2_realtime",
    onPartialTranscript: (data) => {
      console.log("Partial:", data.text);
    },
    onCommittedTranscript: (data) => {
      console.log("Committed:", data.text);
    },
    onCommittedTranscriptWithTimestamps: (data) => {
      console.log("Committed with timestamps:", data.text);
      console.log("Timestamps:", data.words);
    },
  });

  const handleStart = async () => {
    // Fetch a single use token from the server
    const token = await fetchTokenFromServer();

    await scribe.connect({
      token,
      microphone: {
        echoCancellation: true,
        noiseSuppression: true,
      },
    });
  };

  return (
    <div>
      <button onClick={handleStart} disabled={scribe.isConnected}>
        Start Recording
      </button>
      <button onClick={scribe.disconnect} disabled={!scribe.isConnected}>
        Stop
      </button>

      {scribe.partialTranscript && <p>Live: {scribe.partialTranscript}</p>}

      <div>
        {scribe.committedTranscripts.map((t) => (
          <p key={t.id}>{t.text}</p>
        ))}
      </div>
    </div>
  );
}

El hook useScribe gestiona el ciclo de vida de la conexión WebSocket, el acceso al micrófono y el estado de la transcripción. partialTranscript contiene el texto en curso; committedTranscripts es el array creciente de segmentos finalizados.

Para streaming en el servidor (transcribir audio desde una URL o stream de archivo en vez de micrófono), consulta la guía de streaming en el servidor.

Concurrencia y escalado de archivos largos

Los archivos largos requieren un modelo de escalado distinto al de la mayoría de APIs. Es importante entenderlo antes de construir sobre ello.

La concurrencia para transcripción batch funciona de forma diferente a la mayoría de APIs. En vez de limitar cuántas peticiones puedes enviar a la vez, Scribe v2 gestiona archivos largos paralelizándolos automáticamente por dentro.

Los archivos de más de 8 minutos se dividen en segmentos y se transcriben en paralelo. El número de segmentos concurrentes se calcula así:

Concurrency = min(4, round_up(audio_duration_secs / 480))

Concretamente:

• Un archivo de 15 minutos usa concurrencia de 2
• Un archivo de 120 minutos usa concurrencia de 4 (el máximo)

Archivos de hasta 10 horas y 3 GB están soportados en modo estándar. Nota: el modo multicanal tiene un límite de duración menor; consulta la sección de transcripción multicanal más abajo.

En cuanto a formatos soportados, la API STT acepta los formatos de audio y vídeo más comunes:

• Audio: AAC, AIFF, OGG, MP3, OPUS, WAV, FLAC, M4A, WebM.
• Vídeo: MP4, AVI, MKV, MOV, WMV, FLV, WebM, MPEG, 3GPP.

Puedes enviar un archivo de vídeo directamente y recibir la transcripción de su pista de audio sin preprocesar.

Prompting de palabras clave

Los modelos genéricos suelen transcribir mal nombres de marca y jerga técnica. El prompting de palabras clave soluciona esto.

El prompting de palabras clave orienta el modelo hacia palabras o frases concretas al transcribir. Es la herramienta adecuada cuando tu audio contiene nombres de productos, términos técnicos o nombres propios con ortografía poco común.

Una ventaja del prompting de palabras clave es que usa contexto, lo que lo hace más fiable que una simple lista de palabras. Si añades "ElevenLabs" como palabra clave, el modelo la transcribirá correctamente cuando el hablante diga el nombre de la empresa. Sin esto, puede que el modelo siga transcribiendo mal frases como "he trabajado en eleven labs un año".

Sin prompting de palabras clave:

I work at eleven labs.

Con keyterms=["ElevenLabs"]:

I work at ElevenLabs.

Batch soporta hasta 1.000 palabras clave (50 caracteres cada una). Tiempo real soporta hasta 50 palabras clave (20 caracteres cada una).

Transcripción batch con palabras clave

Python

import os
from dotenv import load_dotenv
from io import BytesIO
import requests
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)

audio_url = (
    "https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/stt-keyterm-prompting.mp3"
)
response = requests.get(audio_url)
audio_data = BytesIO(response.content)

transcription = elevenlabs.speech_to_text.convert(
    file=audio_data,
    model_id="scribe_v2",
    # Keyterms to prompt the model with.
    # Up to 1,000 keyterms can be provided, with a maximum length of 50 characters each
    keyterms=["ElevenLabs"],
)

print(transcription)

Streaming en tiempo real con palabras clave

Pasa las palabras clave al conectar con el WebSocket en tiempo real:

Python

connection = await elevenlabs.speech_to_text.realtime.connect(RealtimeUrlOptions(
    model_id="scribe_v2_realtime",
    keyterms=["ElevenLabs"],
))

O pásalas como parámetros de consulta directamente en la URL del WebSocket:

wss://api.elevenlabs.io/v1/speech-to-text/realtime?model_id=scribe_v2_realtime&keyterms=ElevenLabs&keyterms=AnotherTerm

El prompting de palabras clave tiene un coste adicional. Consulta la página de precios de la API para más detalles.

Funciones avanzadas

Aunque los pasos anteriores cubren el flujo principal de transcripción con la API STT, hay varias funciones que enriquecen el resultado final. Aquí tienes algunas funciones avanzadas que puedes usar en tu API Voz a Texto:

• Diarización de hablantes para identificar quién habla
• Modo no-verbatim para limpiar transcripciones
• Detección de entidades para marcar datos sensibles
• Transcripción multicanal para separar canales de audio

Vamos a verlas con más detalle.

Diarización de hablantes

Activa diarize=True en tu petición batch para anotar quién está hablando. Scribe v2 soporta hasta 32 hablantes. Cada palabra en la respuesta incluye un campo speaker_id (por ejemplo, speaker_0, speaker_1) que puedes usar para separar segmentos de transcripción por hablante.

La diarización es útil para transcribir reuniones, procesar entrevistas o cualquier grabación con varios hablantes donde importa saber quién dice qué.

Modo no-verbatim

Cuando no_verbatim=True, el modelo elimina muletillas, repeticiones y disfluencias de la transcripción. "Eh, E-entonces deberíamos, eh, ir con la opción A" se convierte en "Deberíamos ir con la opción A."

Esto produce resultados más limpios para subtítulos, resúmenes o cualquier caso donde la legibilidad sea más importante que capturar cada sonido. Está disponible tanto para batch (scribe_v2) como para tiempo real (scribe_v2_realtime).

Detección y ocultación de entidades

Scribe v2 puede detectar y etiquetar entidades en la transcripción, con marcas de tiempo exactas para cada entidad detectada. Las categorías incluyen PII (nombres, números de tarjeta, DNIs), PHI (condiciones médicas) y PCI (información de pago), entre otras. Para la lista completa de tipos de entidad soportados, consulta la documentación de detección de entidades.

Esto es especialmente útil para casos de cumplimiento normativo, permitiéndote identificar y ocultar automáticamente información sensible antes de guardar o mostrar la transcripción.

La detección de entidades tiene un coste adicional de $0,070 (por hora) sobre el coste base de transcripción. Consulta la página de precios de la API para más detalles.

Transcripción multicanal

Cuando usas use_multi_channel=True, cada canal de audio se transcribe de forma independiente y se le asigna un ID de hablante según el número de canal. Se soportan hasta 5 canales. La duración máxima de archivo en modo multicanal es de 1 hora.

El modo multicanal es útil cuando tienes pistas de audio separadas por hablante, por ejemplo, una grabación de llamada telefónica donde cada participante está en su propio canal. Esto da una atribución de hablante más precisa que la diarización en un archivo mono mezclado.

Entrega asíncrona con webhooks

Consultar el resultado funciona bien con poco volumen, pero no escala cuando trabajas con archivos largos o pipelines de alto rendimiento. Los webhooks solucionan esto enviándote el resultado directamente.

Para archivos largos o pipelines de transcripción de alto volumen, esperar la respuesta síncrona no siempre es práctico. Los webhooks te permiten enviar la petición y recibir el resultado en tu ruta de API cuando termine el procesamiento, sin hacer polling.

Configurar un webhook

En el panel de ElevenLabs, ve a Desarrolladores > Webhooks, haz clic en Crear webhook y configura:

• Nombre: Escribe un nombre descriptivo y fácil de recordar para tu webhook.
• URL de callback: Añade una ruta de API HTTPS accesible públicamente al webhook.
• Método de autenticación del webhook: Elige HMAC u OAuth (opcional pero muy recomendable por seguridad).
• Eventos: Selecciona Transcription completed entre las opciones.

Enviar una transcripción con entrega por webhook

Python

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

Cuando webhook=True, la petición responde antes sin la transcripción. La transcripción final se entrega a tu ruta de API como una petición POST cuando termina el procesamiento.

Implementar tu ruta de API para el webhook

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

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

Estructura del payload del webhook

Tu ruta de API recibe un POST con esta estructura:

{
  "type": "speech_to_text_transcription",
  "data": {
    "request_id": "some-request-id-123",
    "webhook_metadata": {},
    "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"
        }
      ]
    }
  }
}

Buenas prácticas de seguridad para webhooks

Al trabajar con webhooks, hay varias medidas de seguridad que puedes tomar para asegurar que los eventos se entregan y procesan correctamente.

• Verifica las firmas del webhook: Verifica siempre las firmas usando elevenlabs.webhooks.constructEvent() para confirmar que vienen de ElevenLabs.
• Usa rutas de API HTTPS: Las URLs de webhook deben usar HTTPS para proteger los datos en tránsito.
• Devuelve el código de estado HTTP adecuado: Devuelve 200-299 si el procesamiento es correcto, 400-499 para errores del cliente (no se reintentan) y 500-599 para errores del servidor (se reintentan).
• Usa una herramienta de túnel para desarrollo local: Para desarrollo local, usa una herramienta como ngrok para exponer tu servidor local con una URL HTTPS pública.

Con estas estrategias, podrás usar webhooks con tranquilidad.

Puntos clave para tu integración de la API Voz a Texto

Una integración de la API Voz a Texto en producción depende de unas pocas decisiones.

Si aciertas en esto, todo lo demás fluye:

• Elige el modo según el caso de uso: Usa batch (scribe_v2) cuando el audio está completo antes de procesar. Usa tiempo real (scribe_v2_realtime) cuando necesitas transcribir mientras se produce el audio, como para agentes, asistentes de voz o subtítulos en directo.
• Usa palabras clave para precisión en vocabulario específico: Pasa nombres de productos, términos técnicos o nombres propios poco comunes como palabras clave. El modelo usa contexto para aplicarlas correctamente sin sobreactivar.
• Deja que la API gestione archivos largos: Los archivos de más de 8 minutos se paralelizan automáticamente, así que no necesitas dividirlos tú. Archivos de hasta 10 horas y 3 GB están soportados en modo estándar.
• Usa webhooks para pipelines asíncronos: Para trabajos largos o procesamiento de alto volumen, webhook=True te permite enviar y seguir. Verifica la firma en cada payload de webhook recibido.
• Activa el modo no-verbatim para resultados limpios: Si tu caso de uso son subtítulos, resúmenes o procesamiento NLP posterior, no_verbatim=True elimina muletillas y disfluencias automáticamente.
• Usa modo multicanal para pistas de audio separadas: Si tu grabación tiene un canal por hablante (grabaciones de centro de llamadas, entrevistas), la transcripción multicanal da una atribución de hablante más precisa que la diarización en un archivo mezclado. Ten en cuenta el límite de 1 hora en este modo.

Si quieres aún más información, explora la referencia completa de la API como punto de partida.

Crea tu integración Voz a Texto con ElevenAPI

Después de leer esta guía, tienes todos los patrones que necesitas para una integración de la API Voz a Texto en producción. Tanto en batch como en tiempo real, y con funciones avanzadas como prompting de palabras clave y entrega asíncrona, estarás listo para lanzar tu app con STT integrado.

Empieza aprendiendo más sobre la API Voz a Texto o regístrate para hacer tu primera llamada con ElevenAPI hoy mismo.

Preguntas frecuentes sobre la integración de la API STT