Dokumentacja Python SDK | ElevenLabs Documentation

Ta strona dokumentuje publiczne API Python SDK Speech Engine (elevenlabs).

Pobieranie zasobu Speech Engine

Pobierz SpeechEngineResource za pomocą identyfikatora silnika. Zwrócony obiekt udostępnia metody uruchamiania serwera, weryfikowania żądań i tworzenia pojedynczych sesji.

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

SpeechEngineResource

Właściwości

Właściwość	Typ	Opis
`engine_id`	`str`	Identyfikator silnika mowy.

serve

Uruchamia samodzielny serwer WebSocket. Działa do zatrzymania.

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

Parametr	Typ	Domyślnie	Opis
`port`	`int`	`3001`	Port nasłuchiwania.
`path`	`str`	`None`	Ogranicza połączenia do tej ścieżki. `None` akceptuje wszystkie.
`debug`	`bool`	`False`	Włącza logowanie debugowania do stdout.
`disable_auth`	`bool`	`False`	Pomija weryfikację JWT dla połączeń przychodzących. Zobacz Wyłączanie uwierzytelniania.
`on_init`	`callable`		Wywoływane podczas inicjalizacji sesji.
`on_transcript`	`callable`		Wywoływane po otrzymaniu transkrypcji użytkownika.
`on_close`	`callable`		Wywoływane przy poprawnym rozłączeniu.
`on_disconnect`	`callable`		Wywoływane, gdy WebSocket niespodziewanie się rozłączy.
`on_error`	`callable`		Wywoływane przy błędach protokołu lub WebSocket.

Wyłączanie uwierzytelniania

Domyślnie serve() weryfikuje nagłówek X-Elevenlabs-Speech-Engine-Authorization przy każdym połączeniu przychodzącym. Jeśli serwer działa za warstwą infrastruktury, która już ogranicza ruch przychodzący do ElevenLabs (zwykle listą dozwolonych adresów IP dla zakresów wyjściowych ElevenLabs), możesz pominąć weryfikację JWT, przekazując disable_auth=True:

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

Gdy uwierzytelnianie jest wyłączone, serwer akceptuje każdego klienta, który może się z nim połączyć, i przy uruchomieniu emituje UserWarning.

Używaj disable_auth=True tylko, jeśli przed serwerem masz listę dozwolonych adresów IP, własne wartości nagłówków lub równoważne ograniczenie na poziomie sieci. Bez tego każda osoba w internecie może otworzyć sesję i zużyć twoje zasoby obliczeniowe oraz limit po stronie LLM.

verify_request

Weryfikuje, czy żądanie przychodzące pochodzi z API ElevenLabs Speech Engine. Sprawdza nagłówek X-Elevenlabs-Speech-Engine-Authorization pod kątem poprawnego JWT podpisanego hashem SHA-256 twojego klucza API.

Potrzebne tylko wtedy, gdy samodzielnie obsługujesz przejście na WebSocket. Przy użyciu serve() weryfikacja odbywa się automatycznie (chyba że ustawiono disable_auth=True).

is_valid = engine.verify_request(headers)

Parametr	Typ	Opis
`headers`	`dict`	Słownik nagłówków żądania.

Zwraca: bool — True, jeśli żądanie jest poprawne.

create_session

Opakowuje zaakceptowane połączenie WebSocket w SpeechEngineSession. Użyj tego do własnej integracji z serwerem (np. FastAPI, Starlette lub ręcznej obsługi WebSocket).

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

Parametr	Typ	Domyślnie	Opis
`ws`	WebSocket		Zaakceptowane połączenie WebSocket.
`debug`	`bool`	`False`	Włącza logowanie debugowania.

Zwraca: SpeechEngineSession

SpeechEngineSession

Opakowuje pojedyncze połączenie WebSocket. Każde połączenie reprezentuje jedną rozmowę. Sesja emituje zdarzenia dla transkrypcji i zmian cyklu życia oraz udostępnia metody wysyłania odpowiedzi LLM.

Gdy pojawi się nowa transkrypcja, poprzedni handler transkrypcji jest automatycznie anulowany, co przerywa trwające wywołanie LLM.

Właściwości

Właściwość	Typ	Opis
`conversation_id`	`Optional[str]`	Identyfikator rozmowy nadany przez API. Dostępny po `init`.
`is_open`	`bool`	Czy sesja jest nadal otwarta.

on

Rejestruje handler zdarzenia. Zwraca sesję, aby umożliwić łączenie wywołań.

session.on("user_transcript", handler)

off

Usuwa wcześniej zarejestrowany handler.

session.off("user_transcript", handler)

once

Rejestruje handler, który uruchamia się raz, a potem usuwa sam siebie.

session.once("init", handler)

send_response

Wysyła odpowiedź LLM do API Speech Engine w celu syntezy zamiany tekstu na mowę. Musi zostać wywołana wewnątrz handlera on_transcript. Wywołanie poza handlerem emituje ostrzeżenie i kończy się bez wysłania odpowiedzi.

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

Parametr	Typ	Opis
`response`	`str` \| async iterable	Pełny ciąg znaków lub asynchroniczny iterowalny obiekt z fragmentami tekstu / zdarzeniami streamu LLM.

SDK automatycznie wykrywa i wyodrębnia tekst z poniższych formatów streamu LLM:

Dostawca	Format zdarzenia
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

Uruchamia pętlę odbierania, aż WebSocket się zamknie. To główny punkt wejścia po ręcznym utworzeniu sesji przez create_session().

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

close

Zamyka sesję i bazowe połączenie WebSocket.

session.close()

Callbacki

Argumenty nazwane przekazywane do serve(). Wszystkie callbacki są opcjonalne. Handlery mogą być synchronicznymi lub asynchronicznymi funkcjami (korutynami).

Callback	Sygnatura	Opis
`on_init`	`(conversation_id: str, session) -> None`	Sesja zainicjalizowana z identyfikatorem rozmowy.
`on_transcript`	`(transcript: list, session) -> None`	Mowa użytkownika została przetranskrybowana.
`on_close`	`(session) -> None`	Poprawne rozłączenie z ElevenLabs.
`on_disconnect`	`(session) -> None`	WebSocket niespodziewanie się rozłączył.
`on_error`	`(error: Exception, session) -> None`	Błąd protokołu lub WebSocket.

Zdarzenia

Przy bezpośrednim użyciu session.on() zamiast callbacków, poniżej znajdziesz nazwy zdarzeń i sygnatury ich handlerów.

Zdarzenie	Sygnatura handlera
`user_transcript`	`(transcript: list[ConversationMessage])`
`init`	`(conversation_id: str)`
`close`	`()`
`disconnected`	`()`
`error`	`(error: Exception)`

Stałe nazw zdarzeń są dostępne do użycia z kontrolą typów:

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

ConversationMessage

Pojedyncza wiadomość w historii rozmowy. Pełna transkrypcja jest przekazywana do on_transcript w każdej turze.

Właściwość	Typ	Opis
`role`	`"user"` \| `"agent"`	Kto wysłał wiadomość.
`content`	`str`	Treść tekstowa wiadomości.

Protokół komunikacji

Dla odniesienia: są to komunikaty JSON wymieniane przez połączenie WebSocket. SDK automatycznie obsługuje serializację i deserializację.

Przychodzące (API ElevenLabs do serwera dewelopera)

Typ komunikatu	Pola	Opis
`init`	`conversation_id: string`	Sesja zainicjalizowana.
`user_transcript`	`user_transcript: TranscriptMessage[]`, `event_id: number`	Mowa użytkownika została przetranskrybowana.
`ping`		Utrzymanie połączenia. SDK odpowiada pong.
`close`		Poprawne rozłączenie.
`error`	`message: string`	Błąd z API.

Wychodzące (serwer dewelopera do API ElevenLabs)

Typ komunikatu	Pola	Opis
`agent_response`	`content: string`, `event_id: number`, `is_final: boolean`	Fragment odpowiedzi LLM do syntezy TTS.
`pong`		Odpowiedź na ping.