LiveAvatar
Learn how to integrate ElevenAgents with HeyGen’s LiveAvatar for real-time avatar streaming
Overview
Section titled “Overview”The LiveAvatar integration connects ElevenAgents with HeyGen’s LiveAvatar platform to create interactive avatar experiences. This integration combines ElevenLabs Agents (handling audio interactions) with LiveAvatar’s real-time avatar video streaming, enabling low-latency visual conversations with AI avatars.
With this integration you can:
- Deploy conversational AI agents with visual avatar representation
- Create interactive customer service experiences with lifelike avatars
- Build engaging virtual assistants for websites and applications
How it works
Section titled “How it works”The integration uses LiveAvatar’s LITE session mode where responsibilities are divided between the two platforms:
- ElevenLabs: Handles the streaming and orchestration of audio input and output
- LiveAvatar: Manages avatar rendering and real-time video streaming
When a LITE mode session starts with an ElevenAgents configuration, LiveAvatar dispatches a worker that connects to your ElevenLabs agent. The agent’s audio output drives the avatar’s lip sync and animations in real-time.
Prerequisites
Section titled “Prerequisites”Before setting up the integration, ensure you have:
- An ElevenLabs account with API access
- A HeyGen LiveAvatar account with API access
- An ElevenLabs agent (create one following the quickstart guide)
Obtain your ElevenLabs credentials
You need two items from your ElevenLabs account:
- Agent ID: Navigate to Agents Platform > Agents and copy the ID of the agent you want to use
- API Key: Go to Settings > API Keys and generate a new API key (or use an existing one)
Register your ElevenLabs API key with LiveAvatar
LiveAvatar requires your ElevenLabs API key to be registered through their secrets endpoint. This registration encrypts your key using Amazon KMS and returns a
secret_idfor use in sessions.Make a POST request to LiveAvatar’s secrets endpoint:
Bash curl -X POST "https://api.liveavatar.com/v1/secrets" \ -H "Content-Type: application/json" \ -H "X-Api-Key: <your_heygen_api_key>" \ -d '{ "secret_type": "ELEVENLABS_API_KEY", "secret_value": "<your_secret_value>", "secret_name": "<your_secret_name>" }'The response contains your
secret_id. Store thissecret_idfor use when starting sessions.Start a LiveAvatar session
When starting a LiveAvatar session, use LITE mode and include your ElevenAgents configuration:
JSON { "mode": "LITE", "elevenlabs_agent_config": { "secret_id": "xxxxxxxxxxxxxxxx", "agent_id": "agent_xxxxxxxxxxxxxxxx" }, "avatar_id": "xxxxx" }Refer to the LiveAvatar session API documentation for complete details on session management.
Events and callbacks
Section titled “Events and callbacks”The integration delivers events through LiveKit rooms, using the same event structure as LiveAvatar’s FULL mode. This allows you to:
- Monitor conversation state changes
- Track agent speaking and listening modes
- Handle connection and disconnection events
- Process transcriptions and agent responses
Configure your event handlers according to the LiveAvatar events documentation.
Billing
Section titled “Billing”This integration involves separate billing from both platforms:
| Component | Billing |
|---|---|
| LiveAvatar (avatar video) | 1 credit per session minute |
| ElevenLabs (conversational AI) | Billed to your ElevenLabs account based on your subscription plan |
The avatar streaming is billed only for the video component, while all agents usage (audio and LLM) is charged separately through your ElevenLabs account.