---
name: minimax-music
description: 调用 MiniMax music-3.0 生成音乐（带唱歌曲/纯音乐/自动作词/翻唱），并可裁成定长无缝循环 BGM。触发关键词：「生成音乐」「做首歌」「写首歌」「AI 作曲」「生成 BGM」「背景音乐」「配乐」「纯音乐」「器乐」「MiniMax 音乐」「music-3.0」「翻唱」「循环 BGM」「游戏配乐」「短片配乐」。适用场景：游戏/短片/播客的背景音乐、Demo 小样、根据歌词谱曲、按参考音频翻唱。
version: 1.0.0
author: 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`（免费且不限次数，只限速率），定稿再跑付费模型。

## 四种模式

```bash
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，纯音乐普遍更长因为没有歌词框住它）。游戏/短片要定长循环，必须后期处理：

```bash
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](https://platform.minimaxi.com/docs/api-reference/music-generation)
- [音乐生成指南](https://platform.minimaxi.com/docs/guides/music-generation)
- [按量付费定价](https://platform.minimaxi.com/docs/guides/pricing-paygo)