skills/minimax-music/SKILL.md

name, description, version, author

name	description	version	author
minimax-music	调用 MiniMax music-3.0 生成音乐（带唱歌曲/纯音乐/自动作词/翻唱），并可裁成定长无缝循环 BGM。触发关键词：「生成音乐」「做首歌」「写首歌」「AI 作曲」「生成 BGM」「背景音乐」「配乐」「纯音乐」「器乐」「MiniMax 音乐」「music-3.0」「翻唱」「循环 BGM」「游戏配乐」「短片配乐」。适用场景：游戏/短片/播客的背景音乐、Demo 小样、根据歌词谱曲、按参考音频翻唱。	1.0.0	william

MiniMax 音乐生成 Skill

调用 MiniMax music-3.0 生成音乐并下载到本地；需要定长循环 BGM 时再用 loopify.py 做后期。

触发判断

用户说"生成一段音乐/BGM/配乐"、"做首歌"、"写首纯音乐"、"给这个视频配个乐"、"游戏循环 BGM"等 → 按下方流程执行。

两个脚本

脚本	作用	依赖
generate.py	调 API 生成音乐	Python 3 标准库
loopify.py	裁成定长无缝循环 + 客观验收	ffmpeg + numpy

API Key

优先读环境变量 MINIMAX_API_KEY，否则读 ~/.claude/skills/minimax-music/key.txt（权限 600）。切换用 export MINIMAX_API_KEY=<新key>。

⚠️ 区域必须匹配：国内 key 配 api.minimaxi.com（脚本内置），海外 key 要改成 api.minimax.io，否则报鉴权失败。

计费

模型	价格	RPM
music-3.0 / music-2.6 / music-cover	¥1.0 / 首	120
music-3.0-free / music-2.6-free / music-cover-free	免费	3

按"首"计费，不按秒。 试风格、调 prompt 一律先用 --free（免费且不限次数，只限速率），定稿再跑付费模型。

四种模式

S=~/.claude/skills/minimax-music

# 1. 带唱：lyrics 必填，prompt 可选
python3 $S/generate.py "独立民谣，忧郁内省，木吉他分解和弦+弦乐铺底" -l @lyrics.txt -o song.mp3

# 2. 纯音乐：反过来，prompt 必填，lyrics 可省
python3 $S/generate.py "中世纪奇幻大地图探索，鲁特琴+竖琴+木笛，中慢速，无鼓" --instrumental -o bgm.mp3

# 3. 自动作词：不用自己写词
python3 $S/generate.py "抒情流行，夏夜告别，遗憾但释然" --auto-lyrics -o auto.mp3

# 4. 翻唱：参考音频 6s-6min、<=50MB
python3 $S/generate.py "" --cover ref.mp3 -l "[Verse]\n新歌词..." -o cover.mp3

# 免费试跑（任何模式加 --free）
python3 $S/generate.py "..." --instrumental --free -o test.mp3

常用参数

参数	说明	默认
prompt（位置）	曲风/情绪/场景，≤2000 字	纯音乐时必填
-l, --lyrics	歌词 ≤3500 字，\n 分行，支持 @文件	带唱时必填
--instrumental	纯音乐	否
--auto-lyrics	模型自动作词	否
--cover	翻唱参考音频（路径或 URL）	—
-m, --model	模型	music-3.0
--free	换成对应免费模型	否
-o, --output	输出路径	时间戳命名
--sample-rate / --bitrate / --format	16000/24000/32000/44100、32000/64000/128000/256000、mp3/wav/pcm	见粗体
--hex	用 hex 返回而非 url	否

歌词格式

用 [Intro] [Verse] [Chorus] [Bridge] [Outro] 分段，段间空行：

[Verse]
雨把街灯揉成一片橙黄
玻璃门后面有人在张望

[Chorus]
你转身的那一秒
雨就轻了一点点

定长无缝循环 BGM

接口没有 duration 参数，时长完全不可控（实测：带唱 61s、纯音乐 97-126s，纯音乐普遍更长因为没有歌词框住它）。游戏/短片要定长循环，必须后期处理：

python3 $S/loopify.py raw.mp3 -o bgm_loop.mp3 -L 45 --preview 3

它做四件事：

1. 测实际速度，把循环长度对齐到整数小节。只对齐电平不对齐节奏的话，循环起来会丢拍——这是最容易翻车的地方。-L 45 --tol 1.0 表示在 44-46s 里找整小节长度。
2. 扫描起点，比较首尾 2 秒的 RMS + 频谱质心 + 低频占比，选最接近的窗口，并避开渐入、渐出、能量凹陷。
3. qsin 等功率曲线做尾→头交叉淡化（默认 2.0s），并自动把峰值压到 --peak（默认 -1.0 dBFS）留余量。
4. 客观验收：峰值削波、异常静音、接缝逐样本跳变 vs 曲内 99.9 分位跳变、接缝前后 RMS 差、立体声宽度。

--preview 3 会额外导出连播三遍的文件——循环 BGM 一定要循环着听至少 3 分钟，单听一遍听不出接缝和"听腻"的问题。

写 prompt 的要点

先想清楚这段音乐会不会被循环播放，两种写法是相反的：

	一次性配乐（短片/过场）	循环 BGM（游戏/等待画面）
情绪	写情绪曲线："开头克制，中段弦乐推起，结尾回落渐弱"	写稳定："全曲同调性、同速度、同织体密度，平稳流动"
结构	可以有前奏尾奏	明确不要前奏尾奏、不要渐强、不要淡出结尾
旋律	可以抓耳	克制、留白多、听十分钟不腻

其余通用要点：

• 写死速度和拍号："中慢速约 80 BPM，6/8 摇曳律动，自然小调"
• 逐件点名配器："鲁特琴分解和弦作骨架，竖琴琶音点缀，木笛吹主旋律，柔和弦乐铺底"
• 一定要写否定项。不写它很容易自己加鼓、加合成器、加人声，配画面就吵了： "严格不要：人声、歌词、吟唱、现代流行元素、电子合成器、重鼓组、密集打击乐"
• 中英混写没问题；有必须命中的风格关键词就直接用英文写进去（medieval fantasy, orchestral, instrumental, loopable, game soundtrack）

工作流

1. 明确用途（配画面？循环 BGM？独立歌曲？）和时长要求
2. 按上表写 prompt，先用 --free 试 1-2 版确认方向
3. 方向对了跑付费 music-3.0 定稿（¥1）
4. 要定长循环就接 loopify.py，看验收输出是否全项通过
5. 把成品路径告诉用户；循环 BGM 一并给 --preview 的试听文件

坑

1. HTTP 200 不代表成功。一律看 base_resp.status_code：0 成功、1002 限流、1004 鉴权失败、1008 余额不足、1026 敏感内容、2013 参数错。脚本已处理并翻译成人话。
2. output_format 接口默认是 hex（一大串十六进制塞在 JSON 里）。脚本默认改成了 url 并自动下载，两种都兼容。url 链接 24 小时过期，别只存链接。
3. extra_info 里没有计费字段（不像视频接口有 usage），没法从响应对账，只能自己按"首"数。
4. 必填是条件性的：纯音乐要 prompt、带唱要 lyrics，反了会 2013。脚本在发请求前就本地拦截，不会白花钱。
5. 翻唱三个参数互斥：audio_url / audio_base64 / cover_feature_id 只能给一个；cover_feature_id 24 小时过期。
6. 两份官方文档的歌词长度打架：API 参考写 1-3500 字，指南写 10-1000 字。后者只适用于带 cover_feature_id 的翻唱。
7. free 模型限 RPM 3，串行调用够用，别并发。
8. 输出电平不稳定：实测同样参数，有的曲子峰值 -2.3 dBFS，有的直接 0.0 dBFS 顶格。顶格素材做交叉淡化时两路叠加必然削波，loopify.py 已自动衰减留余量；如果你自己用 ffmpeg 拼接，记得先量峰值。

参考

• 音乐生成 API
• 音乐生成指南
• 按量付费定价