Create Avatar Realtime Session

Start a low-latency streaming avatar session and return a stream_id. Three modes, selected by the type discriminator: tts (speak a fixed script), audio (drive lip-sync from a pre-existing audio asset), and text_stream (seed with initial text, then append more text deltas over time via POST /v3/avatar-realtime//text — e.g. as an upstream LLM streams tokens). Poll GET /v3/avatar-realtime/ for the session status and HLS playback URL.

POST /v3/avatar-realtime

Create Avatar Realtime Session

cURL

curl --request POST \
  --url https://api.heygen.com/v3/avatar-realtime \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "type": "<string>",
  "avatar_id": "<string>",
  "text": "<string>",
  "voice_id": "<string>"
}
'

201

{
  "data": {
    "stream_id": "<string>"
  }
}

Authorizations

ApiKeyAuthBearerAuth

x-api-key · string · header · required

HeyGen API key. Obtain from your HeyGen dashboard.

Body

application/json

CreateAvatarRealtimeTTS

CreateAvatarRealtimeAudio

CreateAvatarRealtimeTextStream

Create a stream with text-to-speech audio.

type · string · required

Audio source type: text-to-speech.

Allowed value: "tts"

avatar_id · string · required

HeyGen photo avatar or motion avatar look ID.

text · string · required

Text script for the avatar to speak.

Minimum string length: 1

voice_id · string · required

Voice ID for text-to-speech.

Response

201

application/json

Created.

data · CreateAvatarRealtimeResponse · object

Response data for POST /v3/avatar-realtime.

Show child attributes