Referencia del SDK de Python | ElevenLabs Documentation

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.

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.

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.
`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), puedes omitir la verificación de JWT pasando disable_auth=True:

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

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

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

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.

session.on("user_transcript", handler)

off

Elimina un controlador registrado previamente.

session.off("user_transcript", handler)

once

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

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.

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

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.

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:

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.