SuperAPI AI Directory

minimax-tts

Coding & development

View repository

Updated 10-16 08:49

About this skill

Skill: minimax-tts

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_ID
  • TG_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