Speech Engine 빠른 시작 | ElevenLabs Documentation

이 가이드에서는 Speech Engine으로 음성 기반 에이전트를 구축하는 방법을 안내합니다. LLM을 ElevenLabs에 연결하는 서버를 설정한 다음, 사용자가 에이전트와 음성으로 대화할 수 있도록 브라우저 클라이언트를 연결합니다.

ElevenLabs Speech Engine 스킬을 사용해 채팅 에이전트에 음성을 추가하세요.

npx skills add elevenlabs/skills --skill speech-engine

Speech Engine 작동 방식

Speech Engine은 LLM을 ElevenLabs에 연결하여 사용자가 에이전트에게 말하고 에이전트의 응답을 들을 수 있게 합니다. ElevenLabs는 음성 인식과 텍스트 음성 변환을 처리하고, 서버는 LLM 로직을 제공합니다.

각 WebSocket 연결은 하나의 대화를 나타냅니다. 사용자가 말하면 ElevenLabs가 오디오를 전사하고 전사본을 서버로 전송합니다. 서버는 이를 LLM에 전달한 뒤 응답을 다시 스트리밍합니다. ElevenLabs는 텍스트를 음성으로 변환하여 브라우저에서 재생합니다. SDK는 연결 관리, 발화 순서 관리, 인터럽트 감지를 처리합니다.

사전 요구 사항

이 튜토리얼에서는 LLM에 OpenAI API를 사용합니다. OPENAI_API_KEY 환경 변수에 OpenAI API 키를 설정해야 합니다.

서버 설정

API 키 만들기

여기 대시보드에서 API 키를 생성하세요. 이 키는 API에 안전하게 액세스하는 데 사용됩니다.

키를 관리형 시크릿으로 저장하고, 선호에 따라 .env 파일을 통한 환경 변수 또는 앱 구성에서 직접 SDK에 전달하세요.

.env

ELEVENLABS_API_KEY=<your_api_key_here>

종속성 설치

pip install elevenlabs openai python-dotenv

서버 노출

Speech Engine에는 공개적으로 접근할 수 있는 URL이 필요합니다. ngrok을 사용해 로컬 서버를 노출하세요. 서버는 아직 구축되지 않았지만, 다음 단계에서 사용할 URL을 확보하려면 먼저 ngrok을 실행해야 합니다.

ngrok http 3001

포워딩 URL(예: https://abc123.ngrok.io)을 복사하세요.

Speech Engine 인스턴스 만들기

SDK를 사용해 Speech Engine 인스턴스를 만듭니다. ngrok URL에 /ws 경로를 추가한 값을 WebSocket URL로 전달하세요.

import asyncio
from dotenv import load_dotenv
from elevenlabs import AsyncElevenLabs
load_dotenv()
elevenlabs = AsyncElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)
async def main():
    engine = await elevenlabs.speech_engine.create(
        name="My Speech Engine",
        speech_engine={
            # Note we use the wss protocol instead of https
            "ws_url": "wss://abc123.ngrok.io/ws",
        },
    )
    print(f"Speech Engine ID: {engine.engine_id}")
if __name__ == "__main__":
    asyncio.run(main())

이 스크립트를 실행하고 다음 단계에서 사용할 Speech Engine ID(예: seng_8k3m9xr4hjnfg983brhmhkd98n6)를 복사하세요.

서버 만들기

다음 내용을 포함하는 server.py 또는 server.mts 파일을 만드세요. 이 코드는 서버를 설정하고, /ws 경로에 Speech Engine을 연결하며, OpenAI를 사용해 응답을 생성합니다.

import asyncio
import os
from dotenv import load_dotenv
from openai import AsyncOpenAI
from elevenlabs import AsyncElevenLabs
load_dotenv()
# Replace with your Speech Engine ID from step 4
SPEECH_ENGINE_ID = "seng_8k3m9xr4hjnfg983brhmhkd98n6"
openai = AsyncOpenAI(
  api_key=os.getenv("OPENAI_API_KEY"),
)
elevenlabs = AsyncElevenLabs(
  api_key=os.getenv("ELEVENLABS_API_KEY"),
)
def on_init(conversation_id, session):
    print(f"Session started: {conversation_id}")
async def on_transcript(transcript, session):
    stream = await openai.responses.create(
        model="gpt-4o",
        instructions="You are a helpful voice assistant. Keep responses concise and conversational.",
        input=[
            {"role": "assistant" if m.role == "agent" else m.role, "content": m.content}
            for m in transcript
        ],
        stream=True,
    )
    await session.send_response(stream)
def on_close(session):
    print(f"Session ended: {session.conversation_id}")
def on_error(err, session):
    print(f"Error: {err}")
async def main():
    engine = await elevenlabs.speech_engine.get(SPEECH_ENGINE_ID)
    await engine.serve(
        port=3001,
        path="/ws",
        debug=True,
        on_init=on_init,
        on_transcript=on_transcript,
        on_close=on_close,
        on_error=on_error,
    )
if __name__ == "__main__":
    asyncio.run(main())

onTranscript / on_transcript 콜백은 전체 대화 기록과 현재 세션을 받습니다. TypeScript SDK는 사용자가 응답 도중 인터럽트할 때 실행되는 AbortSignal도 제공합니다. OpenAI 호출에 signal을 전달하면 인터럽트 시 LLM 요청이 자동으로 취소됩니다.

sendResponse() / send_response()는 문자열, 비동기 이터러블 또는 OpenAI, Anthropic, Google Gemini의 스트림을 허용합니다. SDK가 텍스트 콘텐츠를 자동으로 추출합니다.

위 예시에서는 사용자의 전체 전사본이 LLM에 전달됩니다. 프로덕션 환경에서는 프롬프트 인젝션이나 조작 시도를 방지하기 위한 가드레일을 추가해야 합니다.

서버 시작

python server.py

클라이언트 설정

클라이언트 SDK 설치

React

JavaScript

npm install @elevenlabs/react

토큰 엔드포인트 만들기

대화 토큰을 생성하는 서버 측 엔드포인트를 추가하세요. 이렇게 하면 API 키를 브라우저에 노출하지 않고 최상의 오디오 품질을 위해 WebRTC를 사용할 수 있습니다.

import os
from dotenv import load_dotenv
from flask import Flask, jsonify
from elevenlabs import ElevenLabs
load_dotenv()
app = Flask(__name__)
elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)
@app.route("/api/token")
def get_token():
    # Replace with your Speech Engine ID from step 4 of the server setup
    speech_engine_id = "seng_8k3m9xr4hjnfg983brhmhkd98n6"
    response = elevenlabs.conversational_ai.conversations.get_webrtc_token(
        agent_id=speech_engine_id,
    )
    return jsonify(token=response.token)
if __name__ == "__main__":
    app.run(port=3002)

대화 UI 구축

서버에서 대화 토큰을 가져와 세션을 시작하는 데 사용하세요.

React

JavaScript

App.tsx

import { useConversation } from "@elevenlabs/react";
import { useCallback } from "react";
async function getToken(): Promise<string> {
  const response = await fetch("/api/token");
  if (!response.ok) {
    throw Error("Failed to get conversation token");
  }
  const data = await response.json();
  return data.token;
}
export default function App() {
  const conversation = useConversation({
    onConnect: () => console.log("Connected"),
    onDisconnect: () => console.log("Disconnected"),
    onError: (error: Error) => console.error("Error:", error),
  });
  const startConversation = useCallback(async () => {
    await navigator.mediaDevices.getUserMedia({ audio: true });
    const token = await getToken();
    await conversation.startSession({ conversationToken: token });
  }, [conversation]);
  const stopConversation = useCallback(async () => {
    await conversation.endSession();
  }, [conversation]);
  return (
    <div>
      <p>Status: {conversation.status}</p>
      <button onClick={startConversation} disabled={conversation.status === "connected"}>
        Start conversation
      </button>
      <button onClick={stopConversation} disabled={conversation.status !== "connected"}>
        End conversation
      </button>
    </div>
  );
}

테스트하기

다음 3개의 프로세스가 실행 중인지 확인하세요.

ngrok - 포트 3001로 포워딩
Speech Engine 서버 - python server.py 또는 npx tsx server.mts
토큰 서버 - npx tsx token-server.mts 또는 python token_server.py

브라우저에서 클라이언트 애플리케이션을 열고 대화 시작을 클릭하세요. 메시지가 표시되면 마이크 액세스를 허용한 후 말해 보세요. 스피커를 통해 에이전트의 응답을 들을 수 있습니다.

서버에서 debug: true를 활성화했다면 콘솔에 수신 전사본과 발신 응답이 기록됩니다.

세션 이벤트

이벤트	TypeScript 콜백	Python 콜백	설명
`user_transcript`	`onTranscript`	`on_transcript`	사용자 음성이 전사되었습니다. 전체 대화 기록과 중단 신호가 포함됩니다.
`init`	`onInit`	`on_init`	대화 ID로 세션이 초기화되었습니다.
`close`	`onClose`	`on_close`	ElevenLabs에서 정상적으로 연결이 해제되었습니다.
`disconnected`	`onDisconnect`	`on_disconnect`	WebSocket 연결이 예기치 않게 끊어졌습니다.
`error`	`onError`	`on_error`	프로토콜 또는 WebSocket 오류입니다.

에이전트의 첫 메시지 구성

기본적으로 에이전트는 사용자가 먼저 말할 때까지 기다립니다. 대화가 시작될 때 에이전트가 사용자에게 인사하게 하려면, 세션을 시작할 때 클라이언트의 overrides 옵션에서 첫 메시지를 설정하세요.

에이전트가 먼저 말할 수 있도록, 클라이언트에서 이를 설정할 수 있게 Speech Engine 리소스를 업데이트해야 합니다.

engine = await elevenlabs.speech_engine.update(
    speech_engine_id="seng_8k3m9xr4hjnfg983brhmhkd98n6",
    overrides={
      "first_message": True,
    },
)

이제 클라이언트 SDK에서 첫 메시지를 구성합니다.

React

JavaScript

conversation.startSession({
  conversationToken: token,
  overrides: {
    agent: {
      firstMessage: "Hello! How can I help you today?",
    },
  },
});

연결이 설정되는 즉시 에이전트가 첫 메시지를 말합니다. 이 메시지는 서버의 onTranscript 콜백을 트리거하지 않으며, 전적으로 ElevenLabs 측에서 처리됩니다.

최대 대화 시간 구성

기본적으로 대화는 600초(10분) 후에 종료됩니다. Speech Engine은 최대 2,400초(40분)의 대화를 지원합니다. 더 긴 대화를 허용하려면 더 높은 max_duration_seconds 값으로 Speech Engine 리소스를 업데이트하세요.

engine = await elevenlabs.speech_engine.update(
    speech_engine_id="seng_8k3m9xr4hjnfg983brhmhkd98n6",
    conversation={
        "max_duration_seconds": 2400,
    },
)

대시보드에서도 설정할 수 있습니다. Speech Engine을 열고 고급 탭으로 이동한 다음, 대화 동작 아래에서 최대 대화 시간을 설정하세요.

40분을 초과하는 대화는 지원되지 않으며, max_duration_seconds를 더 높은 값으로 설정해도 연결이 해제될 수 있습니다. 더 긴 대화가 필요하다면 팀에 문의하세요.

다음 단계

JavaScript SDK 레퍼런스

JavaScript SDK의 클래스, 메서드 및 이벤트를 확인하세요.

Python SDK 레퍼런스

Python SDK의 클래스, 메서드 및 이벤트를 확인하세요.

API 레퍼런스

모든 Speech Engine 파라미터와 응답 형식을 살펴보세요.

Next.js 예제 앱

완전한 Speech Engine 빠른 시작 앱을 로컬에서 실행하세요.