> 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. # Referência do SDK Python 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. ```python 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. ```python 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](#disabling-authentication). | | `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](/docs/pt/eleven-api/resources/ip-allowlisting)), você pode ignorar a verificação de JWT passando `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() ``` Quando a autenticação está desativada, o servidor aceita qualquer cliente que consiga acessá-lo e emite um `UserWarning` na inicialização. > **Warning** > > 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). ```python 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). ```python 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. ```python session.on("user_transcript", handler) ``` ### off Remove um manipulador registrado anteriormente. ```python session.off("user_transcript", handler) ``` ### once Registra um manipulador que é executado uma vez e depois é removido. ```python 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. ```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 | 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()`. ```python 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. ```python 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: ```python 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. |