---
name: minimax-music
description: 调用 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`，定稿再跑付费模型。

## 用法

```bash
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 参数，时长不可控。游戏/短片要定长循环必须后期处理：

```bash
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` 参数错。