Exclusive skill (only used by companion/Mira) Version: 1.0.0
Function Description
Call the MiniMax T2A v2 API to synthesize text into speech, output ogg/opus format, and send it to the user via the Telegram sendVoice interface. Deeply optimized for Mandarin Chinese, with natural and fluent pronunciation and low latency, suitable for Mira's daily companionship scenarios.
API Specifications
| Parameter | Value |
|---|---|
| Endpoint | https://api.minimax.chat/v1/t2a_v2 |
| Model | speech-01-hd(high quality) / speech-01(standard, low latency) |
| Default Voice | female-zhixing(intellectual female voice) |
| Output Format | mp3 → ffmpeg transcode → ogg/opus |
| Maximum Text Length | 5,000 characters |
| Authentication Method | Authorization: Bearer {MINIMAX_API_KEY} + GroupId |
Recommended Voice Options
| Voice ID | Chinese Name | Style | Use Case |
|---|---|---|---|
female-zhixing |
Intellectual female voice | Composed, warm | Default, Mira's daily companionship (Recommended) |
female-tianmei |
Sweet female voice | Lively, friendly | Relaxed morning messages |
female-shaonv |
Young girl voice | Fresh, nimble | Lively discovery sharing |
female-qingxin |
Fresh female voice | Soothing, gentle | evening / weekly emotional messages |
Users can override the default voice ID in the USER.md field of voice_preference .
Call Interface
speak(text, voice_id=None, output_path=None) → str
输入:
text 必填,要合成的文字(中文优先,支持中英混合)
voice_id 可选,覆盖 USER.md 的 voice_preference 配置
output_path 可选,指定临时文件路径(默认 /tmp/mira_tts_{uuid}.ogg)
输出:
str — 生成的 ogg 文件绝对路径
异常:
MinimaxTTSError — API 调用失败(含错误码和原因)
FFmpegNotFoundError — ffmpeg 未安装时抛出(含安装提示)
Synthesis Flow
1. 读取 USER.md voice_preference(未配置则使用 female-zhixing)
2. 构造 POST /v1/t2a_v2 请求体:
{
"model": "speech-01-hd",
"text": "<消息文字>",
"voice_setting": {
"voice_id": "<voice_id>",
"speed": 1.0,
"vol": 1.0,
"pitch": 0
},
"audio_setting": {
"audio_sample_rate": 32000,
"bitrate": 128000,
"format": "mp3"
},
"GroupId": "<MINIMAX_GROUP_ID>"
}
3. 接收 mp3 二进制流,写入 /tmp/mira_tts_{uuid}.mp3
4. 调用 ffmpeg 转码:
ffmpeg -i /tmp/mira_tts_{uuid}.mp3 -c:a libopus -b:a 64k -ar 48000 /tmp/mira_tts_{uuid}.ogg
5. 清理临时 .mp3 文件
6. 返回 .ogg 文件路径
Integration with Telegram
After generating the .ogg file, send it via sendVoice :
POST https://api.telegram.org/bot{TG_BOT_TOKEN_COMPANION}/sendVoice
Content-Type: multipart/form-data
chat_id: <TG_ADMIN_CHAT_ID>
voice: <.ogg 文件>
caption: <原始文字>(可选,作为字幕)
Delete the temporary .ogg file immediately after sending.
Text Preprocessing Rules
Before calling the API, perform the following processing on the message text to ensure natural reading:
| Processing Item | Rule |
|---|---|
| Markdown Symbols | Remove formatting symbols such as **、_、~、` and other format symbols |
| URL | Replace with "a link" |
| Emoji | Keep (MiniMax will naturally skip most Emoji) |
| Overly Long Messages | When > 500 characters, truncate to the first 500 characters; also send a full text version |
| Pure Number Strings | Keep (MiniMax can read numbers correctly) |
Voice Sending Timing
Not all messages are suitable for voice; the proactive-chat skill decides based on the following rules:
| Trigger Type | Default Behavior | Reason |
|---|---|---|
morning |
Voice priority | Morning greetings are suitable for listening |
evening |
Voice priority | Stronger sense of companionship at night |
weekly |
Voice priority | Emotional recaps are suitable for conveying via voice |
discovery |
Text priority | Content containing links/quotes is not suitable for reading aloud |
| Direct user conversation | Text (unless the user requests otherwise) | Conversation reply efficiency takes priority |
Users can globally disable voice in the USER.md field of voice_messages (enabled: false)。
Fallback Strategy
When any of the following conditions is met, skip speech synthesis and send text directly:
| Condition | Handling |
|---|---|
MINIMAX_API_KEY Not configured |
Degrade, log a warn entry |
MINIMAX_GROUP_ID Not configured |
Degrade, log a warn entry |
| API returns non-200 | Degrade, log an error entry |
| ffmpeg not installed | Degrade, log a warn entry (including installation hint) |
| Text length < 5 characters | Degrade (short text is not suitable for speech) |
USER.md voice_messages.enabled: false |
Degrade (user disabled speech) |
| discovery message contains an external link | Degrade (links cannot be read aloud) |
Environment variables
| Variable | Required | Description |
|---|---|---|
MINIMAX_API_KEY |
✅ | MiniMax platform API Key |
MINIMAX_GROUP_ID |
✅ | MiniMax account Group ID (Console → Account Info) |
MINIMAX_VOICE_ID |
Optional | Override the default voice ID (default female-zhixing) |
Dependencies
requests(Python HTTP requests)ffmpeg(mp3 → ogg/opus transcoding; install:brew install ffmpeg)MINIMAX_API_KEY、MINIMAX_GROUP_IDTG_BOT_TOKEN_COMPANION、TG_ADMIN_CHAT_ID
Logs
- Synthesis successful:
~/.openclaw/workspaces/companion/logs/tts.log(record voice_id, character count, elapsed time) - Degradation log: same as above (including degradation reason)
- Error:
~/.openclaw/workspaces/companion/logs/error.log
Comparison with elevenlabs-tts
| Dimension | minimax-tts | elevenlabs-tts |
|---|---|---|
| Chinese naturalness | ⭐⭐⭐⭐⭐ Excellent (native Chinese) | ⭐⭐⭐⭐ Good (multilingual v2) |
| Mixed Chinese and English | ⭐⭐⭐⭐ Good | ⭐⭐⭐⭐⭐ Excellent |
| ogg output | Requires ffmpeg transcoding | Native ogg_opus |
| Voice cloning | Not supported | Supported (Instant Cloning) |
| Latency | ~300–600ms | ~600–1200ms |
| Cost | Low (more cost-effective for Chinese scenarios) | Medium (Starter $5/30K characters) |
| Recommended scenarios | Pure Chinese, low latency, low cost | Voice cloning, mixed Chinese and English |