前言¶
在 Agent 里做「生成一段 BGM」「写词并出成品」时，常见做法是临时查 MiniMax 文档、手写 curl 或零散脚本，再把 API Key、模型和输出路径拼在一起。步骤多、容易漏鉴权或搞错「歌词接口」与「音乐接口」所需的套餐类型。
下面介绍社区 Skill @user_c9d52b8e/minimax-music-v2（名称：使用 minimax 的 TokenPlanKey 生成音乐）。它把歌词生成、音乐生成和本地播放封装成可复用的 SKILL.md 与脚本，由 Agent 在用户提到作曲、AI 音乐等意图时自动触发。
这是什么¶
一句话定位：基于 MiniMax Music Generation API 的 Agent Skill，用脚本调用官方接口生成歌词与音频。
- 坐标：
@user_c9d52b8e/minimax-music-v2 - 版本：1.0.0
- 来源：SkillHub 社区（
community），发布者user_c9d52b8e - 分类：design-media
- SkillHub 页面：https://www.skillhub.cn/skills/user_c9d52b8e/minimax-music-v2
- 资料地址：https://api.skillhub.cn/user_c9d52b8e/minimax-music-v2
Skill 声明的触发场景：用户要求生成音乐、创作歌曲、作曲，或提到「AI 音乐」「生成歌曲」等。标签 requires_api_key=true，使用前需配置 MiniMax API Key。
核心功能¶
以下能力均来自 Skill 自带的 SKILL.md 与参考文档，经安装包核对。
- 歌词生成：根据主题描述生成完整歌词，支持多种模式（如
write_full_song、write_lyrics_only、optimize_lyrics）。 - 音乐生成：根据风格/情绪/场景描述生成音频；可附带歌词，或加
--instrumental生成无人声纯音乐。 - 本地播放：生成后可用
play_music.py播放 mp3/wav（依赖pyglet）。 - 模型与格式：默认模型
music-2.6（Skill 标注为已验证可用）；可选输出 mp3/wav/pcm，并配置采样率、比特率等。
API 与 Key 说明（Skill 内文档）
- 音乐生成接口：
POST https://api.minimaxi.com/v1/music_generation，请求头Authorization: Bearer <API_KEY>。 - Key 获取：https://platform.minimaxi.com/user-center/basic-information/interface-key
- Lyrics Generation 可使用 Coding Plan Key；Music Generation 需要独立的音乐 Plan。推荐模型
music-2.6需音乐 Plan；music-2.6-free为限免版，需单独申请。名称中的 Token Plan Key 与官方文档中的 Token Plan / 付费套餐对应关系，以 MiniMax 控制台实际开通的 Plan 为准。
生成文件默认落在工作区下的 minimax-music-output/；歌词默认打印到终端，也可用 -o 写入指定路径。
安装与启用¶
1. 安装 SkillHub CLI（若尚未安装）¶
command -v skillhub && skillhub --version
未安装时可按 SkillHub 安装说明执行（完整安装示例）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
2. 安装本 Skill 到当前 Agent 的 skills 目录¶
SkillHub 要求安装时必须用 --dir 指向 Agent 识别的 skills 目录，否则默认 ./skills/ 可能不会被加载。
skillhub install @user_c9d52b8e/minimax-music-v2 --dir <你的 skills 目录>
常用路径（来自 SkillHub 安装文档）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
也可让 Agent 按 https://skillhub.cn/install/skillhub.md 的说明安装 @user_c9d52b8e/minimax-music-v2。
3. 配置 API Key¶
任选其一：
- 在 Skill 目录下的
config.json填写api_key字段； - 设置环境变量
MINIMAX_API_KEY。
config.json 结构示例：
{
"api_key": ""
}
4. Python 依赖¶
脚本通过 uv run 按需拉取依赖；也可预先安装：
uv pip install --python python requests pyglet
requests 用于 HTTP；pyglet 仅在需要 --play 播放时用到。
典型用法¶
将 <skill> 替换为安装后的 Skill 根目录（例如 ~/.cursor/skills/@user_c9d52b8e/minimax-music-v2）。
生成歌词
uv run --with requests python <skill>/scripts/lyrics_generate.py "一首关于夏日海边的轻快情歌"
保存到文件：
uv run --with requests python <skill>/scripts/lyrics_generate.py "描述" -o lyrics.txt
生成带人声的音乐（需音乐 Plan，默认 music-2.6）
uv run --with requests --with pyglet python <skill>/scripts/music_generate.py "流行音乐,欢快,阳光" \
--lyrics "[Verse]\n街道边的树叶\n阳光穿过缝隙" \
--play
纯音乐（无人声）
uv run --with requests --with pyglet python <skill>/scripts/music_generate.py "钢琴独奏,安静,放松" --instrumental --play
指定模型与播放已有文件
uv run --with requests --with pyglet python <skill>/scripts/music_generate.py "..." -m music-2.6
uv run --with pyglet python <skill>/scripts/play_music.py audio.mp3
prompt 建议写法（Skill 参考）：风格,情绪,场景，多维度用逗号分隔，例如 "电子音乐,充满能量,健身"。歌词中可使用 [Verse]、[Chorus] 等结构标签。
在 Cursor 等支持 Skills 的客户端中，安装并配置 Key 后，直接用自然语言描述需求即可；Agent 读取 SKILL.md 后会按上述脚本路径执行。
适用场景与注意¶
适合谁
- 已在 MiniMax 开通接口 Key，并具备音乐 Plan（或试用
music-2.6-free等限免模型）的开发者。 - 希望在 Agent 对话里完成「写词 → 出曲 → 本地试听」，而不每次手写 HTTP 请求的团队。
限制与常见问题
- 套餐：仅配置 Coding Plan Key 时，歌词接口可能可用，但
music-2.6等音乐生成仍受音乐 Plan 约束；余额不足、鉴权失败时，官方错误码包括1004、1008、2049等（见 Skill 内references/models.md）。 - 限流与内容：
1002表示限流；1026表示内容敏感，需调整 prompt 或歌词。 - 运行环境：播放依赖
pyglet，在无图形/音频环境的远程沙箱中可能失败；可去掉--play，只保留输出文件。 - 合规：生成内容需遵守 MiniMax 平台规则；Skill 为社区发布，维护节奏以 SkillHub 页面与安装包为准。
SkillHub 统计（抓取资料）：评分 100000，下载 612 次，安装 19 次。
结尾¶
@user_c9d52b8e/minimax-music-v2 把 MiniMax 歌词与音乐 API、本地脚本和 Agent 触发说明收拢在一套 Skill 里，适合把「AI 作曲」从一次性脚本变成可重复的工作流。安装、Key 与 Plan 就绪后，用自然语言或上述 uv run 命令即可复现。
官方资料入口：
- https://www.skillhub.cn/skills/user_c9d52b8e/minimax-music-v2
- https://api.skillhub.cn/user_c9d52b8e/minimax-music-v2
