minimax-tokenplan-tts

Generate speech audio from text using MiniMax speech-2.8-hd model. Supports multiple voice options, speed/pitch/volume control, WAV file output with automati...

Security Scan

The skill largely matches its stated TTS purpose, but there are security and coherence issues (disabled SSL verification, instructions that encourage embedding the API key in files, and a nonstandard install URL) that warrant caution before use.

Purpose & Capability

Name/description (MiniMax TTS) align with the included scripts and declared binaries (python3, ffplay) and the single required credential (MINIMAX_API_KEY). Minor inconsistency: the SKILL.md/registry declares MINIMAX_API_KEY as required, but the shipped scripts default to a top-of-file API_KEY constant and only accept an override via --api-key rather than automatically reading the MINIMAX_API_KEY env var — the README even tells the user to edit the scripts to paste the key. This is bad practice but consistent with a simple wrapper script.

Instruction Scope

SKILL.md instructs the agent/user to obtain the API key and to edit the two scripts directly (paste the key and base URL) and then delete the init section. Encouraging manual insertion of secrets into code files is insecure. The instructions also reference IDENTIY.md (not present in the bundle) and recommend always using streaming playback in webchat — giving the agent a persistent preference but not itself malicious. The scripts perform network calls only to the documented MiniMax endpoints; there is no evidence they read unrelated system files or environment variables. However, stream_play.py explicitly disables SSL certificate verification (ssl.verify_mode = CERT_NONE and check_hostname = False), which weakens transport security and could expose the API key to a man-in-the-middle.

Install Mechanism

Registry reports no install spec but SKILL.md metadata contains an install entry pointing to https://clawhub.ai/skills/minimax-tokenplan-tts (kind: download). There is no evidence the skill automatically downloads arbitrary code at runtime in the included files, but the presence of a download install URL in metadata (not a well-known release host) is a minor red flag. The actual deliverable is an instruction-only skill with bundled scripts (no opaque remote install required).

Credentials

Only one credential (MINIMAX_API_KEY) is declared, which is appropriate for a TTS integration. But the scripts do not automatically use the MINIMAX_API_KEY env var — they rely on a hard-coded placeholder and instruct users to embed the key in the scripts or pass --api-key. That increases risk of accidental secret leakage. Additionally, the stream websocket code disables TLS verification, which combined with a bearer token increases the risk of credential exposure via MITM. No other unrelated credentials or config paths are requested.

Persistence & Privilege

The skill does not request always:true and does not try to modify other skills or system-wide settings. It writes TTS output to ~/.openclaw/media/minimax/tts/ (declared filesystem write permission), which is proportional to its purpose. It can be invoked autonomously by the agent (default), which is expected behavior for a skill.

What to consider before installing

This skill appears to implement the claimed MiniMax TTS functionality, but take these precautions before installing/using it: - Do NOT paste your API key into the top of the scripts. Instead pass it on the command line or modify the code to read MINIMAX_API_KEY from the environment (safer than hard-coding). - The streaming script disables SSL verification (accepts any certificate). This makes the API key vulnerable to interception on hostile or misconfigured networks. If you plan to use streaming, edit stream_play.py to enable certificate verification (remove the lines that set check_hostname=False and verify_mode=CERT_NONE) or ensure you use a trusted network. - The SKILL.md metadata references a download URL (clawhub.ai) rather than the MiniMax domain; prefer obtaining code from trusted sources or verify the included files' contents. Since the package already includes scripts, prefer using the bundled code rather than invoking any external installer from unknown hosts. - Avoid leaving secrets in code or in version-controlled files. If you must store credentials locally, use environment variables or a secrets manager and confirm the script reads them securely. - Review and test on an isolated environment first (or with a non-production API key) before allowing the agent to call this skill autonomously. If the maintainer can: (1) remove the hard-coded API_KEY placeholder and read MINIMAX_API_KEY from env by default, and (2) enable proper SSL verification in the websocket client, the remaining concerns would be largely addressed and my confidence would increase.

MiniMax TTS Skill

前置条件

• Python 3 已安装
• requests 库：pip3 install requests
• websockets 库：pip3 install websockets（流式播放需要）
• ffplay（流式播放需要）：
  • macOS: brew install ffmpeg
  • Ubuntu: sudo apt install ffmpeg
  • Windows: 从 https://ffmpeg.org/download.html 下载
  • 如果 ffplay 未安装，stream_play.py 会提示安装方法

init

需要初始化以下信息：

第一步：获取 API Key

向用户获取 MiniMax API Key（sk-cp- 开头的 Token Plan key，或普通 API Key）。

第二步：确认配置

向用户确认：

• API Key 是否正确
• 使用国内（https://api.minimaxi.com）还是海外（https://api.minimaxi.io）节点

第三步：填写配置

获取以上信息后：

1. 修改 scripts/generate.py 顶部的配置常量（API_KEY、BASE_URL），填入实际值
2. 修改 scripts/stream_play.py 顶部的配置常量（API_KEY、BASE_URL），填入相同的值
3. 同时更新下方 ## 配置 区段的表格，作为配置记录

第四步：判断音色

1. 根据 IDENTITY.md 自行选择声优
2. 如判断不出，则使用 male-qn-jingying（精英青年音色）
3. 然后更新下方 ## 配置 区段的表格及两个脚本

第五步：清理

配置填写完成后，删除本 ## init 区段（包括 ### 需要初始化以下信息 的全部内容），仅保留 ## 配置 区段。

---

配置

配置项	值	说明
MINIMAX_API_KEY	<待填入>	初始化时替换为实际 key
BASE_URL	<待填入>	CN: https://api.minimaxi.com / Global: https://api.minimaxi.io
REGION	<待填入>	CN 或 global
VOICE_ID	<待填入>	判断音色后填入

---

音色列表

语言因音色较多，不再逐一列出，完整列表参考 MiniMax TTS 官方文档：

---

快速使用

📢 channel=webchat 时的播放策略：当前 channel 为 webchat（实时对话场景）时， 应优先使用 stream_play.py 直接流式播放，而不生成文件。这样用户可以立即听到语音， 无需等待完整音频生成。仅当用户明确要求保存文件时，才使用 generate.py。

1️⃣ 流式播放（channel=webchat）

通过 WebSocket 实时获取音频流，边生成边用 ffplay 播放。无需生成文件，首个音频包到达即开始播放。

SKILL_DIR="~/.openclaw/workspace/skills/minimax-tokenplan-tts"
python3 "$SKILL_DIR/scripts/stream_play.py" \
    --text "要播放的文本内容" \
    --voice "male-qn-jingying"

注意：以下示例中 stream_play.py 和 generate.py 均指 ~/.openclaw/workspace/skills/minimax-tokenplan-tts/scripts/ 下的完整路径。

参数说明：

参数	必填	说明	默认值
--text	✅	要播放的文本，最长 10000 字符	-
--voice	❌	声优 ID	male-qn-jingying
--speed	❌	语速 [0.5,2.0]	1.0
--vol	❌	音量 (0,10]	1.0
--pitch	❌	音调 [-12,12]	0
--save	❌	同时保存到文件（MP3 格式）	不保存
--api-key	❌	API Key（默认使用文件顶部配置）	-
--base-url	❌	Base URL（默认使用文件顶部配置）	-

示例：

# 直接播放（不保存文件）
python3 stream_play.py --text "你好，我正在通过流式方式播放语音"

# 播放同时保存到文件
python3 stream_play.py --text "这段语音会被保存" --save /tmp/stream_output.mp3

# 使用女声播放
python3 stream_play.py --text "今天天气真不错" --voice female-tianmei

---

2️⃣ 文件生成（需要保存 WAV 时使用）

SKILL_DIR="~/.openclaw/workspace/skills/minimax-tokenplan-tts"
python3 "$SKILL_DIR/scripts/generate.py" \
    --text "要转换的文本内容" \
    --voice "male-qn-jingying" \
    --output "/tmp/tts_output.wav"

参数说明：

参数	必填	说明	默认值
--text	✅	要转换的文本，最长 10000 字符，超出会报错	-
--voice	❌	声优 ID	male-qn-jingying
--speed	❌	语速 [0.5,2.0]	1.0
--vol	❌	音量 (0,10]	1.0
--pitch	❌	音调 [-12,12]	0
--output	❌	输出路径	自动生成
--api-key	❌	API Key（默认使用文件顶部配置）	-
--base-url	❌	Base URL（默认使用文件顶部配置）	-

声优可选值： 完整327个音色列表见 ## 音色列表

示例：

# 基本用法
python3 generate.py --text "你好，欢迎使用 MiniMax TTS" --output /tmp/hello.wav

# 快速播报（1.5倍速）
python3 generate.py --text "紧急通知，请立即处理" --speed 1.5 --output /tmp/alert.wav

# 柔和女声
python3 generate.py --text "今天天气真不错" --voice female-qn-tianying --output /tmp/weather.wav

---

工作流总结

TTS 完整流程

1. 文本预处理 → 检查是否需要插入语气词标签（见 ## 语气词标签）
2. 选择声优 → --voice 参数（默认 male-qn-jingying）
3. 调整参数 → --speed / --vol / --pitch
4. 生成 WAV → 脚本调用 MiniMax TTS API（自动处理 HEX 解码）
5. 格式转换 → 如需 MP3/AAC 等格式，用 ffmpeg 转换

---

脚本输出格式

generate.py

调用 generate.py 后，stdout 输出生成结果，格式如下：

stdout 输出	说明
保存后的文件绝对路径	~/.openclaw/media/minimax/tts/tts-2026-03-27-hello.wav

stream_play.py

调用 stream_play.py 后，stdout 输出播放状态：

stdout 输出	说明
STREAM_PLAY_DONE	流式播放完成
STREAM_PLAY_ERROR: <msg>	播放失败，附带错误信息

两个脚本的日志信息（[INFO]、[WARN]、[ERROR]）均输出到 stderr，不会混入 stdout。

---

错误处理

code	含义	处理
0	成功	继续
1002	限流	提醒用户 API 限流中，建议稍后重试
1004	鉴权失败	检查 API Key
1008	余额不足	提醒充值
2049	无效 Key	检查 Key 是否正确

---

文件存储

• 默认保存到：~/.openclaw/media/minimax/tts/（多 Agent 共享目录）
• 文件名格式：tts-YYYY-MM-DD-<slug>.wav
• slug：取 text 前20字符，英文数字保留，空格变 -

---

语气词标签

• 在文本中适当位置插入以下标签，可生成对应的非语言音效（笑声、咳嗽、呼吸等）。AI 应根据文本情绪自动判断是否插入。
• 用户明确要求不插入语气词标签时，不要插入。

支持的标签

标签	含义	标签	含义
(laughs)	笑声	(chuckle)	轻笑
(coughs)	咳嗽	(clear-throat)	清嗓子
(groans)	呻吟	(breath)	正常换气
(pant)	喘气	(inhale)	吸气
(exhale)	呼气	(gasps)	倒吸气
(sniffs)	吸鼻子	(sighs)	叹气
(snorts)	喷鼻息	(burps)	打嗝
(lip-smacking)	咂嘴	(humming)	哼唱
(hissing)	嘶嘶声	(sneezes)	喷嚏

注意：(emm) 不支持，请用 (breath) 或语气停顿代替。

使用示例

--text "今天是不是很开心呀(laughs)，当然了！"
--text "咳咳(coughs)，不好意思，有点呛到了"
--text "嗯(inhale)，让我想想(exhale)..."

---

注意事项

• 文本长度：最长 10000 字符，超出会报错
• HEX 解码：API 返回的 audio 字段是 HEX 编码（不是 base64），脚本自动处理
• 完成后提示用户：可以从 https://platform.minimaxi.com/docs/faq/system-voice-id 找到更多音色