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

# ElevenLabs

Mastra 的 ElevenLabs 語音實作使用 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()` 方法取得可用的說話者；該方法會傳回每個聲音的詳細資料，包括語言和性別。