> 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 JavaScript Esta página documenta a API pública do SDK JavaScript do Speech Engine (`@elevenlabs/elevenlabs-js`). ## Como obter um recurso do Speech Engine Recupere um `SpeechEngineResource` pelo ID do mecanismo. O objeto retornado oferece métodos para se conectar a um servidor HTTP existente, iniciar um servidor independente ou criar sessões individuais. ```typescript import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); const engine = await elevenlabs.speechEngine.get("seng_8k3m9xr4hjnfg983brhmhkd98n6"); ``` ## SpeechEngineResource ### Propriedades | Propriedade | Tipo | Descrição | | ----------- | -------- | -------------------------- | | `engineId` | `string` | O ID do mecanismo de fala. | ### attach Conecte-se a um servidor HTTP Node.js existente e comece a aceitar conexões do Speech Engine no caminho especificado. Use este método quando você já tiver um servidor HTTP (por exemplo, Express, Fastify ou um simples `http.createServer()`) e quiser adicionar o Speech Engine às suas rotas existentes. Gerencia automaticamente atualizações de WebSocket, roteamento de caminhos e verificação de solicitações. Retorna um `SpeechEngineAttachment`, cujo método `close()` deixa de aceitar conexões sem afetar o servidor HTTP. ```typescript const attachment = engine.attach(httpServer, "/ws", { debug: true, onTranscript(transcript, signal, session) { session.sendResponse(stream); }, }); ``` | Parâmetro | Tipo | Descrição | | ------------ | ----------------------- | -------------------------------------------------------- | | `httpServer` | `http.Server` | O servidor HTTP Node.js ao qual se conectar. | | `path` | `string` | Caminho de URL para gerenciar atualizações de WebSocket. | | `handler` | `SpeechEngineCallbacks` | Objeto de callback (consulte [Callbacks](#callbacks)). | Há um atalho disponível diretamente no cliente, que combina `get()` e `attach()` em uma única chamada: ```typescript await elevenlabs.speechEngine.attach("seng_8k3m9xr4hjnfg983brhmhkd98n6", httpServer, "/ws", { onTranscript(transcript, signal, session) { session.sendResponse(stream); }, }); ``` ### verifyRequest Verifique se uma solicitação recebida é originada pela API do 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 ao gerenciar você mesmo a atualização do WebSocket. Ao usar `attach()` ou `SpeechEngineServer`, a verificação é feita automaticamente. ```typescript const isValid = await engine.verifyRequest(req); ``` | Parâmetro | Tipo | Descrição | | --------- | -------------------------------------------------------------- | ------------------------------------ | | `req` | `{ headers: Record }` | Objeto de solicitação HTTP recebida. | **Retorna:** `Promise` — `true` se a solicitação for válida. ### createSession Encapsule um WebSocket aceito em uma `SpeechEngineSession`. Use este método para integração com servidor personalizado ou gerenciamento manual de WebSocket. ```typescript const session = engine.createSession(ws, { debug: true }); session.on("user_transcript", (transcript, signal) => { /* ... */ }); ``` | Parâmetro | Tipo | Padrão | Descrição | | --------------- | --------- | ------- | ------------------------------ | | `ws` | WebSocket | | Uma conexão WebSocket aceita. | | `options.debug` | `boolean` | `false` | Ativa o registro de depuração. | **Retorna:** `SpeechEngineSession` ## SpeechEngineServer Um servidor WebSocket independente que aceita conexões do Speech Engine sem exigir um servidor HTTP existente. Use-o quando o único propósito do seu servidor for gerenciar conexões do Speech Engine. Para integração com um servidor HTTP existente (por exemplo, Express, Fastify), use [`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(); ``` ### Opções do construtor | Parâmetro | Tipo | Padrão | Descrição | | ---------- | ----------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `port` | `number` | `3001` | Porta em que o servidor escuta. | | `apiKey` | `string` | | Chave da API da ElevenLabs para verificar conexões. Usa a variável de ambiente `ELEVENLABS_API_KEY` como alternativa. Não é necessária quando `disableAuth` é `true`. | | `engineId` | `string` | | O ID do mecanismo de fala. Preenchido automaticamente quando criado por meio do recurso. | | ... | `SpeechEngineCallbacks` | | Todas as opções de callback (`onInit`, `onTranscript`, `onClose`, `onDisconnect`, `onError`, `debug`, `disableAuth`). Consulte [Callbacks](#callbacks). | ### start Inicie o servidor WebSocket independente na porta configurada. Verifica cada conexão recebida com a API da ElevenLabs usando a chave de API configurada, a menos que `disableAuth: true` tenha sido definido. ```typescript server.start(); ``` ### stop Pare o servidor WebSocket e feche todas as conexões ativas. ```typescript await server.stop(); ``` ### handleConnection Encapsule um WebSocket existente em uma `SpeechEngineSession` com os callbacks do servidor conectados. Use este método quando você gerenciar seu próprio servidor WebSocket e quiser encapsular conexões individuais. ```typescript const session = server.handleConnection(ws); ``` | Parâmetro | Tipo | Descrição | | --------- | ----------- | ----------------------------- | | `ws` | `WebSocket` | Uma conexão WebSocket aceita. | **Retorna:** `SpeechEngineSession` ## SpeechEngineSession Encapsula uma única conexão WebSocket. Cada conexão representa uma conversa. A sessão emite eventos para transcrições e alterações no ciclo de vida, além de fornecer métodos para enviar respostas de LLM de volta. Quando uma nova transcrição chega, o sinal de cancelamento do manipulador da transcrição anterior é acionado, interrompendo qualquer chamada de LLM em andamento. ### Propriedades | Propriedade | Tipo | Descrição | | ---------------- | --------- | ------------------------------------------------------------ | | `conversationId` | `string` | O ID da conversa atribuído pela API. Disponível após `init`. | | `isOpen` | `boolean` | Indica se a sessão ainda está aberta. | ### on Registre um manipulador para um evento. Retorna a sessão para encadeamento. ```typescript session.on("user_transcript", (transcript, signal) => { /* ... */ }); ``` ### off Remova um manipulador registrado anteriormente. ```typescript session.off("user_transcript", listener); ``` ### once Registre um manipulador que é acionado uma vez e depois se remove. ```typescript session.once("init", (conversationId) => { /* ... */ }); ``` ### sendResponse Envie uma resposta de LLM de volta para a API do Speech Engine para síntese de texto em voz. Deve ser chamado dentro de um manipulador `onTranscript`. Chamá-lo fora de um manipulador emite um aviso e retorna sem 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 | Descrição | | ---------- | ------------------------------------ | ------------------------------------------------------------------------------------------ | | `response` | `string` \| `AsyncIterable` | Uma string completa ou um iterável assíncrono de blocos de texto/eventos de stream de LLM. | O SDK detecta automaticamente e extrai texto dos seguintes formatos de stream de LLM: | Provedor | Formato do 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" }] } }] }` | ### close Feche a sessão e a conexão WebSocket subjacente. ```typescript session.close(); ``` ## SpeechEngineAttachment Retornado por `engine.attach()`. Controla o ciclo de vida do servidor WebSocket sem afetar o servidor HTTP ao qual foi conectado. ### close Pare de aceitar novas conexões, remova o listener de atualização do servidor HTTP e feche o servidor WebSocket subjacente. ```typescript await attachment.close(); ``` ## Callbacks O objeto de callback passado para `attach()` ou `SpeechEngineServer`. Todos os callbacks são opcionais. | Callback | Assinatura | Descrição | | -------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `onInit` | `(conversationId: string, session: Session) => void` | Sessão inicializada com um ID de conversa. | | `onTranscript` | `(transcript: TranscriptMessage[], signal: AbortSignal, session: Session) => void` | Fala do usuário transcrita. | | `onClose` | `(session: Session) => void` | Desconexão normal da ElevenLabs. | | `onDisconnect` | `(session: Session) => void` | WebSocket desconectado inesperadamente. | | `onError` | `(error: Error, session: Session) => void` | Erro de protocolo ou WebSocket. | | `debug` | `boolean` | Ativa o registro de depuração. | | `disableAuth` | `boolean` | Ignora a verificação de JWT em conexões recebidas. Consulte [Como desativar a autenticação](#disabling-authentication). | O manipulador `onTranscript` recebe um `AbortSignal` que é acionado quando o usuário interrompe no meio de uma resposta. ### Como desativar a autenticação Por padrão, tanto `attach()` quanto `SpeechEngineServer` verificam o cabeçalho `X-Elevenlabs-Speech-Engine-Authorization` em cada conexão recebida. Se o seu servidor estiver atrás de uma camada de infraestrutura que já restringe o tráfego recebido à ElevenLabs (normalmente, uma lista de permissões de IP limitada aos [intervalos de saída da ElevenLabs](/docs/pt/eleven-api/resources/ip-allowlisting)), você pode ignorar a verificação de JWT passando `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, }); ``` Quando a autenticação está desativada, o servidor aceita qualquer cliente que consiga acessá-lo e emite um `console.warn` na inicialização. > **Warning** > > Use `disableAuth: true` somente se houver uma lista de permissões de IP, valores de cabeçalho personalizados ou uma restrição > equivalente no nível de rede em frente ao servidor. Sem isso, qualquer pessoa na internet pode abrir uma > sessão e consumir sua capacidade de computação e sua cota de LLM downstream. ## 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: TranscriptMessage[], signal: AbortSignal)` | | `init` | `(conversationId: string)` | | `close` | `()` | | `disconnected` | `()` | | `error` | `(error: Error)` | Constantes de nomes de eventos estão disponíveis para uso com segurança de tipos: ```typescript import { SpeechEngine } from "@elevenlabs/elevenlabs-js"; session.on(SpeechEngine.USER_TRANSCRIPT, (transcript, signal) => { /* ... */ }); ``` ## TranscriptMessage Uma única mensagem no histórico da conversa. A transcrição completa é passada para `onTranscript` a cada turno. | Propriedade | Tipo | Descrição | | ----------- | --------------------- | -------------------------------- | | `role` | `"user"` \| `"agent"` | Quem enviou a mensagem. | | `content` | `string` | O conteúdo de texto da mensagem. | ## Protocolo de comunicação Como 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 da ElevenLabs para 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` | | Manutenção de conexão. O SDK responde com pong. | | `close` | | Desconexão normal. | | `error` | `message: string` | Erro da API. | ### Enviadas (servidor do desenvolvedor para API da ElevenLabs) | Tipo de mensagem | Campos | Descrição | | ---------------- | ---------------------------------------------------------- | --------------------------------------------- | | `agent_response` | `content: string`, `event_id: number`, `is_final: boolean` | Bloco de resposta de LLM para síntese de TTS. | | `pong` | | Resposta ao ping. |