> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 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.

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

const elevenlabs = new ElevenLabsClient();
const engine = await elevenlabs.speechEngine.get("seng_8k3m9xr4hjnfg983brhmhkd98n6");
```

## SpeechEngineResource

### Propiedades

| Propiedad  | Tipo     | Descripción             |
| ---------- | -------- | ----------------------- |
| `engineId` | `string` | El ID del motor de voz. |

### 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.

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

| Parámetro    | Tipo                    | Descripción                                                   |
| ------------ | ----------------------- | ------------------------------------------------------------- |
| `httpServer` | `http.Server`           | El servidor HTTP de Node.js al que conectarse.                |
| `path`       | `string`                | Ruta de URL en la que gestionar actualizaciones de WebSocket. |
| `handler`    | `SpeechEngineCallbacks` | Objeto de callbacks (consulta [Callbacks](#callbacks)).       |

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

```typescript
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.

```typescript
const isValid = await engine.verifyRequest(req);
```

| Parámetro | Tipo                                                           | Descripción                        |
| --------- | -------------------------------------------------------------- | ---------------------------------- |
| `req`     | `{ headers: Record<string, string \| string[] \| undefined> }` | Objeto de solicitud HTTP entrante. |

**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.

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

| Parámetro       | Tipo      | Predeterminado | Descripción                       |
| --------------- | --------- | -------------- | --------------------------------- |
| `ws`            | WebSocket |                | Una conexión WebSocket aceptada.  |
| `options.debug` | `boolean` | `false`        | Activa el registro de depuración. |

**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()`](#attach).

```typescript
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

| Parámetro  | Tipo                    | Predeterminado | Descripción                                                                                                                                                                |
| ---------- | ----------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `port`     | `number`                | `3001`         | Puerto que se va a escuchar.                                                                                                                                               |
| `apiKey`   | `string`                |                | Clave de API de ElevenLabs para verificar conexiones. Si no se indica, se usa la variable de entorno `ELEVENLABS_API_KEY`. No es necesaria cuando `disableAuth` es `true`. |
| `engineId` | `string`                |                | El ID del motor de voz. Se completa automáticamente al crearse mediante el recurso.                                                                                        |
| ...        | `SpeechEngineCallbacks` |                | Todas las opciones de callback (`onInit`, `onTranscript`, `onClose`, `onDisconnect`, `onError`, `debug`, `disableAuth`). Consulta [Callbacks](#callbacks).                 |

### 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`.

```typescript
server.start();
```

### stop

Detiene el servidor WebSocket y cierra todas las conexiones activas.

```typescript
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.

```typescript
const session = server.handleConnection(ws);
```

| Parámetro | Tipo        | Descripción                      |
| --------- | ----------- | -------------------------------- |
| `ws`      | `WebSocket` | Una conexión WebSocket aceptada. |

**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

| Propiedad        | Tipo      | Descripción                                                              |
| ---------------- | --------- | ------------------------------------------------------------------------ |
| `conversationId` | `string`  | El ID de conversación asignado por la API. Disponible después de `init`. |
| `isOpen`         | `boolean` | Indica si la sesión sigue abierta.                                       |

### on

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

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

### off

Elimina un controlador registrado anteriormente.

```typescript
session.off("user_transcript", listener);
```

### once

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

```typescript
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.

```typescript
// 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);
```

| Parámetro  | Tipo                                 | Descripción                                                                                    |
| ---------- | ------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `response` | `string` \| `AsyncIterable<unknown>` | Una cadena completa o un iterable asíncrono de fragmentos de texto o eventos de stream de LLM. |

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

| Proveedor                  | Formato de evento                                                              |
| -------------------------- | ------------------------------------------------------------------------------ |
| API Responses de OpenAI    | `{ type: "response.output_text.delta", delta: "text" }`                        |
| Chat Completions de OpenAI | `{ choices: [{ delta: { content: "text" } }] }`                                |
| API Messages de Anthropic  | `{ type: "content_block_delta", delta: { type: "text_delta", text: "text" } }` |
| API Gemini de Google       | `{ candidates: [{ content: { parts: [{ text: "text" }] } }] }`                 |

### close

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

```typescript
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.

```typescript
await attachment.close();
```

## Callbacks

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

| Callback       | Firma                                                                              | Descripción                                                                                                              |
| -------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `onInit`       | `(conversationId: string, session: Session) => void`                               | Sesión inicializada con un ID de conversación.                                                                           |
| `onTranscript` | `(transcript: TranscriptMessage[], signal: AbortSignal, session: Session) => void` | Voz del usuario transcrita.                                                                                              |
| `onClose`      | `(session: Session) => void`                                                       | Desconexión limpia de ElevenLabs.                                                                                        |
| `onDisconnect` | `(session: Session) => void`                                                       | WebSocket se desconectó inesperadamente.                                                                                 |
| `onError`      | `(error: Error, session: Session) => void`                                         | Error de protocolo o de WebSocket.                                                                                       |
| `debug`        | `boolean`                                                                          | Activa el registro de depuración.                                                                                        |
| `disableAuth`  | `boolean`                                                                          | Omite la verificación de JWT en conexiones entrantes. Consulta [Desactivar la autenticación](#disabling-authentication). |

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](/docs/es/eleven-api/resources/ip-allowlisting)), puedes omitir la verificación de JWT pasando `disableAuth: true`:

```typescript
// 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.

> **Warning**
>
> Usa `disableAuth: true` solo si tienes una lista de IP permitidas, valores de encabezado personalizados o una restricción
> equivalente a nivel de red delante del servidor. Sin una de estas medidas, cualquiera en internet puede abrir una
> sesión y consumir tus recursos de computación y tu cuota de LLM posterior.

## Eventos

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

| Evento            | Firma del controlador                                    |
| ----------------- | -------------------------------------------------------- |
| `user_transcript` | `(transcript: TranscriptMessage[], signal: AbortSignal)` |
| `init`            | `(conversationId: string)`                               |
| `close`           | `()`                                                     |
| `disconnected`    | `()`                                                     |
| `error`           | `(error: Error)`                                         |

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

```typescript
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.

| Propiedad | Tipo                  | Descripción                        |
| --------- | --------------------- | ---------------------------------- |
| `role`    | `"user"` \| `"agent"` | Quién envió el mensaje.            |
| `content` | `string`              | El contenido de texto del mensaje. |

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

| Tipo de mensaje   | Campos                                                     | Descripción                           |
| ----------------- | ---------------------------------------------------------- | ------------------------------------- |
| `init`            | `conversation_id: string`                                  | Sesión inicializada.                  |
| `user_transcript` | `user_transcript: TranscriptMessage[]`, `event_id: number` | Voz del usuario transcrita.           |
| `ping`            |                                                            | Keep-alive. El SDK responde con pong. |
| `close`           |                                                            | Desconexión limpia.                   |
| `error`           | `message: string`                                          | Error de la API.                      |

### Salientes (servidor del desarrollador a la API de ElevenLabs)

| Tipo de mensaje  | Campos                                                     | Descripción                                      |
| ---------------- | ---------------------------------------------------------- | ------------------------------------------------ |
| `agent_response` | `content: string`, `event_id: number`, `is_final: boolean` | Fragmento de respuesta de LLM para síntesis TTS. |
| `pong`           |                                                            | Respuesta a ping.                                |