> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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`): 文字轉語音使用的語音 ID (Default: `'9BWtsMINqrJLrRacOk9x'（Aria 語音）`)

## 方法

### `speak()`

使用已設定的語音模型與語音，將文字轉換為語音。

**input** (`string | NodeJS.ReadableStream`): 要轉換為語音的文字。若提供資料流，會先將其轉換為文字。

**options** (`object`): 語音合成的其他選項

**options.speaker** (`string`): 針對此請求覆寫預設語音 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`): 要在音訊中偵測的說話者人數

**filetype** (`string`): 音訊檔案格式（例如 'mp3'、'wav'、'ogg'）

**timeoutInSeconds** (`number`): 請求逾時秒數

**maxRetries** (`number`): 重試次數上限

**abortSignal** (`AbortSignal`): 中止請求的訊號

回傳：`Promise<string>` — 解析為轉錄文字的 Promise

## 重要事項

1. 必須提供 ElevenLabs API 金鑰。可透過 `ELEVENLABS_API_KEY` 環境變數設定，或傳入建構函式。
2. 預設語音設為 Aria（ID：'9BWtsMINqrJLrRacOk9x'）。
3. ElevenLabs 不支援語音轉文字功能。
4. 可使用 `getSpeakers()` 方法取得可用語音；該方法會回傳每個語音的詳細資訊，包括語言與性別。