> 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.

# Speech Engine

## 概述

ElevenLabs Speech Engine 可为任何聊天智能体添加语音功能。ElevenLabs 负责语音转文本和文本转语音，服务器则提供 LLM 逻辑。SDK 管理连接生命周期、轮次切换和打断检测，让你专注于智能体的行为。

#### [快速开始](/docs/zh/eleven-api/guides/cookbooks/speech-engine)

使用 ElevenLabs SDK 构建语音智能体。

#### [JavaScript SDK 参考](/docs/zh/eleven-api/resources/libraries/speech-engine/javascript-sdk-reference)

JavaScript SDK 的类、方法和事件。

#### [Python SDK 参考](/docs/zh/eleven-api/resources/libraries/speech-engine/python-sdk-reference)

Python SDK 的类、方法和事件。

## 工作原理

Speech Engine 通过 WebSocket 将服务器连接至 ElevenLabs。每个连接代表一段对话。

```mermaid
sequenceDiagram
    participant Browser
    participant ElevenLabs

    box Your Server
        participant SDK as Speech Engine SDK
        participant LLM
    end

    Browser->>ElevenLabs: User speaks (audio)
    ElevenLabs->>SDK: Transcript (WebSocket)
    SDK->>LLM: Conversation history
    LLM->>SDK: Streamed response
    SDK->>ElevenLabs: Text chunks
    ElevenLabs->>Browser: Agent speaks (audio)
```

1. 用户在浏览器中说话。ElevenLabs 捕获并转录音频。
2. 转录文本会连同完整对话历史一起发送到服务器。
3. 服务器将转录文本传给 LLM，并流式返回响应。
4. ElevenLabs 将文本转换为语音，并在浏览器中播放。

## 何时使用 Speech Engine

Speech Engine 专为希望自带 LLM，并在自己的服务器上控制对话逻辑的开发者设计。适用于以下情况：

* 为现有的文本聊天智能体添加语音
* 使用特定 LLM、微调模型或自定义推理流水线
* 完全控制对话路由、上下文管理和工具调用
* 将语音集成到现有服务器应用中（Express、FastAPI 等）

如果想使用由 ElevenLabs 提供 LLM、知识库和工具的全托管方案，请改用 [ElevenAgents](/docs/zh/eleven-agents/overview)。

## 主要功能

* **任意 LLM** - 可使用 OpenAI、Anthropic、Google Gemini 或任何能生成文本的模型。SDK 可自动从 OpenAI、Anthropic 和 Gemini 的流格式中提取文本。
* **打断处理** - 当用户在响应过程中说话时，SDK 会通过 `AbortSignal`（TypeScript）或任务取消（Python）自动取消正在进行的 LLM 请求。
* **流式传输** - 响应生成时会流式传输到浏览器。可传入字符串、异步可迭代对象或原生 LLM 流对象。
* **轮次切换** - SDK 管理对话轮次，因此服务器只需响应转录文本。

## 对话时长

Speech Engine 支持最长 40 分钟（2,400 秒）的对话。默认情况下，
对话会在 600 秒（10 分钟）后结束。如需支持更长对话，请在 API 中提高
`conversation.max_duration_seconds`，或在控制台 **高级** 标签页中提高
**最长对话时长**。参阅
[配置最长对话时长](/docs/zh/eleven-api/guides/cookbooks/speech-engine#configuring-the-maximum-conversation-duration)。
如果需要超过 40 分钟的对话，请[联系我们的团队](https://elevenlabs.io/contact-sales)。

## IP 允许列表

如果服务器位于防火墙后，或使用基于 IP 的访问控制，可以将 ElevenLabs WebSocket 连接来源的静态出站 IP 加入允许列表。完整 IP 地址列表请参阅 [IP 允许列表](/docs/zh/eleven-api/resources/ip-allowlisting)。

> **Tip**
>
> 使用 IP 允许列表可确保服务器只接受来自 ElevenLabs 系统的 WebSocket
> 连接。

## 常见问题

#### 支持哪些 LLM？

支持任何能生成文本的 LLM。SDK 内置了 OpenAI（Responses API 和
Chat Completions API）、Anthropic Messages API 和 Google Gemini API 的流提取功能。对于其他提供商，请传入
纯字符串或字符串块的异步可迭代对象。

#### Speech Engine 与 ElevenAgents 有何区别？

ElevenAgents 是一个全托管平台，由 ElevenLabs 提供 LLM、知识库和
工具。Speech Engine 适合希望自带 LLM，并在自己的服务器上控制
对话逻辑的开发者。

#### 支持哪些服务器框架？

在 TypeScript 中，可以将 Speech Engine 附加到任意 Node.js HTTP 服务器（Express、Fastify 或
原生 `http.createServer()`），也可运行独立 WebSocket 服务器。在 Python 中，SDK 通过 `engine.serve()` 提供
独立服务器，也可通过 `engine.create_session()` 与 FastAPI、Starlette 或任意
ASGI 框架集成。