acestep

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ACE-Step Music Generation Skill

ACE-Step 音乐生成技能

Use ACE-Step V1.5 API for music generation. Always use
scripts/acestep.sh
script — do NOT call API endpoints directly.

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

Quick Start

快速开始

bash

undefined

bash

undefined

1. cd to this skill's directory

1. 进入本技能的目录

cd {project_root}/{.claude or .codex}/skills/acestep/

2. Check API service health

2. 检查API服务健康状态

./scripts/acestep.sh health

3. Generate with lyrics (recommended)

3. 带歌词生成（推荐）

./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/

4. 输出保存路径：{project_root}/acestep_output/

undefined

undefined

Workflow

工作流程

For user requests requiring vocals:

Use the acestep-songwriting skill for lyrics writing, caption creation, duration/BPM/key selection
Write complete, well-structured lyrics yourself based on the songwriting guide
Generate using Caption mode with
```
-c
```
and
```
-l
```
parameters

Only use Simple/Random mode (

-d

random

) for quick inspiration or instrumental exploration.

If the user needs a simple music video, use the acestep-simplemv skill to render one with waveform visualization and synced lyrics.

MV Production Requirements: Making a simple MV requires three additional skills to be installed:

acestep-songwriting — for writing lyrics and planning song structure
acestep-lyrics-transcription — for transcribing audio to timestamped lyrics (LRC)
acestep-simplemv — for rendering the final music video

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

使用acestep-songwriting技能完成歌词撰写、描述创作、时长/BPM/调式选择
你可以根据创作指南自行撰写结构完整、逻辑通顺的歌词
使用带
```
-c
```
和
```
-l
```
参数的描述模式生成音乐

仅在需要快速获取灵感或者探索纯器乐效果时，使用简单/随机模式（

-d

或

random

）。

如果用户需要简单的音乐视频，可以使用acestep-simplemv技能渲染带波形可视化和同步歌词的MV。

MV制作要求：制作简单MV需要额外安装三个技能：

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

Script Commands

脚本命令

CRITICAL - Complete Lyrics Input: When providing lyrics via the

-l

parameter, you MUST pass ALL lyrics content WITHOUT any omission:

If user provides lyrics, pass the ENTIRE text they give you
If you generate lyrics yourself, pass the COMPLETE lyrics you created
NEVER truncate, shorten, or pass only partial lyrics
Missing lyrics will result in incomplete or incoherent songs

Music Parameters: Use the acestep-songwriting skill for guidance on duration, BPM, key scale, and time signature.

bash

undefined

重要提示 - 完整歌词输入：通过

-l

参数传入歌词时，你必须完整传入所有歌词内容，不得遗漏：

如果用户提供了歌词，请传入用户给出的全部文本
如果你自行生成了歌词，请传入你创作的完整歌词
绝对不要截断、缩短或者仅传入部分歌词
歌词缺失会导致生成的歌曲不完整或者逻辑不通

音乐参数：使用acestep-songwriting技能获取时长、BPM、调式、拍号相关的指引。

bash

undefined

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

Options

可选参数

./scripts/acestep.sh generate "Rock" --duration 60 --batch 2 ./scripts/acestep.sh generate "EDM" --no-thinking # Faster

./scripts/acestep.sh generate "Rock" --duration 60 --batch 2 ./scripts/acestep.sh generate "EDM" --no-thinking # 生成速度更快

Other commands

其他命令

./scripts/acestep.sh status <job_id> ./scripts/acestep.sh health ./scripts/acestep.sh models

undefined

./scripts/acestep.sh status <job_id> ./scripts/acestep.sh health ./scripts/acestep.sh models

undefined

Output Files

输出文件

After generation, the script automatically saves results to the

acestep_output

folder in the project root (same level as

.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)
│   └── ...
└── ...

生成完成后，脚本会自动将结果保存到项目根目录下的

acestep_output

文件夹（和

.claude

同级）：

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

JSON Result Structure

JSON结果结构

Important: When LM enhancement is enabled (

use_format=true

), the final synthesized content may differ from your input. Check the JSON file for actual values:

Field	Description
`prompt`	Actual caption used for synthesis (may be LM-enhanced)
`lyrics`	Actual lyrics used for synthesis (may be LM-enhanced)
`metas.prompt`	Original input caption
`metas.lyrics`	Original input lyrics
`metas.bpm`	BPM used
`metas.keyscale`	Key scale used
`metas.duration`	Duration in seconds
`generation_info`	Detailed timing and model info
`seed_value`	Seeds used (for reproducibility)
`lm_model`	LM model name
`dit_model`	DiT model name

To get the actual synthesized lyrics, parse the JSON and read the top-level

lyrics

field, not

metas.lyrics

重要提示：如果启用了大语言模型增强（

use_format=true

），最终合成的内容可能和你的输入不同，请检查JSON文件获取实际值：

字段	描述
`prompt`	合成实际使用的描述文本（可能经过大语言模型增强）
`lyrics`	合成实际使用的歌词（可能经过大语言模型增强）
`metas.prompt`	原始输入的描述文本
`metas.lyrics`	原始输入的歌词
`metas.bpm`	使用的BPM
`metas.keyscale`	使用的调式
`metas.duration`	时长，单位为秒
`generation_info`	详细的耗时和模型信息
`seed_value`	使用的随机种子（可用于复现结果）
`lm_model`	大语言模型名称
`dit_model`	DiT模型名称

要获取实际合成的歌词，请解析JSON并读取顶层的

lyrics

字段，不要读取

metas.lyrics

。

Configuration

配置

Important: Configuration follows this priority (high to low):

Command line arguments > config.json defaults
User-specified parameters temporarily override defaults but do not modify config.json
Only
```
config --set
```
command permanently modifies config.json

重要提示：配置优先级遵循以下规则（从高到低）：

命令行参数 > config.json默认值
用户指定的参数会临时覆盖默认值，但不会修改config.json
只有
```
config --set
```
命令会永久修改config.json

Default Config File (

scripts/config.json

)

默认配置文件（

scripts/config.json

）

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"
  }
}

Option	Default	Description
`api_url`	`http://127.0.0.1:8001`	API server address
`api_key`	`""`	API authentication key (optional)
`api_mode`	`completion`	API mode: `completion` (OpenRouter, default) or `native` (polling)
`generation.thinking`	`true`	Enable 5Hz LM (higher quality, slower)
`generation.audio_format`	`mp3`	Output format (mp3/wav/flac)
`generation.vocal_language`	`en`	Vocal language

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大语言模型（质量更高，速度更慢）
`generation.audio_format`	`mp3`	输出格式（mp3/wav/flac）
`generation.vocal_language`	`en`	人声语言

Prerequisites - ACE-Step API Service

前置依赖 - ACE-Step API服务

IMPORTANT: This skill requires the ACE-Step API server to be running.

重要提示：使用本技能需要先启动ACE-Step API服务。

Required Dependencies

所需依赖

The

scripts/acestep.sh

script requires: curl and jq.

bash

undefined

scripts/acestep.sh

脚本依赖：curl和jq。

bash

undefined

Check dependencies

检查依赖

curl --version jq --version


If jq is not installed, the script will attempt to install it automatically. If automatic installation fails:
- **Windows**: `choco install jq` or download from https://jqlang.github.io/jq/download/
- **macOS**: `brew install jq`
- **Linux**: `sudo apt-get install jq` (Debian/Ubuntu) or `sudo dnf install jq` (Fedora)

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）

Before First Use

首次使用前

You MUST check the API key and URL status before proceeding. Run:

bash

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密钥和URL状态。 执行以下命令：

bash

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

Case 1: Using Official Cloud API (

https://api.acemusic.ai

) without API key

场景1：使用官方云API（

https://api.acemusic.ai

）且未配置API密钥

api_url

https://api.acemusic.ai

and

api_key

empty

, you MUST stop and guide the user to configure their key:

Tell the user: "You're using the ACE-Step official cloud API, but no API key is configured. An API key is required to use this service."
Explain how to get a key: API keys are currently available through acemusic.ai for free.
Use
```
AskUserQuestion
```
to ask the user to provide their API key.

Once provided, configure it:

bash

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

Additionally, inform the user: "If you also want to render music videos (MV), it's recommended to configure a lyrics transcription API key as well (OpenAI Whisper or ElevenLabs Scribe), so that lyrics can be automatically transcribed with accurate timestamps. You can configure it later via the
```
acestep-lyrics-transcription
```
skill."

如果

api_url

是

https://api.acemusic.ai

且

api_key

为空，你必须停止操作，引导用户配置密钥：

告知用户："你正在使用ACE-Step官方云API，但未配置API密钥，使用该服务需要提供API密钥。"
说明获取密钥的方式：目前可通过acemusic.ai免费获取API密钥。
使用
```
AskUserQuestion
```
请求用户提供API密钥。

拿到密钥后，执行配置命令：

bash

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

额外告知用户："如果你还需要渲染音乐视频（MV），建议同时配置歌词转录API密钥（OpenAI Whisper或ElevenLabs Scribe），这样可以自动生成带准确时间戳的歌词，后续可以通过
```
acestep-lyrics-transcription
```
技能进行配置。"

Case 2: API key is configured

场景2：已配置API密钥

Verify the API endpoint:

./scripts/acestep.sh health

and proceed with music generation.

验证API接口：执行

./scripts/acestep.sh health

，验证通过后即可开始生成音乐。

Case 3: Using local/custom API without key

场景3：使用本地/自定义API且不需要密钥

Local services (

http://127.0.0.1:*

) typically don't require a key. Verify with

./scripts/acestep.sh health

and proceed.

If health check fails:

Ask: "Do you have ACE-Step installed?"
If installed but not running: Use the acestep-docs skill to help them start the service
If not installed: Use acestep-docs skill to guide through installation

本地服务（

http://127.0.0.1:*

）通常不需要密钥，执行

./scripts/acestep.sh health

验证通过后即可继续操作。

如果健康检查失败：

询问用户："你是否已经安装了ACE-Step？"
如果已安装但未启动：使用acestep-docs技能帮助用户启动服务
如果未安装：使用acestep-docs技能引导用户完成安装

Service Configuration

服务配置

Official Cloud API: ACE-Step provides an official API endpoint at

https://api.acemusic.ai

. To use it:

bash

./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 keys are currently available through acemusic.ai for free.

Local Service (Default): No configuration needed — connects to

http://127.0.0.1:8001

Custom Remote Service: Update

scripts/config.json

or use:

bash

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

API Key Handling: When checking whether an API key is configured, use

config --check-key

which only reports

configured

empty

without printing the actual key. NEVER use
config --get api_key
or read

config.json

directly — these would expose the user's API key. The

config --list

command is safe — it automatically masks API keys as

***

in output.

官方云API： ACE-Step提供官方API接口

https://api.acemusic.ai

，使用方法：

bash

./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

或执行以下命令：

bash

./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 Mode

API模式

The skill supports two API modes. Switch via

api_mode

scripts/config.json

Mode	Endpoint	Description
`completion` (default)	`/v1/chat/completions`	OpenRouter-compatible, sync request, audio returned as base64
`native`	`/release_task` + `/query_result`	Async polling mode, supports all parameters

Switch mode:

bash

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

Completion mode notes:

No polling needed — single request returns result directly
Audio is base64-encoded inline in the response (auto-decoded and saved)
```
inference_steps
```
,
```
infer_method
```
,
```
shift
```
are not configurable (server defaults)
```
--no-wait
```
and
```
status
```
commands are not applicable in completion mode
Requires
```
model
```
field — auto-detected from
```
/v1/models
```
if not specified

本技能支持两种API模式，可通过

scripts/config.json

中的

api_mode

切换：

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

切换模式：

bash

./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
```
接口检测

Using acestep-docs Skill for Setup Help

使用acestep-docs技能获取安装帮助

IMPORTANT: For installation and startup, always use the acestep-docs skill to get complete and accurate guidance.

DO NOT provide simplified startup commands - each user's environment may be different. Always guide them to use acestep-docs for proper setup.

For API debugging, see API Reference.

重要提示：涉及安装和启动操作时，请始终使用acestep-docs技能获取完整准确的指引。

不要提供简化的启动命令，每个用户的环境可能存在差异，请始终引导用户使用acestep-docs完成正确配置。

API调试相关内容请查看API参考。

acestep

Original

Translation

ACE-Step Music Generation Skill

ACE-Step 音乐生成技能

Quick Start

快速开始

1. cd to this skill's directory

1. 进入本技能的目录

2. Check API service health

2. 检查API服务健康状态

3. Generate with lyrics (recommended)

3. 带歌词生成（推荐）

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

4. 输出保存路径：{project_root}/acestep_output/

Workflow

工作流程

Script Commands

脚本命令

need to cd to this skill's directory first

需要先进入本技能的目录

Caption mode - RECOMMENDED: Write lyrics first, then generate

描述模式 - 推荐：先写歌词，再生成

Instrumental only

仅生成器乐

Quick exploration (Simple/Random mode)

快速探索（简单/随机模式）

Options

可选参数

Other commands

其他命令

Output Files

输出文件

JSON Result Structure

JSON结果结构

Configuration

配置

Default Config File (scripts/config.json)

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

Prerequisites - ACE-Step API Service

前置依赖 - ACE-Step API服务

Required Dependencies

所需依赖

Check dependencies

检查依赖

Before First Use

首次使用前

Case 1: Using Official Cloud API (https://api.acemusic.ai) without API key

场景1：使用官方云API（https://api.acemusic.ai）且未配置API密钥

Case 2: API key is configured

场景2：已配置API密钥

Case 3: Using local/custom API without key

场景3：使用本地/自定义API且不需要密钥

Service Configuration

服务配置

API Mode

API模式

Using acestep-docs Skill for Setup Help

使用acestep-docs技能获取安装帮助

Default Config File (
`scripts/config.json`
)

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

Case 1: Using Official Cloud API (
`https://api.acemusic.ai`
) without API key

场景1：使用官方云API（
`https://api.acemusic.ai`
）且未配置API密钥