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

# 文本转对话快速入门

本指南将介绍如何使用 Text to Dialogue API，从文本生成沉浸感十足、自然流畅的对话。

> **Warning**
>
> 为确保生成稳定，每次请求中所有 `inputs[].text` 值的总长度请勿超过 2,000 个字符。请将较长的脚本拆分为多个片段，并在客户端拼接音频。

## 使用 Text to Dialogue API

#### 创建 API 密钥

[在控制台中创建 API 密钥](https://elevenlabs.io/app/api/api-keys)，用于安全地[访问 API](/docs/zh/api-reference/authentication)。

将密钥作为受管理的机密信息存储，并根据偏好，通过 `.env` 文件将其作为环境变量传递给 SDK，或直接写入应用配置。

**`.env`**

```js title=".env"
ELEVENLABS_API_KEY=<your_api_key_here>
```

#### 安装 SDK

#### SDK

我们还会使用 `dotenv` 库从环境变量加载 API 密钥。

```python
pip install elevenlabs
pip install python-dotenv
```

```typescript
npm install @elevenlabs/elevenlabs-js
npm install dotenv
```

#### CLI

安装 ElevenLabs CLI。推荐使用 Homebrew（macOS）和 Scoop（Windows）。

**`Homebrew（macOS）`**

```bash title="Homebrew（macOS）"
brew install elevenlabs/tap/elevenlabs
```

**`Scoop（Windows）`**

```powershell title="Scoop（Windows）"
scoop bucket add elevenlabs https://github.com/elevenlabs/scoop-bucket
scoop install elevenlabs
```

**`npm`**

```bash title="npm"
npm install -g @elevenlabs/cli
```

**`curl`**

```bash title="curl"
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.sh | sh
```

> **Tip**
>
> 正在使用 AI 编程助手？在项目中运行 `elevenlabs generate-skills`，即可将每个命令组的
> `SKILL.md` 写入 `skills/`，无需粘贴文档，助手就能了解 CLI 的完整功能。使用 `--output-dir`
> 可将其放到其他位置。该命令会读取 CLI 内置的 API 定义，因此无需 API 密钥且可离线运行——还能始终与已安装的 CLI 版本保持同步。

然后进行身份验证——这会打开浏览器以授权 CLI：

```bash
elevenlabs auth login
```

#### 发起 API 请求

#### SDK

根据所选语言，新建名为 `example.py` 或 `example.mts` 的文件，并添加以下代码。
在每个 `text` 值中添加音频标签，以引导该说话人的表达方式。`voice_id`
会为同一输入项选择说话人音色。

```python focus={12-21} maxLines=0
# example.py
import os

from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs
from elevenlabs.play import play

load_dotenv()

elevenlabs = ElevenLabs(
  api_key=os.getenv("ELEVENLABS_API_KEY"),
)

audio = elevenlabs.text_to_dialogue.convert(
    inputs=[
        {
            "text": "[cheerfully] Hello, how are you?",
            "voice_id": "9BWtsMINqrJLrRacOk9x",
        },
        {
            "text": "[stuttering] I'm... I'm doing well, thank you.",
            "voice_id": "IKne3meq5aSn9XLyUdCD",
        }
    ]
)

play(audio)
```

```typescript focus={7-17} maxLines=0
// example.mts
import { ElevenLabsClient, play } from "@elevenlabs/elevenlabs-js";
import "dotenv/config";

const elevenlabs = new ElevenLabsClient();

const audio = await elevenlabs.textToDialogue.convert({
    inputs: [
        {
            text: "[cheerfully] Hello, how are you?",
            voiceId: "9BWtsMINqrJLrRacOk9x",
        },
        {
            text: "[stuttering] I'm... I'm doing well, thank you.",
            voiceId: "IKne3meq5aSn9XLyUdCD",
        },
    ],
});

play(audio);
```

然后运行：

```python
python example.py
```

```typescript
npx tsx example.mts
```

你应该会听到播放的对话音频。

#### CLI

将对话输入作为 JSON 数组传入，并将音频保存到文件：

```bash
elevenlabs text-to-dialogue convert \
  --output dialogue.mp3 \
  --inputs '[
    { "text": "[cheerfully] Hello, how are you?", "voice_id": "9BWtsMINqrJLrRacOk9x" },
    { "text": "[stuttering] I... I am doing well, thank you.", "voice_id": "IKne3meq5aSn9XLyUdCD" }
  ]'
```

打开 `dialogue.mp3` 即可试听结果。

## WebSocket 流式传输

若要通过长连接增量生成 **Eleven v3** 模型的对话，请参阅 [实时文本转对话](/docs/zh/eleven-api/guides/how-to/websockets/realtime-tdd)。如需比较此 WebSocket 与标准 TTS WebSocket，请参阅 [文本转语音与文本转对话 WebSocket 对比](/docs/zh/eleven-api/guides/how-to/websockets/tts-vs-ttd-websockets)。

## 后续步骤

#### [浏览音色](https://elevenlabs.io/app/voice-library)

探索 10,000+ 种音色，为每位对话说话人分配音色

#### [文本转语音](/docs/zh/eleven-api/guides/cookbooks/text-to-speech)

使用 Text to Speech API，通过单一音色生成语音

#### [API 参考文档](/docs/zh/api-reference/text-to-dialogue/convert)

查看所有 Text to Dialogue 参数和响应格式