Terminal
Terminal/Skill
Symptom based fixes for LiveAvatar integrations with a silent avatar, garbled audio, failed sessions or API errors.
By HeyGen
Works with
npx skills add heygen-com/liveavatar-agent-skills --skill liveavatar-debugSymptom-based troubleshooting for LiveAvatar integrations. Find your symptom below and follow the fix.
Most likely: Missing context_id in FULL Mode.
Without a context_id, the avatar enters restricted mode — streams video but ignores user input. No error thrown.
Fix: Create a context via POST /v1/contexts with at least a prompt field. Include the returned context_id in your session token's avatar_persona.
Other causes:
allow="microphone" on iframe)Most likely: Wrong audio format.
Required: PCM 16-bit signed, 24KHz, base64. No error returned for wrong format.
Checklist:
Quick test: Send a known-good 440Hz test tone. If it works but your TTS doesn't, resample your TTS output.
Most likely: Wrong auth header.
| Endpoint | Correct auth |
|---|---|
POST /v1/sessions/token | X-API-KEY: <api_key> |
POST /v1/sessions/start | Authorization: Bearer <session_token> |
Common mistakes: using API key on /start, using Bearer token on /token, putting API key in Bearer format.
agent-control, receive from agent-responseevent_type, event_id, session_idMost likely: Sending before connected.
Wait for {"type": "session.state_updated", "state": "connected"} before sending any commands.
Also check:
agent.*, not avatar.* (that's FULL)5 minutes of inactivity kills the session.
POST /v1/sessions/keep-alive with Bearer <session_token>{"type": "session.keep_alive", "event_id": "..."} via WebSocketSend every 2-3 minutes.
is_sandbox: true set in session tokendd73ea75-1218-4ef3-92ce-606d5f7fbc0a (sessions) or 65f9e3c9-d48b-4118-b73a-4ae2e3cbb8f0 (embeds)~1 minute auto-termination is expected behavior.
Image avatars have no auto-generated voice. Specify voice_id in avatar_persona. Browse voices at GET /v1/voices.
LLM checklist:
secret_type: "LLM_API_KEY"model, secret_id, base_urlllm_configuration_id in session token/chat/completions protocolTTS checklist:
secret_type: "ELEVENLABS_API_KEY"POST /v1/voices/third_partywss:// for LiveKit and WebSocket*.livekit.cloud, api.liveavatar.com, embed.liveavatar.comGET /v1/sessions/{id}GET /v1/sessions/{id}/transcriptGET /v1/users/credits