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.

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
const elevenlabs = new ElevenLabsClient();
const engine = await elevenlabs.speechEngine.get("seng_8k3m9xr4hjnfg983brhmhkd98n6");

SpeechEngineResource

Propriedades

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.

const attachment = engine.attach(httpServer, "/ws", {
  debug: true,
  onTranscript(transcript, signal, session) {
    session.sendResponse(stream);
  },
});

Há um atalho disponível diretamente no cliente, que combina get() e attach() em uma única chamada:

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.

const isValid = await engine.verifyRequest(req);

Retorna: Promise<boolean> — 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.

const session = engine.createSession(ws, { debug: true });
session.on("user_transcript", (transcript, signal) => {
  /* ... */
});

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

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

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.

server.start();

stop

Pare o servidor WebSocket e feche todas as conexões ativas.

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.

const session = server.handleConnection(ws);

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

on

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

session.on("user_transcript", (transcript, signal) => {
  /* ... */
});

off

Remova um manipulador registrado anteriormente.

session.off("user_transcript", listener);

once

Registre um manipulador que é acionado uma vez e depois se remove.

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.

// 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);

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

close

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

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.

await attachment.close();

Callbacks

O objeto de callback passado para attach() ou SpeechEngineServer. Todos os callbacks são opcionais.

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), você pode ignorar a verificação de JWT passando disableAuth: true:

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

Eventos

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

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

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.

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)

Enviadas (servidor do desenvolvedor para API da ElevenLabs)