> Discover all available pages from the documentation index: https://mastra.zisheng.pro/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 key。未提供时使用 MISTRAL\_API\_KEY 环境变量。

**listeningModel** (`MistralModelConfig`): 语音转文本识别配置。 (Default: `{ name: 'voxtral-mini-latest' }`)

**listeningModel.name** (`string`): 用于转写的模型 ID。若要固定版本，请使用 voxtral-mini-2507。

**listeningModel.apiKey** (`string`): Mistral API key。未提供时使用 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 }`。

## 注意事项

- 可以通过构造函数选项或 `MISTRAL_API_KEY` 环境变量提供 API key
- TTS 支持 9 种语言：英语、法语、西班牙语、葡萄牙语、意大利语、荷兰语、德语、印地语和阿拉伯语
- STT 支持 13 种语言：英语、中文、印地语、西班牙语、阿拉伯语、法语、葡萄牙语、俄语、德语、日语、韩语、意大利语和荷兰语
- 为获得最佳效果，每次请求的 TTS 输入文本应少于 300 个单词
- STT 每次请求最多支持 3 小时音频
- 通过 `refAudio` 克隆音色至少需要 2–3 秒的参考音频
- `getSpeakers()` 返回带 UUID 标识符的预设音色。默认值 `en_paul_neutral` 是 TTS 端点接受的命名别名，但不会包含在该列表中