Referencia del SDK de JavaScript

Esta página documenta la API pública del SDK de JavaScript de Speech Engine (@elevenlabs/elevenlabs-js).

Obtener un recurso de Speech Engine

Recupera un SpeechEngineResource mediante su ID de motor. El objeto devuelto proporciona métodos para conectarse a un servidor HTTP existente, iniciar un servidor independiente o crear sesiones individuales.

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
const elevenlabs = new ElevenLabsClient();
const engine = await elevenlabs.speechEngine.get("seng_8k3m9xr4hjnfg983brhmhkd98n6");

SpeechEngineResource

Propiedades

attach

Conéctate a un servidor HTTP de Node.js existente y empieza a aceptar conexiones de Speech Engine en la ruta indicada. Úsalo si ya tienes un servidor HTTP (por ejemplo, Express, Fastify o un http.createServer() estándar) y quieres añadir Speech Engine junto a tus rutas existentes.

Gestiona automáticamente las actualizaciones de WebSocket, el enrutamiento de rutas y la verificación de solicitudes. Devuelve un SpeechEngineAttachment cuyo método close() deja de aceptar conexiones sin afectar al servidor HTTP.

const attachment = engine.attach(httpServer, "/ws", {
  debug: true,
  onTranscript(transcript, signal, session) {
    session.sendResponse(stream);
  },
});

Hay un atajo disponible directamente en el cliente que combina get() y attach() en una sola llamada:

await elevenlabs.speechEngine.attach("seng_8k3m9xr4hjnfg983brhmhkd98n6", httpServer, "/ws", {
  onTranscript(transcript, signal, session) {
    session.sendResponse(stream);
  },
});

verifyRequest

Verifica que una solicitud entrante proceda de la API de Speech Engine de ElevenLabs. Comprueba el encabezado X-Elevenlabs-Speech-Engine-Authorization para detectar un JWT válido firmado con el hash SHA-256 de tu clave de API.

Solo es necesario si gestionas tú mismo la actualización de WebSocket. Al usar attach() o SpeechEngineServer, la verificación se gestiona automáticamente.

const isValid = await engine.verifyRequest(req);

Devuelve: Promise<boolean> — true si la solicitud es válida.

createSession

Envuelve un WebSocket aceptado en un SpeechEngineSession. Úsalo para integraciones de servidor personalizadas o gestión manual de WebSocket.

const session = engine.createSession(ws, { debug: true });
session.on("user_transcript", (transcript, signal) => {
  /* ... */
});

Devuelve: SpeechEngineSession

SpeechEngineServer

Un servidor WebSocket independiente que acepta conexiones de Speech Engine sin necesitar un servidor HTTP existente. Úsalo si la única función de tu servidor es gestionar conexiones de Speech Engine.

Para integrarlo con un servidor HTTP existente (por ejemplo, Express o Fastify), usa engine.attach().

import { SpeechEngine } from "@elevenlabs/elevenlabs-js";
const server = new SpeechEngine.Server({
  port: 3001,
  debug: true,
  onTranscript(transcript, signal, session) {
    session.sendResponse(stream);
  },
});
server.start();

Opciones del constructor

start

Inicia el servidor WebSocket independiente en el puerto configurado. Verifica cada conexión entrante con la API de ElevenLabs mediante la clave de API configurada, salvo que se haya establecido disableAuth: true.

server.start();

stop

Detiene el servidor WebSocket y cierra todas las conexiones activas.

await server.stop();

handleConnection

Envuelve un WebSocket existente en un SpeechEngineSession con los callbacks del servidor conectados. Úsalo si gestionas tu propio servidor WebSocket y quieres envolver conexiones individuales.

const session = server.handleConnection(ws);

Devuelve: SpeechEngineSession

SpeechEngineSession

Envuelve una única conexión WebSocket. Cada conexión representa una conversación. La sesión emite eventos para las transcripciones y los cambios de ciclo de vida, y proporciona métodos para enviar respuestas de LLM.

Cuando llega una nueva transcripción, se activa la señal de cancelación del controlador de la transcripción anterior, lo que interrumpe cualquier llamada a LLM en curso.

Propiedades

on

Registra un controlador para un evento. Devuelve la sesión para poder encadenar llamadas.

session.on("user_transcript", (transcript, signal) => {
  /* ... */
});

off

Elimina un controlador registrado anteriormente.

session.off("user_transcript", listener);

once

Registra un controlador que se ejecuta una vez y después se elimina.

session.once("init", (conversationId) => {
  /* ... */
});

sendResponse

Envía una respuesta de LLM a la API de Speech Engine para sintetizarla mediante texto a voz. Debe llamarse dentro de un controlador onTranscript. Si se llama fuera de un controlador, emite una advertencia y termina sin enviar nada.

// String response
session.sendResponse("Hello, how can I help?");
// Streamed response (OpenAI, Anthropic, or Gemini)
const stream = await openai.responses.create(
  { model: "gpt-4o", input: messages, stream: true },
  { signal }
);
session.sendResponse(stream);

El SDK detecta y extrae automáticamente texto de los siguientes formatos de stream de LLM:

close

Cierra la sesión y la conexión WebSocket subyacente.

session.close();

SpeechEngineAttachment

Devuelto por engine.attach(). Controla el ciclo de vida del servidor WebSocket sin afectar al servidor HTTP al que se conectó.

close

Deja de aceptar conexiones nuevas, elimina el listener de actualización del servidor HTTP y cierra el servidor WebSocket subyacente.

await attachment.close();

Callbacks

El objeto de callbacks que se pasa a attach() o SpeechEngineServer. Todos los callbacks son opcionales.

El controlador onTranscript recibe un AbortSignal que se activa cuando el usuario interrumpe durante una respuesta.

Desactivar la autenticación

De forma predeterminada, tanto attach() como SpeechEngineServer verifican el encabezado X-Elevenlabs-Speech-Engine-Authorization en cada conexión entrante. Si tu servidor está detrás de una capa de infraestructura que ya restringe el tráfico entrante a ElevenLabs (normalmente una lista de IP permitidas limitada a los rangos de salida de ElevenLabs), puedes omitir la verificación de JWT pasando disableAuth: true:

// Standalone — no apiKey required when disableAuth is true
new SpeechEngine.Server({ port: 3001, disableAuth: true, onTranscript }).start();
// Or on attach
elevenlabs.speechEngine.attach("seng_8k3m9xr4hjnfg983brhmhkd98n6", httpServer, "/ws", {
  disableAuth: true,
  onTranscript,
});

Cuando la autenticación está desactivada, el servidor acepta cualquier cliente que pueda acceder a él y emite un console.warn al iniciarse.

Eventos

Si usas session.on() directamente en lugar de callbacks, estos son los nombres de los eventos y las firmas de sus controladores.

Hay constantes de nombres de eventos disponibles para un uso con seguridad de tipos:

import { SpeechEngine } from "@elevenlabs/elevenlabs-js";
session.on(SpeechEngine.USER_TRANSCRIPT, (transcript, signal) => {
  /* ... */
});

TranscriptMessage

Un único mensaje en el historial de la conversación. La transcripción completa se pasa a onTranscript en cada turno.

Protocolo de conexión

Como referencia, estos son los mensajes JSON intercambiados a través de la conexión WebSocket. El SDK gestiona la serialización y deserialización automáticamente.

Entrantes (API de ElevenLabs al servidor del desarrollador)

Salientes (servidor del desarrollador a la API de ElevenLabs)