---
name: minimax-tts-setup
description: Configure MiniMax TTS in Hermes — discovered correct model, base URL, voice_id, and how to inject the API key into Hermes process via .env
---

# MiniMax TTS Setup for Hermes

## 关键发现

### API endpoint
- **正确 base_url:** `https://api.minimaxi.com/v1/t2a_v2` (不是 `api.minimax.io`，也不是 `api.minimax.chat`)
- 模型: `speech-2.8-hd` (注意是 `2.8` 不是 `02`，也不是 `02-hd`)
- voice_id 示例: `female-tianmei`, `male-qn-qingse`

### Hermes 进程环境变量问题
Hermes 是独立进程（不是从 shell 继承环境变量），所以 `.zshrc` 里的 `export MINIMAX_API_KEY=...` **不会生效**。

**解决方案:** 把 key 写入 `~/.hermes/.env`：

```bash
# 已有 MINIMAX_CN_API_KEY 在 .env 第371行，手动加一行 alias：
MINIMAX_API_KEY=<your-key-value>
```

注意：`.env` 里 chat 用的是 `MINIMAX_CN_API_KEY`，TTS 代码读的是 `MINIMAX_API_KEY`，需要单独加这一行。

### config.yaml 配置
```yaml
tts:
  provider: minimax
  minimax:
    api_key_env: MINIMAX_API_KEY   # 从 .env 读取，不是 shell 环境变量
    model: speech-2.8-hd
    voice_id: female-tianmei
    base_url: https://api.minimaxi.com/v1/t2a_v2
```

## 调试技巧

如果 TTS 报错 `invalid api key`，先用 curl 确认 key 是否真的可用：
```bash
source ~/.zshrc
curl -X POST "https://api.minimaxi.com/v1/t2a_v2" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"speech-2.8-hd","text":"测试","stream":false,"voice_setting":{"voice_id":"female-tianmei"}}'
```

## 已知错误
| model 值 | 错误信息 |
|----------|----------|
| `speech-02-hd` | `your current token plan not support model, speech-02-hd` |
| `speech-02` | `method t2a-v2 not have model: speech-02` |
| `speech-01` | `method t2a-v2 not have model: speech-01` |

## 平台兼容性

### 微信 (WeChat) ❌
- **不支持**接收外部语音消息（无论什么格式：OGG/AAC/M4A/MP3）
- 原因：微信限制仅支持从手机端发送的语音，不支持从外部 API 接收的语音文件
- **解决方案**：在微信上只用文字回复，其他平台（Telegram 等）正常发送语音

### Telegram ✅
- 原生支持 Ogg/Opus 格式（`voice_compatible: true`）
- 无需额外转换