Python SDK 레퍼런스 | ElevenLabs Documentation

이 페이지에서는 Speech Engine Python SDK(elevenlabs)의 공개 API를 설명합니다.

Speech Engine 리소스 가져오기

엔진 ID로 SpeechEngineResource를 가져옵니다. 반환된 객체는 서버 시작, 요청 검증 또는 개별 세션 생성 메서드를 제공합니다.

from elevenlabs import AsyncElevenLabs
elevenlabs = AsyncElevenLabs()
engine = await elevenlabs.speech_engine.get("seng_8k3m9xr4hjnfg983brhmhkd98n6")

SpeechEngineResource

속성

속성	유형	설명
`engine_id`	`str`	음성 엔진의 ID입니다.

serve

독립형 WebSocket 서버를 시작합니다. 중지될 때까지 실행됩니다.

await engine.serve(
    port=3001,
    path="/ws",
    debug=True,
    on_transcript=handle_transcript,
)

매개변수	유형	기본값	설명
`port`	`int`	`3001`	수신 대기할 포트입니다.
`path`	`str`	`None`	연결을 이 경로로 제한합니다. `None`은 모든 연결을 허용합니다.
`debug`	`bool`	`False`	stdout에 디버그 로그를 활성화합니다.
`disable_auth`	`bool`	`False`	수신 연결의 JWT 검증을 건너뜁니다. 인증 비활성화를 참조하세요.
`on_init`	`callable`		세션이 초기화될 때 호출됩니다.
`on_transcript`	`callable`		사용자 트랜스크립트가 도착할 때 호출됩니다.
`on_close`	`callable`		정상 연결 해제 시 호출됩니다.
`on_disconnect`	`callable`		WebSocket 연결이 예기치 않게 끊길 때 호출됩니다.
`on_error`	`callable`		프로토콜 또는 WebSocket 오류 시 호출됩니다.

인증 비활성화

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

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

인증을 비활성화하면 서버는 연결 가능한 모든 클라이언트를 허용하며, 시작 시 UserWarning을 발생시킵니다.

서버 앞에 IP 허용 목록, 맞춤 헤더 값 또는 이에 준하는 네트워크 수준 제한이 있는 경우에만 disable_auth=True를 사용하세요. 이러한 제한이 없으면 인터넷의 누구나 세션을 열어 컴퓨팅 리소스와 다운스트림 LLM 할당량을 소진할 수 있습니다.

verify_request

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

WebSocket 업그레이드를 직접 관리할 때만 필요합니다. serve()를 사용할 때는 검증이 자동으로 처리됩니다(disable_auth=True를 설정한 경우 제외).

is_valid = engine.verify_request(headers)

매개변수	유형	설명
`headers`	`dict`	요청 헤더 딕셔너리입니다.

반환값: bool — 요청이 유효하면 True입니다.

create_session

수락된 WebSocket을 SpeechEngineSession으로 래핑합니다. 맞춤 서버 통합(예: FastAPI, Starlette 또는 수동 WebSocket 처리)에 사용하세요.

session = engine.create_session(websocket, debug=True)
session.on("user_transcript", handle_transcript)
await session.run()

매개변수	유형	기본값	설명
`ws`	WebSocket		수락된 WebSocket 연결입니다.
`debug`	`bool`	`False`	디버그 로깅을 활성화합니다.

반환값: SpeechEngineSession

SpeechEngineSession

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

새 트랜스크립트가 도착하면 이전 트랜스크립트 핸들러는 자동으로 취소되어 진행 중인 LLM 호출이 중단됩니다.

속성

속성	유형	설명
`conversation_id`	`Optional[str]`	API가 할당한 대화 ID입니다. `init` 후 사용할 수 있습니다.
`is_open`	`bool`	세션이 아직 열려 있는지 여부입니다.

on

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

session.on("user_transcript", handler)

off

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

session.off("user_transcript", handler)

once

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

session.once("init", handler)

send_response

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

# 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)

매개변수	유형	설명
`response`	`str` \| async iterable	완전한 문자열 또는 텍스트 청크/LLM 스트림 이벤트의 비동기 이터러블입니다.

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

제공업체	이벤트 형식
OpenAI Responses API	`{ type: "response.output_text.delta", delta: "text" }`
OpenAI Chat Completions	`{ choices: [{ delta: { content: "text" } }] }`
Anthropic Messages API	`{ type: "content_block_delta", delta: { type: "text_delta", text: "text" } }`
Google Gemini API	`{ candidates: [{ content: { parts: [{ text: "text" }] } }] }`

run

WebSocket이 닫힐 때까지 수신 루프를 실행합니다. create_session()을 통해 세션을 수동으로 생성한 후의 기본 진입점입니다.

session = engine.create_session(websocket)
session.on("user_transcript", handle_transcript)
await session.run()

close

세션과 기본 WebSocket 연결을 닫습니다.

session.close()

콜백

serve()에 전달하는 키워드 인수입니다. 모든 콜백은 선택 사항입니다. 핸들러는 동기 함수 또는 비동기(코루틴) 함수일 수 있습니다.

콜백	시그니처	설명
`on_init`	`(conversation_id: str, session) -> None`	대화 ID로 세션이 초기화되었습니다.
`on_transcript`	`(transcript: list, session) -> None`	사용자 음성이 트랜스크립션되었습니다.
`on_close`	`(session) -> None`	ElevenLabs에서 정상 연결 해제되었습니다.
`on_disconnect`	`(session) -> None`	WebSocket 연결이 예기치 않게 끊겼습니다.
`on_error`	`(error: Exception, session) -> None`	프로토콜 또는 WebSocket 오류입니다.

이벤트

콜백 대신 session.on()을 직접 사용하는 경우, 다음은 이벤트 이름과 해당 핸들러 시그니처입니다.

이벤트	핸들러 시그니처
`user_transcript`	`(transcript: list[ConversationMessage])`
`init`	`(conversation_id: str)`
`close`	`()`
`disconnected`	`()`
`error`	`(error: Exception)`

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

from elevenlabs.speech_engine import USER_TRANSCRIPT, INIT, CLOSE, DISCONNECTED, ERROR
session.on(USER_TRANSCRIPT, handle_transcript)

ConversationMessage

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

속성	유형	설명
`role`	`"user"` \| `"agent"`	메시지를 보낸 주체입니다.
`content`	`str`	메시지의 텍스트 내용입니다.

와이어 프로토콜

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

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

메시지 유형	필드	설명
`init`	`conversation_id: string`	세션이 초기화되었습니다.
`user_transcript`	`user_transcript: TranscriptMessage[]`, `event_id: number`	사용자 음성이 트랜스크립션되었습니다.
`ping`		연결 유지입니다. SDK가 pong으로 응답합니다.
`close`		정상 연결 해제입니다.
`error`	`message: string`	API에서 발생한 오류입니다.

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

메시지 유형	필드	설명
`agent_response`	`content: string`, `event_id: number`, `is_final: boolean`	TTS 합성을 위한 LLM 응답 청크입니다.
`pong`		ping에 대한 응답입니다.