api_liveavatar

LiveAvatar API.

API to communicate with LiveAvatar Streaming API.

class pipecat.services.heygen.api_liveavatar.AvatarPersona(*, voice_id: str | None = None, context_id: str | None = None, language: str = 'en')[source]

Bases: BaseModel

Avatar persona settings for LiveAvatar.

Parameters:

voice_id (Optional[str]) – ID of the voice to be used.
context_id (Optional[str]) – Context ID for the avatar.
language (str) – Language code for the avatar (default: “en”).

voice_id: str | None

context_id: str | None

language: str

class pipecat.services.heygen.api_liveavatar.CustomSDKLiveKitConfig(*, livekit_url: str, livekit_room: str, livekit_client_token: str)[source]

Bases: BaseModel

Custom LiveKit configuration.

Parameters:

livekit_url (str) – LiveKit server URL.
livekit_room (str) – LiveKit room name.
livekit_client_token (str) – LiveKit client access token.

livekit_url: str

livekit_room: str

livekit_client_token: str

class pipecat.services.heygen.api_liveavatar.VideoEncoding(*values)[source]

Bases: StrEnum

Enum representing the video encoding.

H264 = 'H264'

VP8 = 'VP8'

class pipecat.services.heygen.api_liveavatar.VideoQuality(*values)[source]

Bases: StrEnum

Enum representing different avatar quality levels.

low = 'low'

medium = 'medium'

high = 'high'

very_high = 'very_high'

class pipecat.services.heygen.api_liveavatar.VideoSettings(*, encoding: VideoEncoding, quality: VideoQuality = VideoQuality.high)[source]

Bases: BaseModel

Video encoding settings for session configuration.

encoding: VideoEncoding

quality: VideoQuality

class pipecat.services.heygen.api_liveavatar.LiveAvatarNewSessionRequest(*, mode: str = 'LITE', avatar_id: str, video_settings: VideoSettings | None = VideoSettings(encoding=<VideoEncoding.VP8: 'VP8'>, quality=<VideoQuality.high: 'high'>), is_sandbox: bool | None = False, avatar_persona: AvatarPersona | None = None, livekit_config: CustomSDKLiveKitConfig | None = None)[source]

Bases: BaseModel

Request model for creating a LiveAvatar session token.

Parameters:

mode (str) – Session mode (default: “LITE”).
avatar_id (str) – Unique identifier for the avatar.
video_settings (VideoSettings) – Video encoding settings.
is_sandbox (bool) – Enable sandbox mode (default: False).
avatar_persona (AvatarPersona) – Avatar persona configuration.
livekit_config (CustomSDKLiveKitConfig) – Custom LiveKit configuration.

mode: str

avatar_id: str

video_settings: VideoSettings | None

is_sandbox: bool | None

avatar_persona: AvatarPersona | None

livekit_config: CustomSDKLiveKitConfig | None

class pipecat.services.heygen.api_liveavatar.SessionTokenData(*, session_id: str, session_token: str)[source]

Bases: BaseModel

Data model for session token response.

Parameters:

session_id (str) – Unique identifier for the session.
session_token (str) – Session token for authentication.

session_id: str

session_token: str

class pipecat.services.heygen.api_liveavatar.SessionTokenResponse(*, code: int, data: SessionTokenData, message: str)[source]

Bases: BaseModel

Response model for LiveAvatar session token.

Parameters:

code (int) – Response status code.
data (SessionTokenData) – Session token data containing session_id and session_token.
message (str) – Response message.

code: int

data: SessionTokenData

message: str

class pipecat.services.heygen.api_liveavatar.LiveAvatarSessionData(*, session_id: str, livekit_url: str, livekit_client_token: str, livekit_agent_token: str, max_session_duration: int, ws_url: str)[source]

Bases: BaseModel

Data model for LiveAvatar session response.

Parameters:

session_id (str) – Unique identifier for the streaming session.
livekit_url (str) – LiveKit server URL for the session.
livekit_client_token (str) – Access token for LiveKit user.
livekit_agent_token (str) – Access token for LiveKit Agent (Pipecat).
max_session_duration (int) – Maximum session duration in seconds.
ws_url (str) – WebSocket URL for the session.

session_id: str

livekit_url: str

livekit_client_token: str

livekit_agent_token: str

max_session_duration: int

ws_url: str

class pipecat.services.heygen.api_liveavatar.LiveAvatarSessionResponse(*, code: int, data: LiveAvatarSessionData, message: str)[source]

Bases: BaseModel

Response model for LiveAvatar session start.

Parameters:

code (int) – Response status code.
data (LiveAvatarSessionData) – Session data containing connection details.
message (str) – Response message.

code: int

data: LiveAvatarSessionData

message: str

exception pipecat.services.heygen.api_liveavatar.LiveAvatarApiError(message: str, status: int, response_text: str)[source]

Bases: Exception

Custom exception for LiveAvatar API errors.

__init__(message: str, status: int, response_text: str) → None[source]

Initialize the LiveAvatar API error.

Parameters:

message – Error message
status – HTTP status code
response_text – Raw response text from the API

class pipecat.services.heygen.api_liveavatar.LiveAvatarApi(api_key: str, session: ClientSession)[source]

Bases: BaseAvatarApi

LiveAvatar Streaming API client.

BASE_URL = 'https://api.liveavatar.com/v1'

__init__(api_key: str, session: ClientSession) → None[source]

Initialize the LiveAvatar API.

Parameters:

api_key – LiveAvatar API key
session – aiohttp client session

async create_session_token(request_data: LiveAvatarNewSessionRequest) → SessionTokenResponse[source]

Create a session token for LiveAvatar.

https://docs.liveavatar.com/reference/create_session_token_v1_sessions_token_post

Parameters:: request_data – Session token configuration parameters.
Returns:: Session token information.

async start_session(session_token: str) → LiveAvatarSessionResponse[source]

Start a new LiveAvatar session.

https://docs.liveavatar.com/reference/start_session_v1_sessions_start_post

Parameters:: session_token – Session token obtained from create_session_token.
Returns:: Session information including room URL and session ID.

async stop_session(session_id: str, session_token: str) → Any[source]

Stop an active LiveAvatar session.

https://docs.liveavatar.com/reference/stop_session_v1_sessions_stop_post

Parameters:

session_id – ID of the session to stop.
session_token – Session token for authentication.

Returns:

Response data from the stop session API call.

Raises:

ValueError – If session ID is not set.

async new_session(request_data: LiveAvatarNewSessionRequest) → StandardSessionResponse[source]

Create and start a new LiveAvatar session (convenience method).

This combines create_session_token and start_session into a single call.

Parameters:: request_data – Session token configuration parameters.
Returns:: Standardized session information with LiveAvatar raw response.
Return type:: StandardSessionResponse

async close_session(session_id: str) → Any[source]

Close an active LiveAvatar session (convenience method).

This is a convenience method that closes a session using the stored session token from the most recent new_session() call. It automatically uses the internally stored session token, eliminating the need to manually track tokens.

Parameters:: session_id – ID of the session to close.
Returns:: Response data from the stop session API call.
Raises:: ValueError – If no session token is available (i.e., new_session() hasn’t been called yet or the stored token is None).

Note

This method requires that new_session() has been called previously to establish a stored session token. For more control over session tokens, use stop_session() directly with an explicit token parameter.