> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# LiveAvatar

## 概述

LiveAvatar 集成将 ElevenAgents 与 HeyGen 的 [LiveAvatar](https://docs.liveavatar.com) 平台连接起来，打造可交互的虚拟形象体验。该集成结合 ElevenLabs Agents（处理音频交互）与 LiveAvatar 的实时虚拟形象视频流，让你能以低延迟方式与 AI 虚拟形象进行视觉对话。

通过此集成，你可以：

* 部署带有虚拟形象的对话式 AI 智能体
* 使用逼真的虚拟形象创建互动式客户服务体验
* 为网站和应用构建引人入胜的虚拟助手

## 工作原理

该集成使用 LiveAvatar 的 LITE 会话模式，两个平台分别负责不同部分：

* **ElevenLabs**：负责音频输入和输出的流式传输与编排
* **LiveAvatar**：负责虚拟形象渲染和实时视频流

当使用 ElevenAgents 配置启动 LITE 模式会话时，LiveAvatar 会调度一个 worker 连接到 ElevenLabs 智能体。智能体的音频输出会实时驱动虚拟形象的唇形同步和动画。

```mermaid
sequenceDiagram
    participant User
    participant LiveAvatar
    participant ElevenLabs Agent

    User->>LiveAvatar: Start LITE session with agent config
    LiveAvatar->>ElevenLabs Agent: Connect worker to agent
    User->>ElevenLabs Agent: Audio input (speech)
    ElevenLabs Agent->>ElevenLabs Agent: Audio orchestration + LLM
    ElevenLabs Agent->>LiveAvatar: Audio output
    LiveAvatar->>User: Avatar video stream with lip sync
```

## 前提条件

开始设置集成前，请确保你拥有：

1. 具有 API 访问权限的 ElevenLabs 账户
2. 具有 API 访问权限的 HeyGen LiveAvatar 账户
3. 一个 ElevenLabs 智能体（按照[快速入门指南](/docs/zh/eleven-agents/quickstart)创建）

> **Note**
>
> ElevenLabs Agent 的音频输入和输出格式需设为 PCM 24000 Hz。可在语音设置 > TTS 输出格式，以及高级 > 用户输入音频格式中设置。

## 设置

#### 获取 ElevenLabs 凭据

需要从 ElevenLabs 账户获取以下两项：

1. **智能体 ID**：前往 [Agents Platform > Agents](https://elevenlabs.io/app/agents/agents)，复制要使用的智能体 ID

2. **API 密钥**：前往 [Settings > API Keys](https://elevenlabs.io/app/settings/api-keys)，生成新的 API 密钥（或使用现有密钥）

> **Note**
>
> API 密钥需要具有 `convai_read`、`user_read` 和 `voices_read` 权限。

#### 在 LiveAvatar 注册 ElevenLabs API 密钥

LiveAvatar 要求通过其密钥端点注册 ElevenLabs API 密钥。注册过程会使用 Amazon KMS 加密密钥，并返回供会话使用的 `secret_id`。

向 LiveAvatar 的密钥端点发出 POST 请求：

```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>"
  }'
```

响应中包含 `secret_id`。请保存此 `secret_id`，以便启动会话时使用。

#### 启动 LiveAvatar 会话

启动 LiveAvatar 会话时，请使用 LITE 模式并包含 ElevenAgents 配置：

```json
{
  "mode": "LITE",
  "elevenlabs_agent_config": {
    "secret_id": "xxxxxxxxxxxxxxxx",
    "agent_id": "agent_xxxxxxxxxxxxxxxx"
  },
  "avatar_id": "xxxxx"
}
```

有关会话管理的完整详情，请参阅 [LiveAvatar 会话 API 文档](https://docs.liveavatar.com)。

## 事件和回调

该集成通过 LiveKit 房间传递事件，并使用与 LiveAvatar FULL 模式相同的事件结构。这样你可以：

* 监控对话状态变化
* 跟踪智能体的说话和聆听模式
* 处理连接和断开连接事件
* 处理转录文本和智能体回复

请根据 [LiveAvatar 事件文档](https://docs.liveavatar.com)配置事件处理程序。

## 计费

此集成涉及两个平台的独立计费：

| 组件                 | 计费                                                        |
| ------------------ | --------------------------------------------------------- |
| LiveAvatar（虚拟形象视频） | 每会话分钟 1 个积分                                               |
| ElevenLabs（对话式 AI） | 根据[订阅方案](https://elevenlabs.io/pricing)在 ElevenLabs 账户中计费 |

虚拟形象流仅针对视频组件计费，所有智能体用量（音频和 LLM）均通过 ElevenLabs 账户单独收费。

## 资源

* [LiveAvatar ElevenLabs Agent 插件文档](https://docs.liveavatar.com/docs/elevenlabs-agent-plugin)
* [LiveAvatar API 参考文档](https://docs.liveavatar.com/reference)
* [ElevenAgents 快速入门](/docs/zh/eleven-agents/quickstart)
* [ElevenAgents API 参考文档](/docs/zh/api-reference/agents/create)