核心功能: 本技能提供中文交互等能力。

核心功能: 本技能提供时使用、化工作流场景等能力。

ACE Music - Free Suno Alternative Generate unlimited AI music for free using ACE-Step 1.5. Full songs with vocals, lyrics, any genre, any language. No subscription, no credits, no limits. The open-source Suno alternative, powered by ACE Music's free API.

Generate music via ACE Music's free hosted API (ACE-Step 1.5 model).

Setup

API Key is stored in env ACE_MUSIC_API_KEY. If not set:

1. Open https://acemusic.ai/playground/api-key in the browser for the user
2. Ask them to sign up (free) and paste the API key
3. Store it: export ACE_MUSIC_API_KEY=<key> or add to TOOLS.md

Quick Generation

Use scripts/generate.sh for one-shot generation:

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

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

Script outputs file path(s) to stdout. Send the file to the user.

Advanced Usage (curl/direct API)

For covers, repainting, or audio input — see references/api-docs.md for full API spec.

Key task types:

• text2music (default) — generate from text/lyrics
• cover — cover an existing song (requires audio input)
• repaint — modify a section of existing audio

Parameters Guide

Notes

• API is free forever (confirmed by ACE Music team)
• Base URL: https://api.acemusic.ai
• Audio returned as base64 MP3, decoded automatically by the script
• Duration: if omitted, AI decides content
• For best results, use tagged mode (prompt + lyrics separated)

环境要求

运行环境

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

依赖说明

API Key 配置

• 本Skill基于Markdown指令,无需额外API Key(除内容中明确标注的外部API)

可用性分类

• 分类: MD+execute(纯Markdown指令,部分功能需要exec命令行执行能力)
• 说明: 基于Markdown的AI Skill,通过自然语言指令驱动Agent执行任务

主要能力

• Generate AI music using ACE-Step 1
• 5 via ACE Music's free API
• Use when the user asks to create,
• 触发关键词: full, alternative,, open-source, step, limits
• , ace-step, songs, music''s'

典型场景

不适用于：需要人工判断的复杂决策场景

使用说明

1. 确认运行环境满足依赖说明中的要求
2. 根据适用场景选择合适的使用方式
3. 执行操作并检查输出结果
4. 如遇错误，参考错误处理章节

用法示例

示例1：基础用法

# 请参考上方使用说明进行配置和调用
result = "ready"

错误应对

疑问解答

Q1: 如何开始使用Ace Music？

A: 请先阅读使用流程章节，确认环境满足依赖说明中的要求。

Q2: 遇到错误怎么办？

A: 请参考错误处理章节，按照表格中的处理方式操作。

Q3: Ace Music有什么限制？

A: 请参考已知限制章节了解具体限制。

功能边界

• 需要API Key，无Key环境无法使用

常见问题与故障排查

Q1: API请求失败，提示错误'Invalid API Key'？

错误现象: API请求无法成功，返回'Invalid API Key'错误。 原因分析: API Key配置错误或过期。 解决方案: 确认API Key已正确存储在环境变量中，并检查是否已过期，如过期请重新获取。

Q2: 生成的音乐质量不符合预期？

错误现象: 生成的音乐音质较差，不符合用户需求。 原因分析: 提供的参数不足以指导音乐生成，或参数设置不正确。 解决方案: 尝试调整参数，如增加描述细节，使用更具体的音乐风格描述等。

Q3: 生成的音乐时长不准确？

错误现象: 生成的音乐时长与预期不符。 原因分析: 输入参数中指定的时长与实际生成的音乐时长不一致。 解决方案: 重新设置时长参数，确保其符合实际需求。

Q4: 音乐文件无法播放？

错误现象: 生成的音乐文件无法播放。 原因分析: 文件格式不支持或编码问题。 解决方案: 检查音乐文件的格式是否正确，如果是MP3格式，请使用支持MP3播放的播放器。

Q5: 生成音乐的响应时间过长？

错误现象: API请求的响应时间过长。 原因分析: 网络延迟或API服务压力大。 解决方案: 确认网络连接稳定，并在服务压力低时重试请求。

完整代码示例

示例1: 生成一首描述性音乐

import requests
url = 'https://api.acemusic.ai/generate'
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
payload = {'text': 'A soothing melody for a calm evening', 'duration': 120}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

预期输出: 包含音乐文件的Base64编码和相关信息。

示例2: 生成一首带歌词的音乐

import requests
url = 'https://api.acemusic.ai/generate'
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
payload = {
    'text': '[Verse]
Sunlight through the window

[Chorus]
We are the dreamers',
    'duration': 60,
    'lyrics': 'true'
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

预期输出: 包含音乐文件的Base64编码和歌词。

示例3: 生成一首指定风格的音乐

import requests
url = 'https://api.acemusic.ai/generate'
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
payload = {
    'text': 'A reggae song with a steel drum beat',
    'duration': 90,
    'style': 'reggae'
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

预期输出: 包含音乐文件的Base64编码和指定风格的信息。

边界条件与异常处理

效率提升量化分析

手动操作 vs 自动化对比

差异化优势

ROI计算

假设每年通过本技能生成音乐100首，节省成本80%，则每年ROI为80%。

标准效率量化

安全优选实践

1. API Key保护

安全风险点: API Key泄露可能导致未授权访问。 处理建议: 对API Key进行加密存储，并通过HTTPS传输。

2. 数据安全

安全风险点: 音乐数据可能包含敏感信息。 处理建议: 对音乐数据进行加密，确保存储和传输安全。

3. 认证与授权

安全风险点: 访问控制不当。 优选实践: 使用OAuth 2.0进行认证和授权。

4. 审计日志

安全风险点: 缺乏审计日志可能导致安全事件难以追踪。 优选实践: 记录所有API调用日志，包括用户ID、请求时间、请求内容等。

5. 防止API滥用

安全风险点: API被滥用可能导致服务不可用。 优选实践: 实施API限流和监控策略。

安全提示

以下为使用ACE Music API时需要考虑的安全注意事项：

创新优势

效率提升量化分析

差异化对比

参数说明

结果格式

{
  "audio": "data:audio/mpeg;base64,//uQx+...+==",
  "lyrics": "[Verse]\nSunlight through the window\n\n[Chorus]\nWe are the dreamers",
  "style": "acoustic",
  "duration": 60,
  "bpm": 80,
  "key": "C major",
  "language": "en",
  "instrumental": false,
  "sample-mode": false,
  "batch": 1,
  "seed": 42
}

## 主要功能
- **自动化执行**: 经ACE Music免费API用ACE-Step 1.5生成AI音乐
- **文件处理**: 支持多种文件格式的读取、解析和写入操作
- **API集成**: 通过标准化接口调用外部服务并处理响应
- **命令执行**: 在安全沙箱中执行系统命令并收集结果

## 差异化对比

| 对比维度 | 音乐 | 传统手动方式 | 通用脚本工具 |
|---------|------------|-------------|------------|
| 自动化程度 | 全流程自动 | 完全手动 | 部分自动 |
| 错误处理 | 内置错误恢复 | 依赖人工经验 | 基本try-catch |
| 可复用性 | 参数化配置 | 一次性脚本 | 模板化 |
| 安全合规 | 内置安全检查 | 无安全保障 | 无安全保障 |
| 适用场景 | 经ACE Music免费API用ACE-Step 1.5生成AI音乐 | 通用场景 | 通用场景 |

## 错误恢复
针对音乐使用中可能遇到的常见问题,提供以下排查方案:

| 错误类型 | 原因分析 | 解决方案 |
|---------|---------|---------|
| API认证失败(401) | API密钥错误或过期 | 检查密钥配置,重新生成token |
| 接口限流(429) | 请求频率超出限制 | 降低调用频率,启用重试退避策略 |
| 响应超时(504) | 网络延迟或服务端负载过高 | 增加超时阈值,检查网络连接 |
| 文件不存在 | 路径错误或文件未创建 | 检查路径拼写,确认文件已生成 |
| 文件格式不支持 | 扩展名不在支持列表中 | 转换为支持的格式后重试 |
| 权限不足 | 当前用户无读写权限 | 检查文件权限,以管理员身份运行 |
| 命令执行失败 | 参数错误或环境依赖缺失 | 检查命令语法,确认依赖已安装 |
| 进程超时 | 命令执行时间过长 | 增加超时设置,优化命令参数 |
| 网络连接失败 | DNS解析失败或防火墙拦截 | 检查网络配置,确认代理设置 |

### 音乐通用排查步骤

1. **检查输入参数**: 确认所有必填参数已提供且格式正确
2. **查看日志输出**: 定位具体错误行和异常类型
3. **验证环境配置**: 确认依赖库版本和运行环境满足要求
4. **逐步调试**: 缩小问题范围,隔离故障模块

### 音乐通用排查步骤

1. **检查输入参数**: 确认所有必填参数已提供且格式正确
2. **查看日志输出**: 定位具体错误行和异常类型
3. **验证环境配置**: 确认依赖库版本和运行环境满足要求
4. **逐步调试**: 缩小问题范围,隔离故障模块