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

# Mistral

MistralVoice 類別使用 Mistral 的 Voxtral 音訊模型提供文字轉語音及語音轉文字功能。它支援緩衝及串流 TTS、具備說話者分離功能的批次轉錄，以及透過參考音訊複製語音。

## 使用範例

```typescript
import { MistralVoice } from '@mastra/voice-mistral'

const voice = new MistralVoice()

// Text-to-speech
const audioStream = await voice.speak('Hello, how can I help you?', {
  responseFormat: 'mp3',
})

// Speech-to-text
const text = await voice.listen(audioStream, {
  language: 'en',
})

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

```typescript
import { MistralVoice } from '@mastra/voice-mistral'

// Initialize with specific configuration
const voice = new MistralVoice({
  speechModel: {
    name: 'voxtral-mini-tts-2603',
    apiKey: 'your-mistral-api-key',
  },
  listeningModel: {
    name: 'voxtral-mini-latest',
    apiKey: 'your-mistral-api-key',
  },
  speaker: 'en_paul_neutral',
})
```

## 建構函數參數

**speechModel** (`MistralModelConfig`): 文字轉語音合成的設定。 (Default: `{ name: 'voxtral-mini-tts-2603' }`)

**speechModel.name** (`string`): 用於語音合成的模型 ID。

**speechModel.apiKey** (`string`): Mistral API 金鑰。如未提供，會改用 MISTRAL\_API\_KEY 環境變數。

**listeningModel** (`MistralModelConfig`): 語音轉文字辨識的設定。 (Default: `{ name: 'voxtral-mini-latest' }`)

**listeningModel.name** (`string`): 用於轉錄的模型 ID。如要鎖定特定版本，請使用 'voxtral-mini-2507'。

**listeningModel.apiKey** (`string`): Mistral API 金鑰。如未提供，會改用 MISTRAL\_API\_KEY 環境變數。

**speaker** (`string`): 語音合成的預設語音 ID。可透過 getSpeakers() 取得可用的 ID。 (Default: `'en_paul_neutral'`)

## 方法

### `speak(input, options?)`

使用 Mistral 的 Voxtral TTS 模型把文字轉換成語音。支援緩衝及串流輸出。

**input** (`string | NodeJS.ReadableStream`): 要轉換成語音的文字或文字串流。

**options** (`MistralSpeakOptions`): 設定選項。

**options.speaker** (`string`): 要使用的語音 ID。會覆寫建構函數的預設值。

**options.responseFormat** (`'pcm' | 'wav' | 'mp3' | 'flac' | 'opus'`): 音訊輸出格式。如要以最低延遲串流，請使用 'pcm'。

**options.refAudio** (`string`): 用於單次語音複製、以 Base64 編碼的參考音訊（最少 2 至 3 秒）。

**options.model** (`string`): 覆寫此呼叫所用的語音模型。

**options.stream** (`boolean`): 啟用串流 TTS。音訊區塊會在抵達時寫入串流。

傳回：`Promise<NodeJS.ReadableStream>`

### `listen(audioStream, options?)`

使用 Mistral 的 Voxtral 轉錄模型轉錄音訊。支援說話者分離、情境偏置及時間戳詳細程度設定。

**audioStream** (`NodeJS.ReadableStream`): 要轉錄的音訊串流。

**options** (`MistralListenOptions`): 設定選項。

**options.language** (`string`): 語言代碼（例如 'en'）。指定後可提高準確度。

**options.diarize** (`boolean`): 啟用說話者分離。

**options.contextBias** (`string[]`): 用於詞彙提示的字詞或短語。

**options.timestampGranularities** (`('segment' | 'word')[]`): 轉錄片段的時間戳詳細程度。

**options.filetype** (`string`): 輸入串流的音訊副檔名提示。

傳回：`Promise<string>`

### `getSpeakers()`

從 Mistral Voices API 取得可用的預設語音。每個項目包含：

**voiceId** (`string`): 語音的唯一識別碼。

**name** (`string`): 語音的顯示名稱。

**languages** (`string[]`): 語音支援的語言。

**gender** (`string | null`): 語音的性別。

### `getListener()`

傳回 `{ enabled: true }`。

## 注意事項

- API 金鑰可透過建構函數選項或 `MISTRAL_API_KEY` 環境變數提供
- TTS 支援 9 種語言：英語、法語、西班牙語、葡萄牙語、意大利語、荷蘭語、德語、印地語、阿拉伯語
- STT 支援 13 種語言：英語、中文、印地語、西班牙語、阿拉伯語、法語、葡萄牙語、俄語、德語、日語、韓語、意大利語、荷蘭語
- 為獲得最佳效果，每次請求的 TTS 輸入文字應少於 300 字
- STT 每次請求最多支援 3 小時音訊
- 透過 `refAudio` 複製語音時，參考音訊最少須為 2 至 3 秒
- `getSpeakers()` 會傳回使用 UUID 識別碼的預設語音。預設的 `en_paul_neutral` 是 TTS 端點接受的具名別名，但不會包含在清單中