> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# ElevenLabs

Mastra 中的 ElevenLabs Voice 实现使用 ElevenLabs API 提供高质量的文本转语音 (TTS) 和语音转文本 (STT) 功能。

## 使用示例

```typescript
import { ElevenLabsVoice } from '@mastra/voice-elevenlabs'

// Initialize with default configuration (uses ELEVENLABS_API_KEY environment variable)
const voice = new ElevenLabsVoice()

// Initialize with custom configuration
const voice = new ElevenLabsVoice({
  speechModel: {
    name: 'eleven_multilingual_v2',
    apiKey: 'your-api-key',
  },
  speaker: 'custom-speaker-id',
})

// Text-to-Speech
const audioStream = await voice.speak('Hello, world!')

// Get available speakers
const speakers = await voice.getSpeakers()
```

## 构造函数参数

**speechModel** (`ElevenLabsVoiceConfig`): 文本转语音功能的配置。 (Default: `{ name: 'eleven_multilingual_v2' }`)

**speechModel.name** (`ElevenLabsModel`): 要使用的 ElevenLabs 模型

**speechModel.apiKey** (`string`): ElevenLabs API 密钥。未提供时使用 ELEVENLABS\_API\_KEY 环境变量

**speaker** (`string`): 文本转语音所用 speaker 的 ID (Default: `'9BWtsMINqrJLrRacOk9x'（Aria 声音）`)

## 方法

### `speak()`

使用配置的语音模型和声音将文本转换为语音。

**input** (`string | NodeJS.ReadableStream`): 要转换为语音的文本。如果提供流，则先将其转换为文本。

**options** (`object`): 语音合成的其他选项

**options.speaker** (`string`): 为此次请求覆盖默认 speaker ID

返回：`Promise<NodeJS.ReadableStream>`

### `getSpeakers()`

返回可用声音选项的数组，其中每个节点包含：

**voiceId** (`string`): 声音的唯一标识符

**name** (`string`): 声音的显示名称

**language** (`string`): 声音的语言代码

**gender** (`string`): 声音的性别

### `listen()`

使用 ElevenLabs Speech-to-Text API 将音频输入转换为文本。

**input** (`NodeJS.ReadableStream`): 包含待转录音频数据的可读流

**options** (`object`): 转录的配置选项

options 对象支持以下属性：

**language\_code** (`string`): ISO 语言代码（例如 'en'、'fr'、'es'）

**tag\_audio\_events** (`boolean`): 是否标记 \[MUSIC]、\[LAUGHTER] 等音频事件

**num\_speakers** (`number`): 要在音频中检测的 speaker 数量

**filetype** (`string`): 音频文件格式（例如 'mp3'、'wav'、'ogg'）

**timeoutInSeconds** (`number`): 请求超时时间（秒）

**maxRetries** (`number`): 最大重试次数

**abortSignal** (`AbortSignal`): 用于中止请求的信号

返回：`Promise<string>` —— 解析为转录文本的 Promise

## 重要说明

1. 需要 ElevenLabs API 密钥。可通过 `ELEVENLABS_API_KEY` 环境变量设置，也可在构造函数中传入。
2. 默认 speaker 设置为 Aria（ID：'9BWtsMINqrJLrRacOk9x'）。
3. ElevenLabs 不支持语音转文本功能。
4. 可使用 `getSpeakers()` 方法获取可用 speaker；该方法会返回每种声音的详细信息，包括语言和性别。