Skip to main content

HeyGen LiveAvatar

HeyGen LiveAvatar provides real-time, interactive avatar streaming with high-quality lip-sync.

Setup​

1. Get API Access​

  1. Go to HeyGen
  2. Sign up for an API plan (starts at $99/mo)
  3. Navigate to API Settings
  4. Copy your API key

2. Select an Avatar​

  1. In HeyGen dashboard, go to Avatars
  2. Choose a public avatar or create custom
  3. Copy the Avatar ID

3. Select a Voice​

  1. Navigate to Voices
  2. Choose a voice that matches your avatar
  3. Copy the Voice ID

4. Configure Environment​

LIVEAVATAR_API_KEY=your-heygen-api-key
NEXT_PUBLIC_AVATAR_ID=Pedro_Blue_Shirt_public
NEXT_PUBLIC_VOICE_ID=your-voice-id

Configuration Options​

# Required
LIVEAVATAR_API_KEY=...
NEXT_PUBLIC_AVATAR_ID=...
NEXT_PUBLIC_VOICE_ID=...

# Optional
NEXT_PUBLIC_CONTEXT_ID=...        # For conversation context

Pricing​

HeyGen uses a credit-based system:

TierCredit CostEffective $/min
Pro$0.99/credit$0.198/min
Scale$0.50/credit$0.10/min

1 credit = 5 minutes of streaming (API mode)

Session Costs​

DurationPro TierScale Tier
30 sec (min)$0.099$0.05
1 minute$0.198$0.10
3 minutes$0.594$0.30
5 minutes$0.99$0.50
Minimum Charge

Sessions have a 30-second minimum charge. After that, billing is per-second.

Avatar Options​

Public Avatars​

Pre-made professional avatars available immediately:

  • Various appearances (gender, ethnicity, attire)
  • Professional settings (office, studio)
  • Free to use with API

Custom Avatars​

Create from your own footage:

  • Upload video of a person speaking
  • HeyGen creates a digital clone
  • Additional cost may apply

Photo Avatars​

Generate from a still image:

  • Upload a high-quality photo
  • AI generates movement and lip-sync
  • Quick setup, lower quality than video

Best Practices​

Optimize Session Usage​

// End session when user is done
await endSession(sessionId);

Handle Network Issues​

  • Implement reconnection logic
  • Cache partial responses
  • Graceful degradation to text

Monitor Usage​

  • Track session duration in analytics
  • Set alerts for unusual usage
  • Review monthly spend

Troubleshooting​

"Invalid API key"​

  • Verify key at HeyGen dashboard
  • Check for plan/quota limits
  • Ensure key has API permissions

Avatar not loading​

  • Check network connectivity
  • Verify avatar ID is correct
  • Check browser console for errors

Audio/video sync issues​

  • Usually network-related
  • Try reducing video quality
  • Check client bandwidth

Session Architecture​

SmarterAvatar uses a hybrid approach:

  1. Server creates session and gets token
  2. Client connects directly to HeyGen with token
  3. Server sends text to be spoken
  4. Client receives video stream

This keeps API keys secure while enabling real-time streaming.