Minimax Tts

────────────────────────────────────────────────────────

路径推算规则（Claude 执行任意命令前均应遵守）

────────────────────────────────────────────────────────

SKILLS_ROOT：技能脚本根目录

本 SKILL.md 的绝对路径 → 取父目录(minimax-tts) → 再取上级 = SKILLS_ROOT

如需强制覆盖：export CLAUDE_SKILLS_ROOT=/your/path

SKILLS_ROOT="${CLAUDE_SKILLS_ROOT:-$(cd "$(dirname "$(realpath "${BASH_SOURCE[0]:-$0}")")/.." && pwd)}"

OUTPUT_DIR：所有生成文件的输出根目录（绝对路径）

默认使用当前工作目录（$PWD），即 Claude Code CLI 的 cwd。

前端可通过请求参数 cwd 控制输出位置，实现多用户隔离。

如需强制覆盖：export CLAUDE_OUTPUT_DIR=/your/path

OUTPUT_DIR="${CLAUDE_OUTPUT_DIR:-$PWD}"

⚠️ 强制约束：所有 --output 和 --image 路径必须使用 $OUTPUT_DIR 下的绝对路径

禁止使用 ./xxx 或相对路径，否则文件会落在 Node 进程的 cwd 而非会话目录

示例: node "$SKILLS_ROOT/minimax-tts/scripts/synthesize.js" --text "..." --output "$OUTPUT_DIR/assets/narr.mp3"

MiniMax TTS 语音合成

使用 MiniMax 语音合成 API 将文本转换为高质量语音，支持多种音色、情感、语速调节，适用于旁白生成、有声阅读、配音等场景。

配置

方式一：配置文件（推荐）

创建配置文件 ~/.phoenixassistantai/media_config.json：

{
  "minimaxTTS": {
    "enabled": true,
    "apiKey": "你的API密钥"
  }
}

方式二：环境变量

# macOS/Linux
export MINIMAX_API_KEY="你的API密钥"

# Windows PowerShell
$env:MINIMAX_API_KEY="你的API密钥"

获取 API Key

1. 访问 MiniMax 开放平台：https://platform.minimaxi.com/user-center/basic-information/interface-key
2. 创建新的 API Key
3. 复制密钥并配置

使用示例

路径说明：下面的示例使用 $SKILLS_ROOT 环境变量来引用脚本路径。

1. 基础语音合成

node "$SKILLS_ROOT/minimax-tts/scripts/synthesize.js" \
  --text "你好，这是一段测试语音" \
  --output "$OUTPUT_DIR/hello.mp3"

2. 指定音色和情感

node "$SKILLS_ROOT/minimax-tts/scripts/synthesize.js" \
  --text "今天是不是很开心呀，当然了！" \
  --voice "male-qn-qingse" \
  --emotion "happy" \
  --output "$OUTPUT_DIR/happy.mp3"

3. 从文件读取文本

node "$SKILLS_ROOT/minimax-tts/scripts/synthesize.js" \
  --text-file "$OUTPUT_DIR/narration.txt" \
  --output "$OUTPUT_DIR/narration.mp3" \
  --speed 0.9 \
  --voice "Chinese (Mandarin)_Warm_Bestie"

4. 完整参数配置

node "$SKILLS_ROOT/minimax-tts/scripts/synthesize.js" \
  --text "泉眼无声惜细流，树阴照水爱晴柔" \
  --model "speech-2.8-hd" \
  --voice "Chinese (Mandarin)_Warm_Bestie" \
  --speed 1.0 \
  --volume 1.0 \
  --pitch 0 \
  --emotion "calm" \
  --format mp3 \
  --sample-rate 32000 \
  --bitrate 128000 \
  --channel 1 \
  --output "$OUTPUT_DIR/xiaochi.mp3"

5. 使用发音词典

node "$SKILLS_ROOT/minimax-tts/scripts/synthesize.js" \
  --text "这里的处理方式很危险" \
  --pronunciation "处理/(chu3)(li3)" --pronunciation "危险/dangerous" \
  --output "$OUTPUT_DIR/custom_pron.mp3"

6. URL输出模式（获取音频下载链接）

node "$SKILLS_ROOT/minimax-tts/scripts/synthesize.js" \
  --text "这是一段语音" \
  --output-format url \
  --output "$OUTPUT_DIR/result.mp3"

7. 开启字幕服务

node "$SKILLS_ROOT/minimax-tts/scripts/synthesize.js" \
  --text "这是一段需要字幕的语音" \
  --subtitle \
  --output "$OUTPUT_DIR/with_subtitle.mp3"

8. 使用语言增强（方言/小语种）

node "$SKILLS_ROOT/minimax-tts/scripts/synthesize.js" \
  --text "你好世界" \
  --language-boost "Chinese,Yue" \
  --output "$OUTPUT_DIR/cantonese.mp3"

参数说明

必需参数（二选一）

文本长度限制：不超过 10,000 字符；超过 3,000 字符建议使用流式输出。

可选参数

模型选择

音色列表

中文男声

中文女声

更多音色请参考 MiniMax 官方文档：https://platform.minimaxi.com/docs/guides/t2a-voice

情感列表

情感参数仅部分音色支持，详见官方文档。

语言增强列表

支持的语言/方言（--language-boost 参数）：

Chinese, Chinese,Yue（粤语）, English, Arabic, Russian, Spanish, French, Portuguese, German, Turkish, Dutch, Ukrainian, Vietnamese, Indonesian, Japanese, Italian, Korean, Thai, Polish, Romanian, Greek, Czech, Finnish, Hindi, Bulgarian, Danish, Hebrew, Malay, Persian, Slovak, Swedish, Croatian, Filipino, Hungarian, Norwegian, Slovenian, Catalan, Nynorsk, Tamil, Afrikaans, auto

文本特殊标记

停顿控制

格式：<#x#>，x 为停顿时长（秒），范围 [0.01, 99.99]

这是第一句<#0.5#>停顿半秒后继续

语气词标签（仅 speech-2.8 系列）

输出信息

脚本成功运行后将输出以下信息：

✅ 语音合成成功！
文件路径: /path/to/output.mp3
音频时长: 9.9 秒
采样率: 32000 Hz
比特率: 128000 bps
音频格式: mp3
声道数: 1
计费字符数: 26

程序化调用（供其他 Skill 集成）

其他 Skill 可通过读取本文件了解接口规范，并以以下方式调用：

方式一：命令行调用

node "$SKILLS_ROOT/minimax-tts/scripts/synthesize.js" \
  --text "合成文本" \
  --voice "Chinese (Mandarin)_Warm_Bestie" \
  --speed 1.0 \
  --output "$OUTPUT_DIR/assets/narration.mp3"

方式二：作为模块引用

const { synthesize } = require('$SKILLS_ROOT/minimax-tts/scripts/synthesize.js');

const result = await synthesize({
  text: '合成文本',
  voice: 'Chinese (Mandarin)_Warm_Bestie',
  speed: 1.0,
  volume: 1.0,
  pitch: 0,
  emotion: 'calm',
  format: 'mp3',
  sampleRate: 32000,
  bitrate: 128000,
  channel: 1,
  output: `${OUTPUT_DIR}/assets/narration.mp3`
});
// result: { filePath, audioLength, sampleRate, bitrate, format, channel, usageCharacters }

方式三：从 storyboard.json 读取 TTS 参数

本 Skill 的参数设计兼容 poetry-video-creator 的 storyboard.json 中 tts_params 字段：

{
  "tts_params": {
    "voice_id": "Chinese (Mandarin)_Warm_Bestie",
    "speed": 1.0,
    "volume": 5.0,
    "pitch": 0
  }
}

映射关系：

• voice_id → --voice
• speed → --speed
• volume → --volume（注意：storyboard中为1-10范围，API为0.1-2.0，脚本自动转换）
• pitch → --pitch

常见错误

参考资料

• API 参考：https://platform.minimaxi.com/docs/api-reference/speech-t2a-http
• 控制台：https://platform.minimaxi.com/user-center/basic-information/interface-key
• 错误码：https://platform.minimaxi.com/docs/api-reference/errorcode
• 速率限制：https://platform.minimaxi.com/docs/guides/rate-limits