语音克隆 + 文本转语音（TTS）

适用范围

本技能的功能范围严格限定于以下四点：（1）将用于克隆的音频上传至 MiniMax；（2）创建克隆语音；（3）使用已克隆或已存在的语音进行 TTS 合成；（4）更新本 SKILL.md 文件中的“克隆语音映射”区块。该脚本仅读取/写入本技能自身的 SKILL.md 文件，不会读取任何无关的系统文件，也不会访问除上述 MiniMax API 密钥以外的其他环境变量。

适用场景

• 当您需要将用户提供的音频克隆为可复用的语音时，请使用本技能。
• 当您需要对已克隆的语音执行文本转语音（TTS）时，请使用本技能。
• 为便于长期维护，克隆结果会自动回写至本文件，以减少重复配置工作。

API 参考（MiniMax）

• 上传克隆音频：POST /v1/files/upload，参数 purpose=voice_clone，请求体格式为 multipart/form-data。
• 创建克隆语音：POST /v1/voice_clone。
• 语音合成：POST /v1/t2a_v2。
• 音频要求：支持格式为 mp3/m4a/wav，时长需在 10 秒–5 分钟 之间，文件大小须 <=20MB。

安装

• 运行时环境： Python 3.7+。
• 依赖项： 脚本使用 requests 库。可通过以下命令安装：

  pip install -r requirements.txt
  

  或直接运行 pip install requests。
• 网络： 脚本通过 HTTPS 调用 MiniMax API；不读取任何无关系统文件。仅读取/写入本技能的 SKILL.md 文件，用于更新“克隆语音映射”区块。

必需的环境变量（凭据）

为完成 MiniMax API 认证，至少需设置下列环境变量之一（参见 frontmatter 中的 requiredEnv / optionalEnv）：

若未设置任一变量，脚本将报出明确错误并退出。

前提条件

1. 凭据： 设置上述任一环境变量（详见“必需的环境变量”）。
2. 准备待克隆的音频（需满足前述格式、时长与大小限制）。
3. 克隆前，请务必与用户确认语音名称（voice_name），例如：liuyang_narration_v1。

使用方法

1. 进入技能目录：cd workspace/skills/voice-clone-tts
2. 运行脚本（执行克隆 + 合成）：

python scripts/minimax_voice_clone_tts.py 
  --audio "/absolute/path/to/voice.wav" 
  --voice-name "yangtuo_demo_v1" 
  --display-name "Alpaca Demo" 
  --text "Hello, this is a cloned voice test." 
  --output "./output/voice_test.mp3"

3. 如仅需克隆（不执行合成），请省略 --text 参数。
4. 如仅需合成（通过 display name 或 voice_id 指定已有语音）：

# 通过 display name 解析
python scripts/minimax_voice_clone_tts.py 
  --voice "voice_v2" 
  --text "This is TTS using an existing cloned voice." 
  --output "./output/reuse_voice.mp3"

# 或直接指定 voice_id
python scripts/minimax_voice_clone_tts.py 
  --voice-id "yangtuo_demo_v1" 
  --text "This is TTS using an existing cloned voice." 
  --output "./output/reuse_voice.mp3"

常用参数

• --audio：克隆音频路径（克隆操作必需）。
• --voice-name：克隆时必需；API 所用的 voice ID（仅允许字母、数字及下划线，例如 yangtuo_demo_v1）。
• --display-name：克隆时可选；将写入 SKILL 的显示名称（例如 Alpaca Demo）；若未指定，则默认与 --voice-name 相同。
• --voice-id：合成时使用，直接指定 API voice_id（跳过映射表解析）。
• --voice：合成时使用，指定显示名称或 voice_id；由下方映射表解析（例如 voice_v2 或 yangtuo_demo_v1）。
• --text：待合成的文本（仅克隆时可省略）。
• --output：输出音频路径（默认为 ./output/minimax_tts.mp3）。
• --model：语音模型（默认为 speech-2.8-turbo）。
• --format：输出格式（支持 mp3/pcm/flac/wav）。
• --speed --vol --pitch --emotion：语音表现力参数（语速、音量、音高、情感）。

回写机制（重要）

• 克隆成功后，脚本会将 显示名称 → voice_id 映射关系写入下方“克隆语音映射”区块。
• 建议在 TTS 时使用 --voice "显示名称"，从而无需记忆 voice_id。

克隆语音映射

• 左侧为显示名称，右侧为 API voice_id。TTS 时可使用 --voice "显示名称" 或 --voice-id voice_id。

• test_voice_1772187110: test_voice_1772187110（更新时间：2026-02-27 18:12:00）
• voice_v1: shuangyue_test（更新时间：2026-02-28 16:47:01）
• voice_v2: yangtuo_demo_v1（更新时间：2026-02-27 18:19:39）
• voice_v3: dong_yuhui_voice_v1（更新时间：2026-03-02 19:51:44）

故障排查

• 401 错误 / 认证失败：请检查 MINIMAX_API_KEY 是否正确。
• 参数错误：请检查 voice_name 命名规则、音频格式/大小以及文本长度是否符合要求。
• 克隆成功但未回写：请确保 SKILL.md 文件存在，且其中包含回写标记区块（即 和 ）。