用途：面向 LiveAvatar 集成开发者，按症状提供排障与修复指引。
主要能力与要点： 头像静音：FULL 模式最常见原因是缺少 context_id，会进入受限模式（只推视频、忽略输入且不报错）。需用 POST /v1/contexts 创建 context（至少含 prompt 字段），并把返回的 context_id 放入会话令牌的 avatar_persona。其他原因包括浏览器麦克风权限被拦（检查 iframe 的 allow="microphone"）、启用 Push-to-Talk 但未发送 PTT 事件、系统级麦克风静音。 音频失真（LITE 模式）：多为音频格式错误，要求 PCM 16 位有符号、24KHz、base64，格式错误不报错。检查采样率恰为 24,000 Hz、原始 PCM（无 WAV/MP3/OGG 头）、16 位有符号、base64 编码、分块小于 1MB。可用 440Hz 测试音验证。 401/会话启动失败：POST /v1/sessions/token 用 X-API-KEY: <api_key>；POST /v1/sessions/start 用 Authorization: Bearer <session_token>，勿混用。 FULL 模式收不到事件：确认订阅主题（发往 agent-control、从 agent-response 接收）、LiveKit 房间已连接、正确解析含 event_type、event_id、session_id 的 JSON。 LITE 模式 WebSocket 事件被丢弃：需先等到 {"type": "session.state_updated", "state": "connected"} 再发送命令；事件名用 agent.（非 FULL 的 avatar.）；注意 5 分钟无活动超时。 会话超时：5 分钟无活动即终止。FULL 用 POST /v1/sessions/keep-alive 带 Bearer <session_token>；LITE 通过 WebSocket 发 {"type": "session.keep_alive", "event_id": "..."}，建议每 2-3 分钟发送。 沙箱无法启动：会话令牌设 is_sandbox: true；头像 ID 为 dd73ea75-1218-4ef3-92ce-606d5f7fbc0a（sessions）或 65f9e3c9-d48b-4118-b73a-4ae2e3cbb8f0（embeds）；约 1 分钟自动终止属预期。 图片头像无音频：图片头像无自动生成语音，需在 avatar_persona 指定 voice_id，可用 GET /v1/voices 浏览。 自定义 LLM/TTS：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。 CORS/网络：API 调用应来自后端而非浏览器；放行 wss:// 及 *.livekit.cloud、api.liveavatar.com、embed.liveavatar.com。
通用排查：先用沙箱模式排除计费问题；用 GET /v1/sessions/{id} 查状态、GET /v1/sessions/{id}/transcript 查转写、GET /v1/users/credits 查额度；确认未混用 FULL 与 LITE 事件体系。
限制：资料未提供具体价格、平台支持范围与更多错误码说明。