api_interactive_avatar

HeyGen API.

API to communicate with HeyGen Streaming API.

class pipecat.services.heygen.api_interactive_avatar.AvatarQuality(*values)[source]

Bases: StrEnum

Enum representing different avatar quality levels.

low = 'low'
medium = 'medium'
high = 'high'
class pipecat.services.heygen.api_interactive_avatar.VideoEncoding(*values)[source]

Bases: StrEnum

Enum representing the video encoding.

H264 = 'H264'
VP8 = 'VP8'
class pipecat.services.heygen.api_interactive_avatar.VoiceEmotion(*values)[source]

Bases: StrEnum

Enum representing different voice emotion types.

EXCITED = 'excited'
SERIOUS = 'serious'
FRIENDLY = 'friendly'
SOOTHING = 'soothing'
BROADCASTER = 'broadcaster'
class pipecat.services.heygen.api_interactive_avatar.ElevenLabsSettings(*, stability: float | None = None, similarity_boost: float | None = None, model_id: str | None = None, style: int | None = None, use_speaker_boost: bool | None = None)[source]

Bases: BaseModel

Settings for ElevenLabs voice configuration.

Parameters:

  • stability (Optional[float]) – Stability of the voice synthesis.

  • similarity_boost (Optional[float]) – Adjustment for similarity in voice performance.

  • model_id (Optional[str]) – Identifier for the ElevenLabs model to use.

  • style (Optional[int]) – Style metric to apply for the voice.

  • use_speaker_boost (Optional[bool]) – Flag to enable speaker boost.

stability: float | None
similarity_boost: float | None
model_id: str | None
style: int | None
use_speaker_boost: bool | None
class pipecat.services.heygen.api_interactive_avatar.VoiceSettings(*, voiceId: str | None = None, rate: float | None = None, emotion: VoiceEmotion | None = None, elevenlabsSettings: ElevenLabsSettings | None = None)[source]

Bases: BaseModel

Voice configuration settings.

Parameters:

  • voice_id (Optional[str]) – ID of the voice to be used.

  • rate (Optional[float]) – Speaking rate for the voice.

  • emotion (Optional[VoiceEmotion]) – Emotion tone for the voice.

  • elevenlabs_settings (Optional[ElevenLabsSettings]) – Details for ElevenLabs configuration.

voice_id: str | None
rate: float | None
emotion: VoiceEmotion | None
elevenlabs_settings: ElevenLabsSettings | None
class pipecat.services.heygen.api_interactive_avatar.NewSessionRequest(*, quality: AvatarQuality | None = None, avatar_id: str | None = None, voice: VoiceSettings | None = None, video_encoding: VideoEncoding | None = None, knowledge_id: str | None = None, knowledge_base: str | None = None, version: Literal['v2'] = 'v2', disable_idle_timeout: bool | None = None, activity_idle_timeout: int | None = None)[source]

Bases: BaseModel

Requesting model for creating a new HeyGen session.

Parameters:

  • quality (Optional[AvatarQuality]) – Desired quality of the avatar.

  • avatar_id (Optional[str]) – Unique identifier for the avatar.

  • voice (Optional[VoiceSettings]) – Voice configurations for the session.

  • video_encoding (Optional[VideoEncoding]) – Desired encoding for the video stream.

  • knowledge_id (Optional[str]) – Identifier for the knowledge base (if applicable).

  • knowledge_base (Optional[str]) – Details of any external knowledge base.

  • version (Literal["v2"]) – API version to use.

  • disable_idle_timeout (Optional[bool]) – Flag to disable automatic idle timeout.

  • activity_idle_timeout (Optional[int]) – Timeout in seconds for activity-based idle detection.

quality: AvatarQuality | None
avatar_id: str | None
voice: VoiceSettings | None
video_encoding: VideoEncoding | None
knowledge_id: str | None
knowledge_base: str | None
version: Literal['v2']
disable_idle_timeout: bool | None
activity_idle_timeout: int | None
class pipecat.services.heygen.api_interactive_avatar.HeyGenSession(*, session_id: str, access_token: str, livekit_agent_token: str, realtime_endpoint: str, url: str)[source]

Bases: BaseModel

Response model for a HeyGen session.

Parameters:

  • session_id (str) – Unique identifier for the streaming session.

  • access_token (str) – Token for accessing the session securely.

  • livekit_agent_token (str) – Token for HeyGen’s audio agents(Pipecat).

  • realtime_endpoint (str) – Real-time communication endpoint URL.

  • url (str) – Direct URL for the session.

session_id: str
access_token: str
livekit_agent_token: str
realtime_endpoint: str
url: str
exception pipecat.services.heygen.api_interactive_avatar.HeygenApiError(message: str, status: int, response_text: str)[source]

Bases: Exception

Custom exception for HeyGen API errors.

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

Initialize the HeyGen API error.

Parameters:

  • message – Error message

  • status – HTTP status code

  • response_text – Raw response text from the API

class pipecat.services.heygen.api_interactive_avatar.HeyGenApi(api_key: str, session: ClientSession)[source]

Bases: BaseAvatarApi

HeyGen Streaming API client.

BASE_URL = 'https://api.heygen.com/v1'
__init__(api_key: str, session: ClientSession) → None[source]

Initialize the HeyGen API.

Parameters:

  • api_key – HeyGen API key

  • session – Optional aiohttp client session

async new_session(request_data: NewSessionRequest) → StandardSessionResponse[source]

Create a new streaming session and start it immediately.

https://docs.heygen.com/reference/new-session

Parameters:

request_data – Session configuration parameters.

Returns:

Standardized session information with HeyGen raw response.

Return type:

StandardSessionResponse

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

Terminate an active the streaming session.

https://docs.heygen.com/reference/close-session

Parameters:

session_id – ID of the session to stop.

Returns:

Response data from the stop session API call.

Raises:

ValueError – If session ID is not set.

async create_token() → str[source]

Create a streaming token.

https://docs.heygen.com/reference/streaming-token

Returns:

The generated access token for the streaming session

Return type:

str