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

Esta página documenta la API pública del SDK de Python de Speech Engine (`elevenlabs`).

## Obtener un recurso de Speech Engine

Recupera un `SpeechEngineResource` mediante el ID de su motor. El objeto devuelto ofrece métodos para iniciar un servidor, verificar solicitudes o crear sesiones individuales.

```python
from elevenlabs import AsyncElevenLabs

elevenlabs = AsyncElevenLabs()
engine = await elevenlabs.speech_engine.get("seng_8k3m9xr4hjnfg983brhmhkd98n6")
```

## SpeechEngineResource

### Propiedades

| Propiedad   | Tipo  | Descripción             |
| ----------- | ----- | ----------------------- |
| `engine_id` | `str` | El ID del motor de voz. |

### serve

Inicia un servidor WebSocket independiente. Se bloquea hasta que se detiene.

```python
await engine.serve(
    port=3001,
    path="/ws",
    debug=True,
    on_transcript=handle_transcript,
)
```

| Parámetro       | Tipo       | Predeterminado | Descripción                                                                                                                  |
| --------------- | ---------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `port`          | `int`      | `3001`         | Puerto en el que escuchar.                                                                                                   |
| `path`          | `str`      | `None`         | Restringe las conexiones a esta ruta. `None` acepta todas.                                                                   |
| `debug`         | `bool`     | `False`        | Activa el registro de depuración en stdout.                                                                                  |
| `disable_auth`  | `bool`     | `False`        | Omite la verificación de JWT en las conexiones entrantes. Consulta [Desactivar la autenticación](#disabling-authentication). |
| `on_init`       | `callable` |                | Se llama cuando se inicializa una sesión.                                                                                    |
| `on_transcript` | `callable` |                | Se llama cuando llega una transcripción de usuario.                                                                          |
| `on_close`      | `callable` |                | Se llama al desconectarse correctamente.                                                                                     |
| `on_disconnect` | `callable` |                | Se llama cuando el WebSocket se desconecta inesperadamente.                                                                  |
| `on_error`      | `callable` |                | Se llama cuando se producen errores de protocolo o WebSocket.                                                                |

#### Desactivar la autenticación

De forma predeterminada, `serve()` verifica la cabecera `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 `disable_auth=True`:

```python
# No api_key required when disable_auth is True
await engine.serve(port=3001, disable_auth=True, on_transcript=on_transcript)

# Or directly on SpeechEngineServer
from elevenlabs.speech_engine import SpeechEngineServer

server = SpeechEngineServer(port=3001, disable_auth=True, on_transcript=on_transcript)
await server.serve()
```

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

> **Warning**
>
> Usa `disable_auth=True` solo si tienes una lista de IP permitidas, valores de cabecera personalizados o una restricción
> equivalente a nivel de red delante del servidor. Sin una, cualquier persona en internet puede abrir una
> sesión y consumir tu capacidad de procesamiento y cuota de LLM posterior.

### verify_request

Verifica que una solicitud entrante procede de la API de Speech Engine de ElevenLabs. Comprueba que la cabecera `X-Elevenlabs-Speech-Engine-Authorization` contenga un JWT válido firmado con el hash SHA-256 de tu clave de API.

Solo es necesario cuando gestionas tú mismo la actualización a WebSocket. Al usar `serve()`, la verificación se gestiona automáticamente (a menos que se haya establecido `disable_auth=True`).

```python
is_valid = engine.verify_request(headers)
```

| Parámetro | Tipo   | Descripción                               |
| --------- | ------ | ----------------------------------------- |
| `headers` | `dict` | Diccionario de cabeceras de la solicitud. |

**Devuelve:** `bool` — `True` si la solicitud es válida.

### create_session

Envuelve un WebSocket aceptado en una `SpeechEngineSession`. Úsalo para integrar un servidor personalizado (por ejemplo, FastAPI, Starlette o gestión manual de WebSocket).

```python
session = engine.create_session(websocket, debug=True)
session.on("user_transcript", handle_transcript)
await session.run()
```

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

**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 ofrece métodos para enviar respuestas de LLM.

Cuando llega una transcripción nueva, el controlador de la transcripción anterior se cancela automáticamente, interrumpiendo cualquier llamada de LLM en curso.

### Propiedades

| Propiedad         | Tipo            | Descripción                                                              |
| ----------------- | --------------- | ------------------------------------------------------------------------ |
| `conversation_id` | `Optional[str]` | El ID de conversación asignado por la API. Disponible después de `init`. |
| `is_open`         | `bool`          | Indica si la sesión sigue abierta.                                       |

### on

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

```python
session.on("user_transcript", handler)
```

### off

Elimina un controlador registrado previamente.

```python
session.off("user_transcript", handler)
```

### once

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

```python
session.once("init", handler)
```

### send_response

Envía una respuesta de LLM a la API de Speech Engine para la síntesis de texto a voz. Debe llamarse dentro de un controlador `on_transcript`. Si se llama fuera de un controlador, emite una advertencia y vuelve sin enviar nada.

```python
# String response
await session.send_response("Hello, how can I help?")

# Streamed response (OpenAI, Anthropic, or Gemini)
stream = await openai_client.responses.create(model="gpt-4o", input=messages, stream=True)
await session.send_response(stream)
```

| Parámetro  | Tipo                    | Descripción                                                                                   |
| ---------- | ----------------------- | --------------------------------------------------------------------------------------------- |
| `response` | `str` \| async iterable | Una cadena completa o un iterable asíncrono de fragmentos de texto o eventos de flujo de LLM. |

El SDK detecta y extrae automáticamente el texto de los siguientes formatos de flujo 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" }] } }] }`                 |

### run

Ejecuta el bucle de recepción hasta que se cierre el WebSocket. Este es el punto de entrada principal después de construir una sesión manualmente mediante `create_session()`.

```python
session = engine.create_session(websocket)
session.on("user_transcript", handle_transcript)
await session.run()
```

### close

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

```python
session.close()
```

## Callbacks

Los argumentos de palabra clave que se pasan a `serve()`. Todos los callbacks son opcionales. Los controladores pueden ser funciones síncronas o asíncronas (corutinas).

| Callback        | Firma                                     | Descripción                                    |
| --------------- | ----------------------------------------- | ---------------------------------------------- |
| `on_init`       | `(conversation_id: str, session) -> None` | Sesión inicializada con un ID de conversación. |
| `on_transcript` | `(transcript: list, session) -> None`     | Voz de usuario transcrita.                     |
| `on_close`      | `(session) -> None`                       | Desconexión correcta de ElevenLabs.            |
| `on_disconnect` | `(session) -> None`                       | El WebSocket se desconectó inesperadamente.    |
| `on_error`      | `(error: Exception, session) -> None`     | Error de protocolo o WebSocket.                |

## Eventos

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

| Evento            | Firma del controlador                     |
| ----------------- | ----------------------------------------- |
| `user_transcript` | `(transcript: list[ConversationMessage])` |
| `init`            | `(conversation_id: str)`                  |
| `close`           | `()`                                      |
| `disconnected`    | `()`                                      |
| `error`           | `(error: Exception)`                      |

Las constantes de nombres de eventos están disponibles para usarlas de forma segura con tipos:

```python
from elevenlabs.speech_engine import USER_TRANSCRIPT, INIT, CLOSE, DISCONNECTED, ERROR

session.on(USER_TRANSCRIPT, handle_transcript)
```

## ConversationMessage

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

| Propiedad | Tipo                  | Descripción                       |
| --------- | --------------------- | --------------------------------- |
| `role`    | `"user"` \| `"agent"` | Quién envió el mensaje.           |
| `content` | `str`                 | El contenido textual 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 de usuario transcrita.                           |
| `ping`            |                                                            | Mantenimiento de conexión. El SDK responde con pong. |
| `close`           |                                                            | Desconexión correcta.                                |
| `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 de TTS. |
| `pong`           |                                                            | Respuesta a ping.                                   |