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）节点

第三步：填写配置

获取以上信息后：

1. 修改 scripts/generate.py 顶部的配置常量（ API_KEY、 BASE_URL），填入实际值
2. 如果用户提供了 API Key → 设置 USE_FREE_MODEL = False
3. 如果用户未提供 API Key → 保持 USE_FREE_MODEL = True
4. 同时更新下方 ## 配置 区段的表格，作为配置记录

第四步：清理

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

---

配置#

配置项值说明MINIMAX_API_KEY<待填入>初始化时替换为实际 keyBASE_URL<待填入>CN: https://api.minimaxi.com / Global: https://api.minimaxi.ioUSE_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 生成歌词后再生成音乐。

bash

SKILL_DIR="~/.openclaw/workspace/skills/minimax-tokenplan-music"
python3 "$SKILL_DIR/scripts/generate.py" \
    --prompt "一首关于夏天海边的轻快情歌"

2. 带歌词的音乐#

bash

python3 "$SKILL_DIR/scripts/generate.py" \
    --prompt "独立民谣,忧郁,内省" \
    --lyrics "[verse]
街灯微亮晚风轻抚
影子拉长独自漫步
[chorus]
推开木门香气弥漫
熟悉的角落陌生人看"

3. 从文件读取歌词#

bash

python3 "$SKILL_DIR/scripts/generate.py" \
    --prompt "流行,欢快,夏日" \
    --lyrics-file /path/to/lyrics.txt

4. 纯音乐（Instrumental）#

bash

python3 "$SKILL_DIR/scripts/generate.py" \
    --prompt "轻快的钢琴曲,治愈,咖啡馆" \
    --instrumental

5. 翻唱（本地参考音频）#

bash

python3 "$SKILL_DIR/scripts/generate.py" \
    --prompt "清新女声翻唱" \
    --cover \
    --audio "/path/to/reference.mp3"

6. 翻唱（URL 参考音频）#

bash

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/4410044100``--bitrate❌比特率: 32000/64000/128000/256000256000``--format / -f❌音频格式: mp3/wav/pcmwav``--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 生成完整歌词，再用于音乐生成。

---

工作流总结#

文生音乐完整流程#

1. 确定模式 → 文生音乐 / 纯音乐 / 翻唱
2. 歌词处理 → 用户提供 / 自动生成 / 纯音乐跳过
3. 选择模型 → music-2.6(-free) / music-cover(-free)
4. 调用 API → 自动处理 HEX 解码
5. 保存文件 → WAV/MP3/PCM 格式

翻唱完整流程#

1. 用户提供参考音频 → URL 或本地文件
2. 脚本自动处理 → URL 直接传递 / 本地文件转 base64
3. 选择模型 → music-cover(-free)
4. 调用 API → 生成翻唱音频
5. 保存文件

---

脚本输出格式#

调用 generate.py 后， stdout 输出生成结果：

output_formatstdout 输出示例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 Key1008余额不足提醒充值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 较低