MiniMax Music Generation Skill
前置条件
- Python 3 已安装
- requests 库：
pip3 install requests
init
需要初始化以下信息：
第一步：获取 API Key
向用户获取 MiniMax API Key（sk-cp- 开头的 Token Plan key，或普通 API Key）。
如果用户不提供 API Key：保持 USE_FREE_MODEL = True，使用免费模型（music-2.6-free / music-cover-free），RPM 较低但无需付费。
第二步：确认配置
向用户确认：
- API Key 是否正确（如果提供了的话）
- 使用国内（
https://api.minimaxi.com）还是海外（https://api.minimaxi.io）节点
第三步：填写配置
获取以上信息后：
- 修改
scripts/generate.py顶部的配置常量（API_KEY、BASE_URL），填入实际值 - 如果用户提供了 API Key → 设置
USE_FREE_MODEL = False - 如果用户未提供 API Key → 保持
USE_FREE_MODEL = True - 同时更新下方
## 配置区段的表格，作为配置记录
第四步：清理
配置填写完成后，删除本 ## init 区段（包括 ### 需要初始化以下信息 的全部内容），仅保留 ## 配置 区段。
配置
| 配置项 | 值 | 说明 |
|---|---|---|
| MINIMAX_API_KEY | <待填入> | 初始化时替换为实际 key |
| BASE_URL | <待填入> | CN: https://api.minimaxi.com / Global: https://api.minimaxi.io |
| USE_FREE_MODEL | <待填入> | 有 API Key: False（付费模型） / 无 API Key: True（免费模型） |
模型说明
| 模型 | 说明 | 适用场景 |
|---|---|---|
music-2.6 | 文生音乐（付费，高 RPM） | Token Plan 用户 |
music-2.6-free | 文生音乐（免费，低 RPM） | 所有用户 |
music-cover | 翻唱（付费，高 RPM） | Token Plan 用户 |
music-cover-free | 翻唱（免费，低 RPM） | 所有用户 |
脚本根据
USE_FREE_MODEL和--cover参数自动选择模型，无需手动指定。
快速使用
注意：以下示例中
generate.py均指~/.openclaw/workspace/skills/minimax-tokenplan-music/scripts/generate.py的完整路径。
1. 文生音乐（自动生成歌词）
当不提供 --lyrics 且不传 --instrumental 时，脚本会自动调用歌词生成 API，根据 prompt 生成歌词后再生成音乐。
SKILL_DIR="~/.openclaw/workspace/skills/minimax-tokenplan-music"
python3 "$SKILL_DIR/scripts/generate.py" \
--prompt "一首关于夏天海边的轻快情歌"
2. 带歌词的音乐
python3 "$SKILL_DIR/scripts/generate.py" \
--prompt "独立民谣,忧郁,内省" \
--lyrics "[verse]
街灯微亮晚风轻抚
影子拉长独自漫步
[chorus]
推开木门香气弥漫
熟悉的角落陌生人看"
3. 从文件读取歌词
python3 "$SKILL_DIR/scripts/generate.py" \
--prompt "流行,欢快,夏日" \
--lyrics-file /path/to/lyrics.txt
4. 纯音乐（Instrumental）
python3 "$SKILL_DIR/scripts/generate.py" \
--prompt "轻快的钢琴曲,治愈,咖啡馆" \
--instrumental
5. 翻唱（本地参考音频）
python3 "$SKILL_DIR/scripts/generate.py" \
--prompt "清新女声翻唱" \
--cover \
--audio "/path/to/reference.mp3"
6. 翻唱（URL 参考音频）
python3 "$SKILL_DIR/scripts/generate.py" \
--prompt "翻唱风格描述" \
--cover \
--audio "https://example.com/song.mp3"
参数说明
| 参数 | 必填 | 说明 | 默认值 |
|---|---|---|---|
--prompt / -p | 条件 | 音乐风格描述（文生音乐: 1-2000字符；翻唱: 10-300字符） | - |
--lyrics / -l | ❌ | 歌词内容，\n 分隔，支持结构标签 | 自动生成 |
--lyrics-file | ❌ | 从文件读取歌词（与 --lyrics 互斥） | - |
--instrumental | ❌ | 生成纯音乐（无人声） | 关闭 |
--cover | ❌ | 翻唱模式（需提供 --audio） | 关闭 |
--audio / -a | 翻唱必填 | 参考音频: URL 或本地路径（6秒-6分钟，最大50MB） | - |
--stream | ❌ | 流式输出（output_format 强制为 hex） | 关闭 |
--output-format | ❌ | hex（默认）或 url（24小时有效链接） | hex |
--sample-rate | ❌ | 采样率: 16000/24000/32000/44100 | 44100 |
--bitrate | ❌ | 比特率: 32000/64000/128000/256000 | 256000 |
--format / -f | ❌ | 音频格式: mp3/wav/pcm | wav |
--aigc-watermark | ❌ | 添加 AIGC 水印（非流式模式） | 关闭 |
--lyrics-optimizer | ❌ | 根据 prompt 自动生成歌词（music-2.6 系列） | 关闭 |
--output / -o | ❌ | 输出路径 | 自动生成 |
--api-key | ❌ | API Key（默认使用文件顶部配置） | - |
--base-url | ❌ | Base URL（默认使用文件顶部配置） | - |
--timeout | ❌ | 超时秒数 | 240 |
歌词结构标签
在歌词中使用以下标签标注歌曲结构：
| 标签 | 含义 | 标签 | 含义 |
|---|---|---|---|
[Intro] | 前奏 | [Verse] | 主歌 |
[Pre Chorus] | 预副歌 | [Chorus] | 副歌 |
[Interlude] | 间奏 | [Bridge] | 桥段 |
[Outro] | 尾奏 | [Post Chorus] | 后副歌 |
[Transition] | 过渡 | [Break] | 停顿 |
[Hook] | 记忆点 | [Build Up] | 铺垫 |
[Inst] | 器乐段 | [Solo] | 独奏 |
自动歌词生成规则
| 情况 | 处理方式 |
|---|---|
--instrumental | 纯音乐，不生成歌词 |
提供了 --lyrics 或 --lyrics-file | 使用用户提供的歌词 |
--lyrics-optimizer | 由 API 根据 prompt 自动生成歌词 |
| 以上都不满足（非纯音乐 + 无歌词） | 自动调用 lyrics_generation API 生成歌词 |
例如用户说"创建一首非纯音乐"但没给歌词，脚本会先调用歌词 API 生成完整歌词，再用于音乐生成。
工作流总结
文生音乐完整流程
- 确定模式 → 文生音乐 / 纯音乐 / 翻唱
- 歌词处理 → 用户提供 / 自动生成 / 纯音乐跳过
- 选择模型 → music-2.6(-free) / music-cover(-free)
- 调用 API → 自动处理 HEX 解码
- 保存文件 → WAV/MP3/PCM 格式
翻唱完整流程
- 用户提供参考音频 → URL 或本地文件
- 脚本自动处理 → URL 直接传递 / 本地文件转 base64
- 选择模型 → music-cover(-free)
- 调用 API → 生成翻唱音频
- 保存文件
脚本输出格式
调用 generate.py 后，stdout 输出生成结果：
| output_format | stdout 输出 | 示例 |
|---|---|---|
hex（默认） | 保存后的文件绝对路径 | ~/.openclaw/media/minimax/music/music-2026-04-11-summer-song.wav |
url | 音乐的公网 URL（24小时有效） | https://filecdn.minimax.chat/... |
所有日志信息（
[INFO]、[WARN]、[ERROR]）输出到 stderr，不会混入 stdout。
文件存储
- 默认保存到：
~/.openclaw/media/minimax/music/（多 Agent 共享目录） - 文件名格式：
music-YYYY-MM-DD-<slug>.<format> - slug：取 prompt 前20字符，保留中英文数字，空格变
-
错误处理
| code | 含义 | 处理 |
|---|---|---|
| 0 | 成功 | 继续 |
| 1002 | 限流 | 提醒用户 API 限流中，建议稍后重试 |
| 1004 | 鉴权失败 | 检查 API Key |
| 1008 | 余额不足 | 提醒充值 |
| 1026 | 敏感词 | 换词后重试 |
| 2013 | 参数异常 | 检查入参 |
| 2049 | 无效 Key | 检查 Key 是否正确 |
注意事项
- HEX 解码：API 返回的 audio 字段是 HEX 编码（不是 base64），脚本自动处理
- 翻唱参考音频：6秒-6分钟，最大50MB，支持 mp3/wav/flac 等格式
- URL 有效期：
output_format=url返回的链接仅 24 小时有效 - 流式限制：流式模式下
output_format强制为hex，不支持 AIGC 水印 - 免费模型：
*-free模型对所有用户开放，RPM 较低