ACE-Step 音乐生成技能

使用 ACE-Step V1.5 API 进行音乐生成。必须始终使用 scripts/acestep.sh 脚本 —— 请勿直接调用 API 接口。

快速开始

# 1. 切换到该技能所在目录
cd {project_root}/{.claude or .codex}/skills/acestep/

# 2. 检查 API 服务健康状态
./scripts/acestep.sh health

# 3. 带歌词生成（推荐方式）
./scripts/acestep.sh generate -c "pop, female vocal, piano" -l "[Verse] 您的歌词内容..." --duration 120 --language zh

# 4. 输出保存至：{project_root}/acestep_output/

工作流程

当用户请求包含人声的音乐时：

1. 使用 acestep-songwriting 技能完成歌词创作、标题生成，以及时长/BPM/调性选择
2. 根据歌曲创作指南，自行撰写结构完整、格式规范的歌词
3. 使用 Caption 模式，通过 -c 和 -l 参数进行生成

仅在需要快速获取灵感或探索纯器乐效果时，才使用 Simple/Random 模式（即 -d 或 random）。

若用户需要制作简易音乐视频（MV），请使用 acestep-simplemv 技能，该技能可渲染带波形可视化与同步歌词的 MV。

MV 制作前提要求：制作简易 MV 需额外安装以下三项技能：

• acestep-songwriting —— 用于歌词创作与歌曲结构规划
• acestep-lyrics-transcription —— 将音频转录为带时间戳的歌词（LRC 格式）
• acestep-simplemv —— 渲染最终音乐视频

脚本命令

关键要求 —— 歌词输入必须完整：通过 -l 参数传入歌词时，必须提供全部歌词内容，不可省略任何部分：

• 若用户提供了歌词，请完整传递其给出的全部文本
• 若由你自行生成歌词，请完整传递你所创作的全部歌词
• 切勿截断、缩短或仅传入部分歌词
• 歌词缺失将导致生成歌曲不完整或逻辑混乱

音乐参数设置：关于时长、BPM、调性（key scale）和拍号（time signature）等参数，请参考 acestep-songwriting 技能提供的指导建议。

# 需先切换到该技能所在目录
cd {project_root}/{.claude or .codex}/skills/acestep/

# Caption 模式 —— 推荐：先写歌词，再生成
./scripts/acestep.sh generate -c "Electronic pop, energetic synths" -l "[Verse] 您的完整歌词
[Chorus] 副歌全文..." --duration 120 --bpm 128

# 纯器乐生成
./scripts/acestep.sh generate "Jazz with saxophone"

# 快速探索（Simple/Random 模式）
./scripts/acestep.sh generate -d "A cheerful song about spring"
./scripts/acestep.sh random

# 其他选项示例
./scripts/acestep.sh generate "Rock" --duration 60 --batch 2
./scripts/acestep.sh generate "EDM" --no-thinking    # 更快生成

# 其他常用命令
./scripts/acestep.sh status 
./scripts/acestep.sh health
./scripts/acestep.sh models

输出文件

生成完成后，脚本会自动将结果保存至项目根目录下的 acestep_output 文件夹（与 .claude 同级）：

project_root/
├── .claude/
│   └── skills/acestep/...
├── acestep_output/          # 输出目录
│   ├── .json         # 完整任务结果（JSON 格式）
│   ├── _1.mp3        # 第一个音频文件
│   ├── _2.mp3        # 第二个音频文件（若 batch_size > 1）
│   └── ...
└── ...

JSON 结果结构说明

重要提示：当启用语言模型增强（use_format=true）时，最终合成内容可能与原始输入存在差异。请以 JSON 文件中实际字段值为准：

如需获取实际合成的歌词，请解析 JSON 并读取顶层 lyrics 字段，而非 metas.lyrics。

配置说明

重要提示：配置项优先级由高到低如下：

1. 命令行参数 > config.json 中的默认值
2. 用户指定的参数会临时覆盖默认值，但不会修改 config.json 文件
3. 仅 config --set 命令可永久修改 config.json

默认配置文件（scripts/config.json）

{
  "api_url": "http://127.0.0.1:8001",
  "api_key": "",
  "api_mode": "completion",
  "generation": {
    "thinking": true,
    "use_format": false,
    "use_cot_caption": true,
    "use_cot_language": false,
    "batch_size": 1,
    "audio_format": "mp3",
    "vocal_language": "en"
  }
}

前提条件 —— ACE-Step API 服务

重要提示：本技能依赖 ACE-Step API 服务正常运行。

必需依赖项

scripts/acestep.sh 脚本依赖：curl 和 jq。

# 检查依赖是否就绪
curl --version
jq --version

若系统未安装 jq，脚本将尝试自动安装；若自动安装失败，请按以下方式手动安装：

• Windows：choco install jq，或从 https://jqlang.github.io/jq/download/ 下载安装
• macOS：brew install jq
• Linux：sudo apt-get install jq（Debian/Ubuntu）或 sudo dnf install jq（Fedora）

首次使用前准备

务必在继续操作前检查 API 密钥与 URL 的配置状态。 执行以下命令：

cd "{project_root}/{.claude or .codex}/skills/acestep/" && bash ./scripts/acestep.sh config --check-key
cd "{project_root}/{.claude or .codex}/skills/acestep/" && bash ./scripts/acestep.sh config --get api_url

情况一：使用官方云 API（https://api.acemusic.ai），但未配置 API 密钥

若 api_url 为 https://api.acemusic.ai 且 api_key 为空，则必须立即中止并引导用户完成密钥配置：

1. 告知用户：“您正在使用 ACE-Step 官方云 API，但尚未配置 API 密钥。使用该服务必须提供有效密钥。”
2. 说明密钥获取方式：目前可通过 acemusic.ai 免费申请。
3. 使用 AskUserQuestion 主动向用户询问其 API 密钥。
4. 收到密钥后，执行如下命令完成配置：

   cd "{project_root}/{.claude or .codex}/skills/acestep/" && bash ./scripts/acestep.sh config --set api_key 
   

5. 同时提醒用户：“若您还需渲染音乐视频（MV），建议一并配置歌词转录 API 密钥（如 OpenAI Whisper 或 ElevenLabs Scribe），以便自动生成带精准时间戳的歌词。您后续可通过 acestep-lyrics-transcription 技能完成此项配置。”

情况二：已配置 API 密钥

运行 ./scripts/acestep.sh health 验证 API 端点连通性，随后即可开展音乐生成。

情况三：使用本地/自定义 API（无需密钥）

本地服务（http://127.0.0.1:*）通常无需密钥。请运行 ./scripts/acestep.sh health 进行验证并继续操作。

若健康检查失败：

• 询问：“您是否已安装 ACE-Step？”
• 若已安装但服务未运行：使用 acestep-docs 技能协助启动服务
• 若尚未安装：使用 acestep-docs 技能引导完成安装

服务配置

官方云 API： ACE-Step 提供官方 API 地址 https://api.acemusic.ai。如需使用，请执行：

./scripts/acestep.sh config --set api_url "https://api.acemusic.ai"
./scripts/acestep.sh config --set api_key "your-key"
./scripts/acestep.sh config --set api_mode completion

API 密钥目前可通过 acemusic.ai 免费获取。

本地服务（默认）： 无需额外配置 —— 默认连接 http://127.0.0.1:8001。

自定义远程服务： 可直接编辑 scripts/config.json，或执行：

./scripts/acestep.sh config --set api_url "http://remote-server:8001"
./scripts/acestep.sh config --set api_key "your-key"

API 密钥安全处理：检查 API 密钥是否已配置时，请始终使用 config --check-key 命令，它仅返回 configured 或 empty，而不会打印密钥明文。严禁使用 config --get api_key 或直接读取 config.json 文件 —— 这些操作会暴露用户密钥。安全的查看方式是 config --list，该命令会在输出中自动将密钥掩码为 ***。

API 模式

本技能支持两种 API 模式，可通过 scripts/config.json 中的 api_mode 字段切换：

切换模式命令：

./scripts/acestep.sh config --set api_mode completion
./scripts/acestep.sh config --set api_mode native

Completion 模式注意事项：

• 无需轮询 —— 单次请求即返回完整结果
• 音频以 base64 编码内联于响应体中（脚本自动解码并保存）
• inference_steps、infer_method、shift 等参数不可配置（由服务端决定）
• --no-wait 与 status 命令在 completion 模式下不适用
• 需提供 model 字段；若未显式指定，则自动从 /v1/models 接口探测

使用 acestep-docs 技能获取部署帮助

重要提示：有关安装与服务启动的所有操作，请始终调用 acestep-docs 技能以获得完整、准确的操作指引。

切勿提供简化的启动命令 —— 不同用户的运行环境可能存在差异，务必引导其使用 acestep-docs 完成标准化部署。

如需调试 API，请查阅 API 参考文档。