Ace Music Free

ACE Music AI 音乐生成基础客户端（免费版）。通过 ACE Music 托管的免费 API 调用 ACE-Step 1.5 模型, 支持文本转音乐、自定义歌词、纯音乐模式三种基础能力。支持时长参数控制,音频以 base64 MP3 返回并由脚本自动解码。 API 永久免费,无需订阅。适用于个人创作者、快速音乐原型、学习试用场景。

天轰穿@thcjp

Install

openclaw skills install @thcjp/ace-music-free

ACE Music LITE

ACE Music 基础版,基于 ACE-Step 1.5 模型生成 AI 音乐。永久免费、无订阅。仅支持文本转音乐（text2music）任务。

范围外（本技能不做）: 翻唱（cover）、片段重绘（repaint）、批量生成、种子复现、BPM/调性精确控制（需升级付费版）。

依赖说明

运行环境

Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
操作系统: Windows / macOS / Linux

依赖项

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

分类: MD+EXEC（）

API Key配置方式:

bash

export API_KEY="your_api_key_here"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统。

核心能力

基础生成

使用 scripts/generate.sh 完成一站式生成:

bash

# 基础文本生成
scripts/generate.sh "upbeat pop song about summer" --duration 30 --output summer.mp3

# 自定义歌词
scripts/generate.sh "gentle acoustic ballad, female vo

**输入**: 用户提供基础生成所需的参数和指令。
**处理**: 按照skill规范执行基础生成操作。

### 参数指南（基础参数）
| 想要 | 参数 |
| --- | --- |
| 特定风格 | 在 prompt 中描述: "jazz, saxophone solo, smoky bar" |
| 自定义歌词 | `--lyrics "[Verse]...[Chorus]..."` |
| 无人声 | `--instrumental` |
| 更长歌曲 | `--duration 120`（秒） |

> **升级提示*

**处理**: 按照skill规范执行参数指南（基础参数）操作。

**输出**: 返回参数指南（基础参数）的执行结果,包含操作状态和输出数据。
### 结果验证与输出

验证处理结果的正确性,格式化输出并返回给用户。

**输入**: 用户提供结果验证与输出所需的参数和指令。

- 执行`结果验证与输出`操作，处理输入数据并返回结果
- 验证执行结果，确认输出符合预期格式
- 参考`结果验证与输出`相关配置参数进行设置

### 能力覆盖范围

本skill还覆盖以下能力场景: ACE、Music、基础版、文本转音乐生成、支持歌词定制和纯、音乐模式、音乐生成基础客户、免费版、托管的免费、API、Step、支持文本转音乐、纯音乐模式三种基、础能力、支持时长参数控制、音频以、base、返回并由脚本自动、永久免费、无需订阅、适用于个人创作者、快速音乐原型、学习试用场景。这些能力在上述核心功能中均有对应处理逻辑。
## 认证

使用 `ACE_MUSIC_API_KEY` 环境变量。永不打印或暴露 Key。

```bash
[ -n "${ACE_MUSIC_API_KEY:-}" ] && echo ok || echo missing

若 Key 缺失,引导用户:

浏览器打开 https://acemusic.ai/playground/api-key
注册（免费）并创建 API Key
终端环境变量: export ACE_MUSIC_API_KEY="你的Key"
配置完成后重新发起生成请求

安全红线: 永不接受/回显/存储来自聊天输入的 Key;Key 仅作认证头使用。

基础生成

使用 scripts/generate.sh 完成一站式生成:

bash

# 基础文本生成
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

脚本将生成的文件路径输出到 stdout,Agent 应将文件发送给用户。

参数指南（基础参数）

想要	参数
特定风格	在 prompt 中描述: "jazz, saxophone solo, smoky bar"
自定义歌词	`--lyrics "[Verse]...[Chorus]..."`
无人声	`--instrumental`
更长歌曲	`--duration 120`（秒）

升级提示: BPM/调性/语言/种子/批量生成、cover 翻唱、repaint 片段重绘等高级能力仅在 ace-music 付费版中提供。

适用场景

场景	典型输入	输出内容
基础文本生成	"生成一首关于夏天的流行歌"	MP3 文件
带歌词人声生成	"生成民谣,带歌词"	带人声 MP3 文件
纯音乐节拍	"做一段 lo-fi 节拍"	无人声 MP3 文件

不适用于: 翻唱已有歌曲、修改已有音频、批量生成、精确 BPM/调性控制（需升级付费版）

使用流程

Step 1: 校验 API Key

bash

[ -n "${ACE_MUSIC_API_KEY:-}" ] && echo ok || echo missing

Step 2: 缺失时引导配置

需要先配置 ACE Music API Key:

访问 https://acemusic.ai/playground/api-key

注册（免费）并创建 API Key

终端环境变量: export ACE_MUSIC_API_KEY="你的Key"

配置完成后重新发起生成请求

Step 3: 构造参数并执行

prompt 必填,描述风格/情绪/乐器
lyrics 可选,推荐使用 [Verse]/[Chorus] 标签模式
duration 不填则由 AI 决定

Step 4: 解码与落盘

脚本自动完成 base64 解码与 MP3 落盘
将文件路径回传给用户

命令参数说明

--output: 命令参数,用于指定操作选项

案例展示

案例1: 基础文本生成

场景: 用户需要快速生成一段 30 秒的夏日主题流行歌

bash

scripts/generate.sh "upbeat pop song about summer, sunny beach, upbeat tempo" \
  --duration 30 --output summer.mp3

输出: summer.mp3 文件路径

说明: 通过 prompt 描述风格与情绪,--duration 30 控制时长。适合快速原型与试听。

案例2: 带歌词的人声生成

场景: 创作者需要生成一首带歌词的民谣

bash

scripts/generate.sh "gentle acoustic ballad, female vocal, fingerstyle guitar" \
  --lyrics "[Verse 1]\nSunlight through the window\nCoffee getting cold\n\n[Chorus]\nWe are the dreamers\nChasing after light" \
  --duration 60 --output ballad.mp3

输出: ballad.mp3 文件路径

说明: --lyrics 使用 [Verse]/[Chorus] 标签模式确保段落结构清晰。AI 会根据歌词内容自动匹配旋律与人声。

错误处理

错误场景	错误信息	原因分析	处理方式
missing_api_key	`ACE_MUSIC_API_KEY missing`	环境变量未设置	不调 API,引导用户访问 acemusic.ai 注册并配置 Key
401 unauthorized	`{"error":"invalid_api_key"}`	Key 格式错误或已失效	不执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令,引导用户重新生成 Key
429 rate_limited	`{"error":"rate_limited"}`	短时间内请求过多	等待 2 秒后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令,最多 3 次
400 invalid_duration	`{"error":"duration_out_of_range"}`	duration 超出支持范围	不执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令,提示用户调整时长（5-300 秒）
400 invalid_lyrics	`{"error":"lyrics_format_error"}`	lyrics 含非法字符或格式错误	不执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令,引导用户使用 `[Verse]`/`[Chorus]` 标签
5xx server_error	HTTP 500/502/503	ACE Music 服务端错误	等待后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令,最多 2 次

常见问题

Q1: ACE Music API 真的免费吗?

A: ACE Music 团队确认 API 永久免费,无订阅、无额度限制。基础地址 https://api.acemusic.ai。如遇未来政策调整,以 ACE Music 官方公告为准。

Q2: 生成的歌曲时长有什么限制?

A: --duration 参数控制生成时长（秒）。不填则由 AI 根据内容自动决定。建议从 30-60 秒开始尝试。

Q3: 如何使用自定义歌词?

A: 通过 --lyrics 参数传入,推荐使用 [Verse 1]、[Chorus] 等标签,换行分隔歌词行。标签模式能让 AI 更准确理解歌曲结构。

Q4: 免费版和付费版有什么区别?

A: 免费版（LITE）支持文本转音乐、自定义歌词、纯音乐三种基础能力。付费版（ace-music）额外提供:

翻唱（cover）与片段重绘（repaint）任务
批量生成（--batch）与种子复现（--seed）
BPM/调性/语言精确控制（--bpm/--key/--language）
采样模式（--sample-mode,AI 自动生成歌词）
3 个完整案例（vs 免费版 2 个基础案例）
9 种错误处理（vs 免费版 6 种）

已知限制

基础任务: 仅支持 text2music,不支持 cover/repaint（需升级付费版）
基础参数: 仅支持 duration/lyrics/instrumental,不支持 bpm/key/language/seed/batch
需 API Key: 必须配置 ACE_MUSIC_API_KEY
API 基础地址固定: https://api.acemusic.ai,不支持自建部署
生成质量取决于 prompt 描述: 风格描述越具体,结果越符合预期

想要翻唱、批量生成、精确 BPM 控制? 升级到 ace-music 付费版解锁全部高级能力。