前言¶
给 Agent 加音乐生成能力时，常见两条路：接 Suno 这类商业服务，按量付费，有订阅和额度限制；自己部署开源模型，硬件和维护成本高。下面介绍的 Skill 走的是第三条路：调用 ACE Music 的免费托管 API，背后是 ACE-Step 1.5 模型，生成带人声、歌词、任意风格和语言的完整歌曲，不订阅、不扣额度。它解决的问题是：Agent 在被要求「写首歌、做个 beat、配段音乐」时，能直接产出可用的音频文件，而不用先让用户去开通付费账号。
这是什么¶
ACE Music（Skill 坐标 @clawhub_fspecii/ace-music，版本 1.0.0）是一个基于通用 SKILL.md 格式的 Agent Skill，由开发者 fspecii 发布在 ClawHub，上游仓库为 https://clawhub.ai/fspecii/ace-music，许可为 MIT-0。SkillHub 页面将其归入 design-media 分类，标签显示 requires_api_key=true。它在 SkillHub 上的快照显示评分 100000、下载 9836、安装 162（该数字来自预抓取资料，未能在官网页面二次核对）。
一句话定位：让 Agent 通过一句命令行脚本，把文本提示变成一段 MP3 音乐文件。
核心功能¶
已核实的能力：
- 文生音乐（text2music，默认模式）：根据文本提示或歌词生成完整歌曲，支持人声。
- 自定义歌词：通过
--lyrics传入带[Verse]、[Chorus]标记的歌词。 - 纯器乐：
--instrumental关闭人声。 - 翻唱（cover）与重绘（repaint）：基于已有音频二次创作，完整 API 规格见 Skill 内
references/api-docs.md。 - 多语言人声：
--language支持 zh、en、ja、ko 等。 - 可复现生成：
--seed固定随机种子。 - 批量变体：
--batch一次生成多个版本。
底层模型为 ACE-Step 1.5，API Base URL 为 https://api.acemusic.ai。音频以 base64 MP3 返回，脚本自动解码成文件。
安装与启用¶
官方安装命令（ClawHub Skills CLI）：
openclaw skills install @fspecii/ace-music
安装后，Skill 包内自带 scripts/generate.sh，后续所有生成都通过这个脚本完成。本 Skill 面向 OpenClaw 生态，安装命令以官方 SKILL.md 为准；Cursor / Codex CLI / Claude Code 是否可直接复用同一安装方式，官方资料未说明，不在此臆测。
配置 API Key¶
脚本读取环境变量 ACE_MUSIC_API_KEY。若未设置，按以下步骤操作：
- 让用户在浏览器打开 https://acemusic.ai/playground/api-key ；
- 注册免费账号并复制 API Key；
- 写入环境变量或配置文件：
export ACE_MUSIC_API_KEY=<key>
或写入 TOOLS.md，供 Agent 运行时读取。
典型用法¶
下面命令均来自官方 SKILL.md，可直接复现。脚本把生成的音频文件路径打印到 stdout，需要由 Agent 取出文件并发给用户。
最简单的用法，只给一句提示，其余交给 AI：
scripts/generate.sh "upbeat pop song about summer" --duration 30 --output summer.mp3
带歌词：
scripts/generate.sh "gentle acoustic ballad, female vocal" \
--lyrics "[Verse 1]\nSunlight through the window\n\n[Chorus]\nWe are the dreamers" \
--duration 60 --output ballad.mp3
纯器乐：
scripts/generate.sh "lo-fi hip hop beats, chill, rainy day" --instrumental --duration 120 --output lofi.mp3
自然语言描述，让 AI 全权决定风格与歌词：
scripts/generate.sh "write me a jazz song about coffee" --sample-mode --output jazz.mp3
指定节奏、调性、语言、种子：
scripts/generate.sh "rock anthem" --bpm 140 --key "E minor" --language en --seed 42 --output rock.mp3
一次生成多个版本：
scripts/generate.sh "electronic dance track" --batch 3 --output edm.mp3
常用参数对照：
| 需求 | 参数 |
|---|---|
| 特定风格 | 在提示词里描述，如 “jazz, saxophone solo, smoky bar” |
| 自定义歌词 | --lyrics "[Verse]...[Chorus]..." |
| AI 全权创作 | --sample-mode |
| 无人声 | --instrumental |
| 更长时长 | --duration 120（秒） |
| 指定速度 | --bpm 120 |
| 指定调性 | --key "C major" |
| 多个版本 | --batch 3 |
| 可复现 | --seed 42 |
| 非英语人声 | --language ja（支持 zh、en、ja、ko 等） |
适用场景与注意¶
适合：Agent 需要按用户一句话请求产出歌曲、节拍、配乐原型；想零成本试 AI 音乐能力，不想碰订阅和额度。
注意：
- 需要 API Key，虽然注册免费，但 Key 必须由用户自行申请，Skill 不会替你生成。
--duration省略时由 AI 根据内容自行决定时长，对结果长度有要求时要显式指定。- 官方建议使用 tagged mode（提示词与歌词分离）以获得更好效果。
- 封面、重绘等需要音频输入的高级用法不走
generate.sh，要查references/api-docs.md里的完整 API 规格。 - 上游页面标注 API 由 ACE Music 团队确认永久免费，但该承诺来自上游自述，长期稳定性需自行评估。
结尾¶
这个 Skill 的价值在于把「生成音乐」压缩成一条命令：安装、配好 Key、调用 scripts/generate.sh，输出就是一个 MP3 文件路径。没有订阅和额度门槛，适合需要让 Agent 具备创作能力的开发者快速接入。官方地址：https://api.skillhub.cn/zcwl/ace-music ，上游仓库：https://clawhub.ai/fspecii/ace-music 。
