acestep

ACE-Step 音乐生成 Skill

使用 ACE-Step V1.5 API 生成音乐。始终使用 scripts/acestep.sh 脚本——不要直接调用 API 端点。

快速开始

# 1. cd to this skill's directory
cd {project_root}/{.claude or .codex}/skills/acestep/

# 2. Check API service health
./scripts/acestep.sh health

# 3. Generate with lyrics (recommended)
./scripts/acestep.sh generate -c "pop, female vocal, piano" -l "[Verse] Your lyrics here..." --duration 120 --language zh

# 4. Output saved to: {project_root}/acestep_output/

工作流

对于需要人声的用户请求：

1. 使用 acestep-songwriting Skill 编写歌词、创建描述，并选择时长、BPM 和调性
2. 根据 songwriting 指南自行编写完整、结构清晰的歌词
3. 使用 Caption 模式，通过 -c 和 -l 参数生成

只有在快速获取灵感或探索纯音乐时，才使用 Simple/Random 模式（-d 或 random）。

如果用户需要简单的音乐视频，请使用 acestep-simplemv Skill，生成带有波形可视化和同步歌词的视频。

MV 制作要求：制作简单 MV 还需要安装以下 Skill：

• acestep-songwriting——用于编写歌词和规划歌曲结构
• acestep-lyrics-transcription——用于将音频转录为带时间戳的歌词（LRC）
• acestep-simplemv——用于渲染最终音乐视频
• acestep-thumbnail（可选）——通过 Gemini API 生成封面图 / MV 背景图

MV 背景图：当用户请求制作 MV 时，询问他们是否需要视频背景图：

1. 通过 Gemini 生成——使用 acestep-thumbnail Skill（需要配置 Gemini API 密钥）
2. 提供现有图片——用户提供本地图片路径
3. 跳过——使用默认的动态渐变背景（无需图片）

在继续渲染 MV 之前，使用 AskUserQuestion 让用户选择。

并行处理：歌词转录和缩略图生成是相互独立的任务。当用户选择生成背景图时，并行运行 acestep-lyrics-transcription 和 acestep-thumbnail（例如，通过两个并发的 Agent 调用）以节省时间，然后在渲染最终 MV 时使用两者的输出。

脚本命令

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

• 如果用户提供了歌词，传入他们提供的完整文本
• 如果由你生成歌词，传入你创作的完整歌词
• 绝不要截断、缩短或只传入部分歌词
• 缺失歌词会导致歌曲不完整或不连贯

音乐参数：请使用 acestep-songwriting Skill 获取时长、BPM、调式和拍号方面的指导。

# need to cd to this skill's directory first
cd {project_root}/{.claude or .codex}/skills/acestep/

# Caption mode - RECOMMENDED: Write lyrics first, then generate
./scripts/acestep.sh generate -c "Electronic pop, energetic synths" -l "[Verse] Your complete lyrics
[Chorus] Full chorus here..." --duration 120 --bpm 128

# Instrumental only
./scripts/acestep.sh generate "Jazz with saxophone"

# Quick exploration (Simple/Random mode)
./scripts/acestep.sh generate -d "A cheerful song about spring"
./scripts/acestep.sh random

# Cover / Repainting from source audio
./scripts/acestep.sh cover song.mp3 -c "Rock cover style" -l "[Verse] Lyrics..." --duration 120 --bpm 128
./scripts/acestep.sh generate --src-audio song.mp3 --task-type repaint -c "Pop" --repaint-start 30 --repaint-end 60

# Music attribute options
./scripts/acestep.sh generate "Rock" --duration 60 --bpm 120 --key-scale "C major" --time-sig "4/4"
./scripts/acestep.sh generate "Rock" --duration 60 --batch 2
./scripts/acestep.sh generate "EDM" --no-thinking    # Faster

# Other commands
./scripts/acestep.sh status <job_id>
./scripts/acestep.sh health
./scripts/acestep.sh models

翻唱 / 音频重绘

cover 命令基于源音频文件生成音乐。音频会经过 Base64 编码后发送至 API。

# Cover: regenerate with new style/lyrics, preserving melody structure
./scripts/acestep.sh cover input.mp3 -c "Jazz cover" -l "[Verse] New lyrics..." --duration 120

# Repainting: modify a specific region of the audio
./scripts/acestep.sh generate --src-audio input.mp3 --task-type repaint -c "Pop ballad" --repaint-start 30 --repaint-end 90

# Cover options
#   --src-audio         Source audio file path
#   --task-type         cover (default with --src-audio), repaint, text2music
#   --cover-strength    0.0-1.0 (default: 1.0, higher = closer to source)
#   --repaint-start     Repainting start position (seconds)
#   --repaint-end       Repainting end position (seconds)
#   --key-scale         Musical key (e.g. "E minor")
#   --time-signature    Time signature (e.g. "4/4")

注意：使用云 API 时，较大的音频文件可能会被 Cloudflare 拒绝。需要时请在上传前压缩音频（例如使用 ffmpeg：ffmpeg -i input.mp3 -b:a 64k -ar 24000 -ac 1 compressed.mp3）。

输出文件

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

project_root/
├── .claude/
│   └── skills/acestep/...
├── acestep_output/          # Output directory
│   ├── <job_id>.json         # Complete task result (JSON)
│   ├── <job_id>_1.mp3        # First audio file
│   ├── <job_id>_2.mp3        # Second audio file (if batch_size > 1)
│   └── ...
└── ...

JSON 结果结构

重要：启用 LM 增强（use_format=true）时，最终合成内容可能与输入不同。请检查 JSON 文件以获取实际值：

字段	描述
prompt	合成时使用的实际描述（可能经过 LM 增强）
lyrics	合成时使用的实际歌词（可能经过 LM 增强）
metas.prompt	原始输入描述
metas.lyrics	原始输入歌词
metas.bpm	使用的 BPM
metas.keyscale	使用的调式
metas.duration	时长（秒）
generation_info	详细的计时和模型信息
seed_value	使用的种子值（用于复现）
lm_model	LM 模型名称
dit_model	DiT 模型名称

若要获取实际合成的歌词，请解析 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"
  }
}

选项	默认值	说明
api_url	http://127.0.0.1:8001	API 服务地址
api_key	""	API 身份验证密钥（可选）
api_mode	completion	API 模式：completion（OpenRouter，默认）或 native（轮询）
generation.thinking	true	启用 5Hz LM（质量更高，速度更慢）
generation.audio_format	mp3	输出格式（mp3/wav/flac）
generation.vocal_language	en	人声语言

前置条件 - ACE-Step API 服务

重要：此技能需要 ACE-Step API 服务正在运行。

必需依赖项

scripts/acestep.sh 脚本需要：curl 和 jq。

# Check dependencies
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

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

如果 api_url 是 https://api.acemusic.ai 且 api_key 为 empty，必须停止操作并引导用户配置密钥：

1. 告诉用户：“你正在使用 ACE-Step 官方云 API，但尚未配置 API 密钥。使用此服务需要 API 密钥。”
2. 说明如何获取密钥：目前可通过 acemusic.ai 免费获取 API 密钥。
3. 使用 AskUserQuestion 询问用户提供 API 密钥。
4. 用户提供密钥后，进行配置：

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

5. 此外，告知用户：“如果你还想制作音乐视频（MV），建议也配置歌词转录 API 密钥（OpenAI Whisper 或 ElevenLabs Scribe），以便自动转录歌词并生成准确的时间戳。之后可通过 acestep-lyrics-transcription 技能进行配置。”

情况 2：已配置 API 密钥

验证 API 端点：./scripts/acestep.sh health，然后继续生成音乐。

情况 3：使用本地/自定义 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

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

**本地服务（默认）：**无需配置——连接到 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——这些操作会暴露用户的 API 密钥。config --list 命令是安全的——它会自动在输出中将 API 密钥遮蔽为 ***。

API 模式

该技能支持两种 API 模式。通过 scripts/config.json 中的 api_mode 切换：

模式	端点	说明
completion（默认）	/v1/chat/completions	兼容 OpenRouter，同步请求，音频以 base64 格式返回
native	/release_task + /query_result	异步轮询模式，支持所有参数

切换模式：

./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 参考。