企业官网建设流程全解析

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手

MiniMax Speech 是 AIRI 语音合成（TTS）服务商中的一项内置方案，允许你在「设置 → 服务商 → 语音合成」中直接接入 MiniMax 的语音合成模型与预设声音。本文以 AIRI 仓库中的配置文档为骨架，结合 MiniMax Speech 提供商实现、设置页源码 与 Speech 模块，完整讲解从获取 API Key、粘贴配置、Ping 校验、选择模型与音色，到最终在「发声」模块启用并试听的整条链路，并深入到 MiniMax 接口的流式合成实现细节，帮助你配置后还能理解每一步背后的源码逻辑。

为什么选择 MiniMax Speech？

如果你已经使用 MiniMax，并希望直接使用其中文或英文预设声音，可以选择它。MiniMax Speech 的优势在于：

• 无需额外注册：复用已有的 MiniMax 开放平台账号与 API Key，即可获得语音合成能力；
• 开箱即用的预设音色：提供商内置了一批官方 System Voice ID 列表中的音色（见下文「账号音色目录与内置兜底列表」），同时也支持读取账号下克隆（voice_cloning）与生成（voice_generation）的音色；
• 低接入成本：在 AIRI 的设置页中粘贴 Key、选好模型与音色即可使用，无需手写任何 API 调用代码。

第一步：获取 API Key

MiniMax Speech 走的是云端 API，因此你需要一个有效的 API Key：

1. 登录 MiniMax 开放平台，开通 API 使用权限；
2. 在 API Key 管理页面创建密钥；
3. 复制密钥并妥善保存，后续粘贴到 AIRI 的提供商配置中。

::: warning API Key 安全 不要将 API Key 提交到仓库、截图或发送给他人。AIRI 的提供商配置是本地持久化的，Key 仅用于本机发往 MiniMax 的请求，请勿把它写进任何会被公开的配置文件。 :::

第二步：在 AIRI 中配置

1. 打开设置 → 服务商 → 语音合成 → MiniMax Speech，在 API Key 输入框中粘贴上一步获取的密钥；
2. 保留默认服务地址https://api.minimax.io，除非服务商明确提供了其他地址。

从 提供商实现 可以看到，MiniMax Speech 的配置项由 Zod schema 定义，共两个字段：

底层实现还会对baseUrl做一次尾部斜杠清洗（replace(/\/$/, '')），因此地址末尾带不带/都不影响实际请求。Key 在发送前也会经过trim()去除首尾空白。

配置如何被校验与持久化

设置页通过 minimax-speech.vue 中的watchDebounced监听apiKey与baseUrl的变化（500ms 防抖），一旦校验通过就会调用loadVoicesForProvider拉取账号音色目录。校验逻辑位于 提供商的 validators：

• 空 Key 直接判定为无效（API key is required.），不会发起网络请求；
• 非空 Key 会调用probeMinimaxCredentials向 MiniMax 的真实接口探测一次，只有账号接受该 Key 才算「已配置」；
• 校验结果决定了提供商在 Speech 模块 中的configured状态，未配置的提供商不会出现在可用的语音服务列表中。

这一点在浏览器测试 minimax-speech.browser.test.ts 中也有对应回归用例：用户输入有效 Key 后，provider 状态才会从未配置（unconfigured）变为configured。

第三步：验证配置

配置完成后，按以下顺序验证整条链路是否打通：

1. Ping API：验证网络与 Key

点击Ping API按钮，测试网络是否连通以及 API Key 是否填写正确。这一步在源码层面等价于执行validateConfig校验器：它通过POST {baseUrl}/v1/get_voice请求账号音色目录，并根据响应体中的base_resp.status_code判断 Key 是否被接受。

这里有一个值得注意的实现细节：MiniMax 的所有接口都把结果封装在响应体里，即使 Key 被拒绝也返回 HTTP 200。因此 AIRI 的实现 专门解析响应体，只有status_code === 0才视为成功，任何非零状态码都会把status_msg（如invalid api key）透传为校验错误。这也意味着「网络不通」与「Key 被拒绝」被区分对待：前者不证明 Key 错误，后者才是真正的凭据问题。相关测试见 index.test.ts。

2. 选择模型与音色

Ping 成功后，选择可用的模型与声音。模型下拉框由listModels提供，当前内置两个选项：

注意speech-2.8-hd同时也是 默认模型常量：当调用方没有显式指定模型时（例如裸调用 provider），合成请求会自动回退到该模型。设置页的默认模型同样指向它，并且用户的选择会写回 provider 配置中的model字段，供 Speech 模块读取。

选好模型与音色后，再到设置 → 发声启用（即把当前发声单元切换为 MiniMax Speech）。在 Speech 模块中，activeSpeechProvider、activeSpeechModel、activeSpeechVoiceId三个持久化字段分别保存当前语音服务、模型与音色，只有当三者齐全时configured才为真，Agent 才会真正用该语音方案发声。

3. 输入短文本试听

在设置页的试听区域（Playground）输入一段短文本，确认可以正常播放。试听请求经由 speech store 的 speech() 调用generateSpeech完成：它把当前模型、输入文本、音色 ID 与 provider 配置一起传给 MiniMax 适配器，返回合成好的ArrayBuffer音频供播放器播放。试听时选择的音色会持久化到 provider 配置的voice字段，重新打开设置页后依然保留——这一点由浏览器测试 「keeps a picked voice after the page is reopened」 验证。

账号音色目录与内置兜底列表

音色选择器中的列表并非写死的常量，而是优先从账号拉取的实时目录。AIRI 通过POST {baseUrl}/v1/get_voice（请求体{ voice_type: 'all' }）读取三类音色并合并展示：

• system_voice：官方系统预设音色（如English_Graceful_Lady）；
• voice_cloning：账号下克隆的音色；
• voice_generation：账号下生成的音色。

由于系统音色的 ID 带有语言前缀（如Spanish_SereneWoman、Chinese (Mandarin)_News_Anchor），resolveVoiceLanguage 会解析 ID 前缀并为每个音色标注语言（英文、西班牙语、普通话、粤语、日语、韩语、法语、德语、意大利语、葡萄牙语、俄语、土耳其语、印尼语、越南语、泰语等）。克隆与生成的音色没有前缀，会被标记为und（Unknown）。测试用例验证了同一显示名（如 Serene Woman）在不同语言下可以正确区分：[index.test.ts](https://link.gitcode.com/i/e5dd76c53ea798c56708e188d9f0346c#L131-L143 附近用例)。

当网络不可达或账号尚未拥有任何音色时，listVoices 会回退到内置的 12 个官方音色列表，保证选择器始终可用；但若 Key 被拒绝，则直接抛错而非展示内置列表，避免「看起来已配置、实则 Key 无效」的假象。

合成请求的底层实现：从文本到 MP3

为了让你理解「试听成功」背后发生了什么，这里展开适配器的核心请求逻辑。当音色与模型确定后，AIRI 会向POST {baseUrl}/v1/t2a_v2发起流式合成请求，请求体大致如下（见 index.ts）：

{ "model": "speech-2.8-hd", "text": "输入文本", "stream": true, "voice_setting": { "voice_id": "English_Graceful_Lady", "speed": 1, "vol": 1, "pitch": 0 }, "audio_setting": { "sample_rate": 32000, "bitrate": 128000, "format": "mp3", "channel": 1 } }

几个值得留意的参数：

• voice_setting：默认音速1、音量1、音调0，voice_id使用你选择的音色；调用方未指定音色时回退到English_Graceful_Lady；
• audio_setting：输出 32kHz、128kbps、单声道的 MP3 音频；
• stream: true：开启流式返回，响应是 SSE 事件流，每个data:事件中的audio字段携带十六进制编码的音频块。适配器逐事件解码、拼接，并跳过状态为 2 的最终汇总事件（其音频与前序块重复），最终合并为一个完整的 MP3 字节数组返回给播放器：index.ts。

此外，合成失败的多种形态都被显式处理，并各有测试覆盖（index.test.ts）：

• 流内出现base_resp.status_code非 0 的拒绝事件（即使 HTTP 200）——直接抛错，而不是把错误当静音播放；
• 音频已经开始后又收到拒绝事件——丢弃此前已解码的块，避免播放被截断的片段；
• 流结束但没有任何音频——报「MiniMax returned no audio for this request」，而不是展示一个 0 秒的空播放器；
• 非 2xx 的 HTTP 响应——读取响应体中的 API 消息，读不到则回退到状态码描述。

排查指南

Ping API 失败

按以下顺序排查：

1. API Key 是否正确：复制时是否遗漏字符、前后是否有空白。AIRI 在发送前会trim()，但建议粘贴后再次确认；
2. 账户额度与权限：是否已在 MiniMax 平台开通 API 使用权限、账户是否有可用额度。额度不足或权限未开通时，get_voice会返回非 0 状态码；
3. 网络连接：能否正常访问https://api.minimax.io。从源码实现看，网络不可达会被单独归类为unreachable，此时校验不会判定 Key 无效，音色选择器会回退到内置列表；若你处于需要代理的网络环境，请先确保代理可用。

模型或声音不可用

• 模型列表以提供商内置的speech-2.8-hd与speech-2.8-turbo为准，两者均为当前账号可直接使用的公开模型；
• 音色列表以 MiniMax 账户当前开放的列表为准：官方系统音色需账号具备对应权限，克隆（voice_cloning）与生成（voice_generation）音色更是账号私有数据。若某音色不在你的账号目录中，合成请求会被 MiniMax 拒绝——内置列表中的每个 ID 都来自官方 System Voice ID List，不要自行臆造音色 ID；
• 若保存的音色在新一轮目录拉取后已不存在，设置页会自动回退到目录中首个可用音色，并同步更新持久化配置（见 minimax-speech.browser.test.ts 中的回归测试）。

小结

MiniMax Speech 为 AIRI 提供了一条「粘贴即用」的云端语音合成路径：获取 API Key → 在设置页配置并 Ping 校验 → 选择模型与音色 → 在「发声」模块启用 → 短文本试听。其背后的 提供商适配器 完整处理了账号音色目录读取、流式 SSE 音频解码、凭据校验与多种失败形态，而 设置页 与 Speech 模块 共同保证了模型、音色选择的持久化与跨窗口同步。如果你已经在使用 MiniMax，这可能是把 AIRI 的 Agent 接上稳定中文/英文语音能力最快捷的方式之一。

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手