quality

string

The quality of the data to be retrieved. Can be "high", "medium", or "low".
high: 2000kbps and 720p.
medium: 1000kbps and 480p.
low: 500kbps and 360p.

avatar_id

string (optional)

The ID of the Interactive Avatar to use. If not provided, a default avatar will be chosen. Default: default

voice

VoiceSetting(optional)

The settings for the Interactive Avatar's voice.

stt_settings

STTSetting(optional) beta

The speech-to-text settings control how audio is converted into text.

video_encoding

string (optional)

Specifies the encoding format for streaming video. Can be "H264", "VP8". Default: VP8.
Note: Choosing "H264" may offer better compatibility with certain devices and platforms.

knowledge_base

string (optional)

Knowledge Base prompt used for chat task type.

version

string (optional) beta

Specifies the version to use. Currently, the only valid value is v2.
Default: Not specified (uses v1).

knowledge_base_id

string (optional) beta

The ID of the knowledge base to use for the avatar's responses. Only applicable when version is set to v2.

disable_idle_timeout

boolean(optional)

By default session has a 2 minute idle timeout, setting to true disables it.
⚠️ Do not use this feature without proper session management, as open sessions can consume your API credits!

activity_idle_timeout

integer(optional)

Specifies the maximum idle time in seconds allowed after the last user activity before the session is considered inactive. Default value: 120 seconds. Min value: 30 seconds, Max value: 3600 seconds.

livekit_settings

LiveKitSettings (optional) beta

Settings for connecting to your own LiveKit instance. ⚠️ Only provide this if you are using your own LiveKit, not HeyGen-managed LiveKit.

provider

string (optional) beta

STT model. Allowed values: deepgram, gladia, assembly_ia. assembly_aiis default provider for English language transcription.

confidence

float(optional)

Default is 0.55.

code

integer

The response status code.

message

string

A message providing more details about the request's result, typically explaining success or error.

data

object

Contains the main data for the response.

data.session_id

string

A unique identifier for the session.

data.url

string

The WebSocket URL for accessing the LiveKit room (e.g., wss://heygen-feapbkvq.livekit.cloud).

data.access_token

string

The access token required to authenticate and join the LiveKit room.

data.session_duration_limit

integer

The maximum allowed duration (in seconds) for the session, indicating any session time limits.

data.is_paid

boolean

A flag indicating whether the session is part of a paid plan.

data.realtime_endpoint

string

The real-time endpoint URL for alpha implementations, which could be used for experimental features (e.g., wss://webrtc-signaling.heygen.io/v2-alpha/...).

data.livekit_agent_token

string

Only returned when using HeyGen-managed LiveKit. This token is for HeyGen’s audio agents (e.g., Pipecat / LiveKit Agent) to join the room and provide audio services. Not needed when using your own LiveKit instance.