liveavatar-debug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

LiveAvatar Debugging Guide

LiveAvatar 调试指南

Symptom-based troubleshooting for LiveAvatar integrations. Find your symptom below and follow the fix.

针对LiveAvatar集成的基于症状的排查指南，在下方找到你遇到的问题症状并按照修复方案操作。

Avatar is silent / not responding to speech

虚拟形象无声音/不回应语音

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:

Browser mic permissions blocked (check
```
allow="microphone"
```
on iframe)
Push-to-Talk enabled but PTT events not being sent
OS-level mic mute

最可能原因：FULL Mode 中缺失
context_id
参数

缺少

context_id

时，虚拟形象会进入受限模式——正常推流视频但会忽略用户输入，不会抛出任何错误。

修复方案： 通过

POST /v1/contexts

接口创建上下文，请求中至少包含

prompt

字段。将接口返回的

context_id

填入会话令牌的

avatar_persona

字段中。

其他可能原因：

浏览器麦克风权限被阻止（检查iframe上的
```
allow="microphone"
```
属性配置）
开启了按键说话功能但未发送PTT事件
系统层面麦克风被静音

Audio is garbled or distorted (LITE Mode)

音频失真或有杂音（LITE Mode）

401 error / session fails to start

401错误/会话无法启动

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.

最可能原因：认证头配置错误

端点	正确认证方式
`POST /v1/sessions/token`	`X-API-KEY: <api_key>`
`POST /v1/sessions/start`	`Authorization: Bearer <session_token>`

常见错误：在

/start

接口使用API密钥，在

/token

接口使用Bearer令牌，将API密钥按Bearer格式拼接。

Events not received (FULL Mode)

接收不到事件（FULL Mode）

Subscribed to correct topics? Send to
```
agent-control
```
, receive from
```
agent-response
```
LiveKit room connected? Check connection state
Parsing JSON correctly? Events have
```
event_type
```
,
```
event_id
```
,
```
session_id
```

是否订阅了正确的主题？向
```
agent-control
```
发送事件，从
```
agent-response
```
接收事件
LiveKit房间是否已连接？检查连接状态
JSON解析是否正确？事件包含
```
event_type
```
、
```
event_id
```
、
```
session_id
```
字段

WebSocket events silently dropped (LITE Mode)

WebSocket事件被静默丢弃（LITE Mode）

Most likely: Sending before
connected
.

Wait for

{"type": "session.state_updated", "state": "connected"}

before sending any commands.

Also check:

Using correct event names? LITE uses
```
agent.*
```
, not
```
avatar.*
```
(that's FULL)
WebSocket still open? 5-min inactivity timeout

最可能原因：在连接建立完成前发送数据

请等待收到

{"type": "session.state_updated", "state": "connected"}

事件后再发送任何命令。

其他检查项：

是否使用了正确的事件名？LITE模式使用
```
agent.*
```
前缀，而非
```
avatar.*
```
（该前缀是FULL模式使用）
WebSocket连接是否仍处于开启状态？无操作5分钟会自动超时

Session times out

会话超时

5 minutes of inactivity kills the session.

FULL:

POST /v1/sessions/keep-alive

with

Bearer <session_token>

LITE:

{"type": "session.keep_alive", "event_id": "..."}

via WebSocket

Send every 2-3 minutes.

5分钟无操作会自动终止会话。

FULL模式： 携带

Bearer <session_token>

请求

POST /v1/sessions/keep-alive

接口

LITE模式： 通过WebSocket发送

{"type": "session.keep_alive", "event_id": "..."}

建议每2-3分钟发送一次心跳请求。

Sandbox won't start

沙箱环境无法启动

```
is_sandbox: true
```
set in session token

Avatar ID is

dd73ea75-1218-4ef3-92ce-606d5f7fbc0a

(sessions) or

65f9e3c9-d48b-4118-b73a-4ae2e3cbb8f0

(embeds)

Not using a different avatar with sandbox mode

~1 minute auto-termination is expected behavior.

会话令牌中已设置
```
is_sandbox: true
```

虚拟形象ID为

dd73ea75-1218-4ef3-92ce-606d5f7fbc0a

（会话场景）或

65f9e3c9-d48b-4118-b73a-4ae2e3cbb8f0

（嵌入场景）

沙箱模式下未使用其他虚拟形象ID

约1分钟自动终止是沙箱环境的预期行为。

Image avatar fails / no audio

图片虚拟形象运行失败/无音频

Image avatars have no auto-generated voice. Specify

voice_id

avatar_persona

. Browse voices at

GET /v1/voices

图片虚拟形象不会自动生成语音，请在

avatar_persona

中指定

voice_id

。可通过

GET /v1/voices

接口查询可用音色列表。

Custom LLM / TTS not working

自定义LLM/TTS无法正常工作

LLM checklist:

Secret:
```
secret_type: "LLM_API_KEY"
```
Config: correct
```
model
```
,
```
secret_id
```
,
```
base_url
```
```
llm_configuration_id
```
in session token
Endpoint supports OpenAI
```
/chat/completions
```
protocol

TTS checklist:

Secret:
```
secret_type: "ELEVENLABS_API_KEY"
```
Voice imported via
```
POST /v1/voices/third_party
```
Using the returned LiveAvatar voice_id (not the ElevenLabs ID)

LLM检查清单：

密钥配置：
```
secret_type: "LLM_API_KEY"
```
配置项：
```
model
```
、
```
secret_id
```
、
```
base_url
```
配置正确
会话令牌中已传入
```
llm_configuration_id
```
端点支持OpenAI
```
/chat/completions
```
协议

TTS检查清单：

密钥配置：
```
secret_type: "ELEVENLABS_API_KEY"
```
音色已通过
```
POST /v1/voices/third_party
```
接口导入
使用接口返回的LiveAvatar voice_id（而非ElevenLabs的ID）

CORS / network errors

CORS/网络错误

API calls should come from backend, not browser
Allow outbound
```
wss://
```
for LiveKit and WebSocket

Allow

*.livekit.cloud

api.liveavatar.com

embed.liveavatar.com

API请求应从后端发送，而非浏览器端
允许出站的
```
wss://
```
请求，用于LiveKit和WebSocket连接

放开

*.livekit.cloud

、

api.liveavatar.com

、

embed.liveavatar.com

域名访问限制

General approach

通用排查思路

Start with sandbox mode to eliminate billing issues
Check session state:
```
GET /v1/sessions/{id}
```
Check transcript:
```
GET /v1/sessions/{id}/transcript
```
Check credits:
```
GET /v1/users/credits
```
Verify you're not mixing FULL and LITE event systems

先使用沙箱模式排查，排除计费相关问题
检查会话状态：
```
GET /v1/sessions/{id}
```
检查会话转写记录：
```
GET /v1/sessions/{id}/transcript
```
检查账户额度：
```
GET /v1/users/credits
```
确认你没有混用FULL和LITE模式的事件体系