skills/minimax-music-codex/SKILL.md

name, description

name	description
minimax-music	调用 MiniMax music-3.0 生成音乐（带唱歌曲、纯音乐、自动作词、翻唱），并裁成定长无缝循环 BGM。触发关键词：「生成音乐」「做首歌」「写首歌」「AI 作曲」「生成 BGM」「背景音乐」「配乐」「纯音乐」「器乐」「MiniMax 音乐」「music-3.0」「翻唱」「循环 BGM」「游戏配乐」「短片配乐」。

MiniMax 音乐生成

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

脚本

• scripts/generate.py：调 API 生成音乐（Python 3 标准库）
• scripts/loopify.py：裁成定长无缝循环 + 客观验收（依赖 ffmpeg + numpy）

API Key

优先读环境变量 MINIMAX_API_KEY，否则读 ~/.config/minimax_api_key。不要把 key 写进代码或提交。

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

计费

music-3.0 / music-2.6 / music-cover 约 ¥1/首；对应 -free 模型免费但 RPM 3。试风格、调 prompt 一律先用 --free，定稿再跑付费模型。

用法

S=~/.codex/skills/minimax-music/scripts

# 纯音乐（游戏 BGM 常用）
python3 $S/generate.py "中世纪奇幻大地图探索，鲁特琴+竖琴+木笛，中慢速，无鼓" --instrumental -o bgm.mp3

# 带唱：lyrics 必填
python3 $S/generate.py "独立民谣，忧郁内省" -l @lyrics.txt -o song.mp3

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

# 翻唱：参考音频 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

常用参数：-l/--lyrics、--instrumental、--auto-lyrics、--cover、-m/--model、--free、-o/--output、--sample-rate、--bitrate、--format、--hex。

定长无缝循环 BGM

接口没有 duration 参数，时长不可控。游戏/短片要定长循环必须后期处理：

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

它会测速并对齐整数小节、扫描最优接缝、交叉淡化、峰值留余量，并输出客观验收。--preview 3 额外导出连播三遍的文件，循环 BGM 必须循环听至少 3 分钟。

若验收有项未通过（常见为接缝前后 RMS 差），换 -L 30 / -L 60 等循环长度重试。

写 prompt 的要点

循环 BGM 要写「稳定」：全曲同调性、同速度、同织体密度，明确不要前奏尾奏、不要渐强、不要淡出结尾。

• 写死速度和拍号：「中慢速约 80 BPM，6/8 摇曳律动，自然小调」
• 逐件点名配器：「古筝分解和弦作骨架，三味线点缀，尺八吹主旋律，柔和弦乐铺底」
• 一定写否定项：「严格不要：人声、歌词、吟唱、现代流行元素、电子合成器、重鼓组、密集打击乐」
• 中英混写没问题，关键风格用英文直接写：Japanese traditional, wafuu orchestral, instrumental, loopable, game soundtrack

工作流

1. 明确用途和时长要求
2. 先用 --free 试 1-2 版确认方向
3. 方向对了跑付费模型定稿
4. 要循环就接 loopify.py，看验收是否全项通过
5. 成品路径告诉用户；循环 BGM 一并给 --preview 试听文件

错误码

HTTP 200 不代表成功，看 base_resp.status_code：0 成功、1002 限流、1004 鉴权失败、1008 余额不足、1026 敏感内容、2013 参数错。