Referência do SDK Python | ElevenLabs Documentation

Esta página documenta a API pública do SDK Python do Speech Engine (elevenlabs).

Como obter um recurso do Speech Engine

Recupere um SpeechEngineResource pelo ID do mecanismo. O objeto retornado oferece métodos para iniciar um servidor, verificar solicitações ou criar sessões individuais.

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

SpeechEngineResource

Propriedades

Propriedade	Tipo	Descrição
`engine_id`	`str`	O ID do mecanismo de fala.

serve

Inicia um servidor WebSocket independente. Bloqueia até ser interrompido.

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

Parâmetro	Tipo	Padrão	Descrição
`port`	`int`	`3001`	Porta em que o servidor escuta.
`path`	`str`	`None`	Restringe as conexões a este caminho. `None` aceita todas.
`debug`	`bool`	`False`	Ativa registros de depuração na saída padrão.
`disable_auth`	`bool`	`False`	Ignora a verificação de JWT nas conexões recebidas. Consulte Desativar a autenticação.
`on_init`	`callable`		Chamado quando uma sessão é inicializada.
`on_transcript`	`callable`		Chamado quando chega uma transcrição do usuário.
`on_close`	`callable`		Chamado em uma desconexão normal.
`on_disconnect`	`callable`		Chamado quando o WebSocket é encerrado inesperadamente.
`on_error`	`callable`		Chamado em erros de protocolo ou do WebSocket.

Desativar a autenticação

Por padrão, serve() verifica o cabeçalho X-Elevenlabs-Speech-Engine-Authorization em todas as conexões recebidas. Se o servidor estiver atrás de uma camada de infraestrutura que já restringe o tráfego recebido à ElevenLabs (geralmente uma lista de permissão de IPs limitada aos intervalos de saída da ElevenLabs), você pode ignorar a verificação de JWT passando 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()

Quando a autenticação está desativada, o servidor aceita qualquer cliente que consiga acessá-lo e emite um UserWarning na inicialização.

Use disable_auth=True somente se houver uma lista de permissão de IPs, valores de cabeçalho personalizados ou uma restrição equivalente no nível da rede antes do servidor. Sem isso, qualquer pessoa na internet pode abrir uma sessão e consumir sua capacidade computacional e sua cota de LLM downstream.

verify_request

Verifica se uma solicitação recebida é originada da API Speech Engine da ElevenLabs. Verifica o cabeçalho X-Elevenlabs-Speech-Engine-Authorization em busca de um JWT válido assinado com o hash SHA-256 da sua chave de API.

Necessário apenas quando você mesmo gerencia a atualização do WebSocket. Ao usar serve(), a verificação é realizada automaticamente (a menos que disable_auth=True tenha sido definido).

is_valid = engine.verify_request(headers)

Parâmetro	Tipo	Descrição
`headers`	`dict`	Dicionário de cabeçalhos da solicitação.

Retorna: bool — True se a solicitação for válida.

create_session

Encapsula um WebSocket aceito em uma SpeechEngineSession. Use isso para integrações personalizadas de servidor (por exemplo, FastAPI, Starlette ou gerenciamento manual de WebSocket).

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

Parâmetro	Tipo	Padrão	Descrição
`ws`	WebSocket		Uma conexão WebSocket aceita.
`debug`	`bool`	`False`	Ativa registros de depuração.

Retorna: SpeechEngineSession

SpeechEngineSession

Encapsula uma única conexão WebSocket. Cada conexão representa uma conversa. A sessão emite eventos para transcrições e mudanças no ciclo de vida, além de oferecer métodos para enviar respostas do LLM de volta.

Quando uma nova transcrição chega, o manipulador da transcrição anterior é cancelado automaticamente, interrompendo qualquer chamada de LLM em andamento.

Propriedades

Propriedade	Tipo	Descrição
`conversation_id`	`Optional[str]`	O ID da conversa atribuído pela API. Disponível após `init`.
`is_open`	`bool`	Indica se a sessão ainda está aberta.

on

Registra um manipulador para um evento. Retorna a sessão para encadeamento.

session.on("user_transcript", handler)

off

Remove um manipulador registrado anteriormente.

session.off("user_transcript", handler)

once

Registra um manipulador que é executado uma vez e depois é removido.

session.once("init", handler)

send_response

Envia uma resposta do LLM de volta à API Speech Engine para síntese de texto em fala. Deve ser chamado dentro de um manipulador on_transcript. Chamá-lo fora de um manipulador emite um aviso e retorna sem 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	Descrição
`response`	`str` \| async iterable	Uma string completa ou um iterável assíncrono de trechos de texto / eventos de stream do LLM.

O SDK detecta e extrai automaticamente texto dos seguintes formatos de stream de LLM:

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

run

Executa o loop de recebimento até que o WebSocket seja fechado. Este é o principal ponto de entrada após criar uma sessão manualmente com create_session().

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

close

Fecha a sessão e a conexão WebSocket subjacente.

session.close()

Callbacks

Os argumentos nomeados passados a serve(). Todos os callbacks são opcionais. Os manipuladores podem ser funções síncronas ou assíncronas (corrotinas).

Callback	Assinatura	Descrição
`on_init`	`(conversation_id: str, session) -> None`	Sessão inicializada com um ID de conversa.
`on_transcript`	`(transcript: list, session) -> None`	Fala do usuário transcrita.
`on_close`	`(session) -> None`	Desconexão normal da ElevenLabs.
`on_disconnect`	`(session) -> None`	WebSocket encerrado inesperadamente.
`on_error`	`(error: Exception, session) -> None`	Erro de protocolo ou WebSocket.

Eventos

Ao usar session.on() diretamente em vez de callbacks, estes são os nomes dos eventos e as assinaturas de seus manipuladores.

Evento	Assinatura do manipulador
`user_transcript`	`(transcript: list[ConversationMessage])`
`init`	`(conversation_id: str)`
`close`	`()`
`disconnected`	`()`
`error`	`(error: Exception)`

Constantes de nomes de eventos estão disponíveis para uso com segurança de tipos:

from elevenlabs.speech_engine import USER_TRANSCRIPT, INIT, CLOSE, DISCONNECTED, ERROR
session.on(USER_TRANSCRIPT, handle_transcript)

ConversationMessage

Uma única mensagem no histórico da conversa. A transcrição completa é passada a on_transcript em cada turno.

Propriedade	Tipo	Descrição
`role`	`"user"` \| `"agent"`	Quem enviou a mensagem.
`content`	`str`	O conteúdo textual da mensagem.

Protocolo de comunicação

Para referência, estas são as mensagens JSON trocadas pela conexão WebSocket. O SDK gerencia a serialização e a desserialização automaticamente.

Recebidas (API ElevenLabs para o servidor do desenvolvedor)

Tipo de mensagem	Campos	Descrição
`init`	`conversation_id: string`	Sessão inicializada.
`user_transcript`	`user_transcript: TranscriptMessage[]`, `event_id: number`	Fala do usuário transcrita.
`ping`		Keep-alive. O SDK responde com pong.
`close`		Desconexão normal.
`error`	`message: string`	Erro da API.

Enviadas (servidor do desenvolvedor para a API ElevenLabs)

Tipo de mensagem	Campos	Descrição
`agent_response`	`content: string`, `event_id: number`, `is_final: boolean`	Trecho de resposta do LLM para síntese de TTS.
`pong`		Resposta ao ping.