JavaScript SDK 레퍼런스

이 페이지에서는 Speech Engine JavaScript SDK(@elevenlabs/elevenlabs-js)의 공개 API를 문서화합니다.

Speech Engine 리소스 가져오기

엔진 ID로 SpeechEngineResource를 가져옵니다. 반환된 객체는 기존 HTTP 서버에 연결하고, 독립형 서버를 시작하거나, 개별 세션을 생성하는 메서드를 제공합니다.

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

SpeechEngineResource

속성

attach

기존 Node.js HTTP 서버에 연결하고 지정된 경로에서 Speech Engine 연결을 수락하기 시작합니다. 이미 HTTP 서버(예: Express, Fastify 또는 일반 http.createServer())가 있고 기존 라우트와 함께 Speech Engine을 추가하려는 경우 사용합니다.

WebSocket 업그레이드, 경로 라우팅 및 요청 검증을 자동으로 처리합니다. close() 메서드가 HTTP 서버에 영향을 주지 않고 연결 수락을 중지하는 SpeechEngineAttachment를 반환합니다.

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

클라이언트에서 직접 사용할 수 있는 단축 방식으로, get()과 attach()를 하나의 호출로 결합할 수 있습니다.

await elevenlabs.speechEngine.attach("seng_8k3m9xr4hjnfg983brhmhkd98n6", httpServer, "/ws", {
  onTranscript(transcript, signal, session) {
    session.sendResponse(stream);
  },
});

verifyRequest

수신 요청이 ElevenLabs Speech Engine API에서 시작되었는지 확인합니다. API 키의 SHA-256 해시로 서명된 유효한 JWT가 있는지 X-Elevenlabs-Speech-Engine-Authorization 헤더를 확인합니다.

WebSocket 업그레이드를 직접 관리할 때만 필요합니다. attach() 또는 SpeechEngineServer를 사용하면 검증이 자동으로 처리됩니다.

const isValid = await engine.verifyRequest(req);

반환값: 요청이 유효하면 true인 Promise<boolean>

createSession

수락된 WebSocket을 SpeechEngineSession으로 래핑합니다. 맞춤 서버 통합 또는 수동 WebSocket 처리에 사용합니다.

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

반환값: SpeechEngineSession

SpeechEngineServer

기존 HTTP 서버 없이 Speech Engine 연결을 수락하는 독립형 WebSocket 서버입니다. 서버의 유일한 목적이 Speech Engine 연결 처리인 경우 사용합니다.

기존 HTTP 서버(예: Express, Fastify)와 통합하려면 대신 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();

생성자 옵션

start

구성된 포트에서 독립형 WebSocket 서버를 시작합니다. disableAuth: true가 설정되지 않은 한, 구성된 API 키를 사용해 각 수신 연결을 ElevenLabs API로 검증합니다.

server.start();

stop

WebSocket 서버를 중지하고 모든 활성 연결을 종료합니다.

await server.stop();

handleConnection

서버의 콜백이 연결된 상태로 기존 WebSocket을 SpeechEngineSession으로 래핑합니다. 자체 WebSocket 서버를 관리하면서 개별 연결을 래핑하려는 경우 사용합니다.

const session = server.handleConnection(ws);

반환값: SpeechEngineSession

SpeechEngineSession

단일 WebSocket 연결을 래핑합니다. 각 연결은 하나의 대화를 나타냅니다. 세션은 트랜스크립트 및 수명 주기 변경에 대한 이벤트를 발생시키고, LLM 응답을 다시 전송하는 메서드를 제공합니다.

새 트랜스크립트가 도착하면 이전 트랜스크립트 핸들러의 중단 신호가 발생하여 진행 중인 모든 LLM 호출을 중단합니다.

속성

on

이벤트 핸들러를 등록합니다. 체이닝을 위해 세션을 반환합니다.

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

off

이전에 등록한 핸들러를 제거합니다.

session.off("user_transcript", listener);

once

한 번 실행된 후 자체적으로 제거되는 핸들러를 등록합니다.

session.once("init", (conversationId) => {
  /* ... */
});

sendResponse

텍스트 음성 변환을 위해 LLM 응답을 Speech Engine API로 다시 전송합니다. onTranscript 핸들러 내에서 호출해야 합니다. 핸들러 외부에서 호출하면 경고를 발생시키고 전송하지 않은 채 반환합니다.

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

SDK는 다음 LLM 스트림 형식에서 텍스트를 자동으로 감지하고 추출합니다.

close

세션과 기본 WebSocket 연결을 종료합니다.

session.close();

SpeechEngineAttachment

engine.attach()가 반환합니다. 연결된 HTTP 서버에는 영향을 주지 않고 WebSocket 서버의 수명 주기를 제어합니다.

close

새 연결 수락을 중지하고, HTTP 서버에서 업그레이드 리스너를 제거하며, 기본 WebSocket 서버를 종료합니다.

await attachment.close();

콜백

attach() 또는 SpeechEngineServer에 전달하는 콜백 객체입니다. 모든 콜백은 선택 사항입니다.

onTranscript 핸들러는 사용자가 응답 중간에 중단할 때 발생하는 AbortSignal을 받습니다.

인증 비활성화

기본적으로 attach()와 SpeechEngineServer는 모든 수신 연결에서 X-Elevenlabs-Speech-Engine-Authorization 헤더를 검증합니다. 서버가 이미 ElevenLabs로의 수신 트래픽을 제한하는 인프라 계층(일반적으로 ElevenLabs의 송신 범위로 범위가 지정된 IP 허용 목록) 뒤에 있다면 disableAuth: true를 전달하여 JWT 검증을 건너뛸 수 있습니다.

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

인증이 비활성화되면 서버는 연결할 수 있는 모든 클라이언트를 수락하고 시작 시 console.warn을 발생시킵니다.

이벤트

콜백 대신 session.on()을 직접 사용할 때의 이벤트 이름과 해당 핸들러 시그니처입니다.

타입 안전한 사용을 위한 이벤트 이름 상수를 제공합니다.

import { SpeechEngine } from "@elevenlabs/elevenlabs-js";
session.on(SpeechEngine.USER_TRANSCRIPT, (transcript, signal) => {
  /* ... */
});

TranscriptMessage

대화 기록의 단일 메시지입니다. 전체 트랜스크립트는 매 턴마다 onTranscript에 전달됩니다.

와이어 프로토콜

참고용으로, WebSocket 연결을 통해 교환되는 JSON 메시지는 다음과 같습니다. SDK가 직렬화와 역직렬화를 자동으로 처리합니다.

수신(개발자 서버로 전송되는 ElevenLabs API 메시지)

발신(개발자 서버에서 ElevenLabs API로 전송)