ACE-Step Music Generation Skill

Use ACE-Step V1.5 API for music generation. Script: scripts/acestep.sh (requires curl + jq).

Prerequisites - ACE-Step API Service

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

Required Dependencies

The scripts/acestep.sh script requires the following tools:

1. curl - For making HTTP requests to the API 2. jq - For parsing JSON responses

Check Dependencies

Before using this skill, verify that the required tools are installed:

# Check curl
curl --version

# Check jq
jq --version

Installing jq

If jq is not installed, the script will attempt to install it automatically. If automatic installation fails, install manually:

Windows:

# Using Chocolatey
choco install jq

# Or download from: https://jqlang.github.io/jq/download/
# Extract jq.exe and add to PATH

macOS:

# Using Homebrew
brew install jq

# Using MacPorts
port install jq

Linux:

# Debian/Ubuntu
sudo apt-get install jq

# Fedora/RHEL/CentOS
sudo yum install jq
# or
sudo dnf install jq

# Arch Linux
sudo pacman -S jq

Verification:

jq --version
# Should output: jq-1.x

If user reports jq installation issues, guide them through manual installation for their platform.

Before First Use

Ask the user about their setup:

1. "Do you have ACE-Step API service configured and running?"

   If YES:

   • Verify the API endpoint: curl -s http://127.0.0.1:8001/health
   • If using remote service, ask for the API URL and update scripts/config.json
   • Proceed with music generation

   If NO or NOT SURE:

   • Ask: "Do you have ACE-Step installed?"

     If installed but not running:

     • Use the acestep-docs skill to help them start the service
     • Guide them through startup process

     If not installed:

     • Offer to help download and install ACE-Step
     • Ask: "Would you like to use the Windows portable package or install from source?"
     • Use acestep-docs skill to guide through installation

Service Configuration

Local Service (Default):

{
  "api_url": "http://127.0.0.1:8001",
  "api_key": ""
}

Remote Service:

{
  "api_url": "http://your-server-ip:8001",
  "api_key": "your-api-key-if-needed"
}

To configure remote service, update scripts/config.json or use:

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

Using acestep-docs Skill for Setup Help

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

When user needs help with installation or startup, invoke the acestep-docs skill:

Use the Skill tool to invoke: acestep-docs

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

Health Check

To verify if service is running:

curl http://127.0.0.1:8001/health
# Should return: {"status":"ok",...}

If health check fails, use acestep-docs skill to help user start the service properly.

---

WORKFLOW: For user requests requiring vocals, you should:

1. Consult Music Creation Guide for lyrics writing, caption creation, duration/BPM/key selection
2. Write complete, well-structured lyrics yourself based on the guide
3. Generate using Caption mode with -c and -l parameters

Only use Simple/Random mode (-d or random) for quick inspiration or instrumental exploration.

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

JSON Result Structure

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:

To get the actual synthesized lyrics, parse the JSON and read the top-level lyrics field, not metas.lyrics.

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: Refer to Music Creation Guide for how to calculate duration, choose BPM, key scale, and time signature.

# need to cd skills path
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

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

Configuration

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

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

Default Config File (scripts/config.json)

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

API Reference

All responses wrapped: {"data": <payload>, "code": 200, "error": null, "timestamp": ...}

Query Result Response

{
  "data": [{
    "task_id": "xxx",
    "status": 1,
    "result": "[{\"file\":\"/v1/audio?path=...\",\"metas\":{\"bpm\":120,\"duration\":60,\"keyscale\":\"C Major\"}}]"
  }]
}

Status codes: 0 = processing, 1 = success, 2 = failed

Request Parameters (/release_task)

Parameters can be placed in param_obj object.

Generation Modes

Core Parameters

Music Attributes

Generation Parameters

Audio Task Parameters

Example Request (Simple Mode)

{
  "sample_mode": true,
  "sample_query": "A cheerful pop song about spring",
  "thinking": true,
  "param_obj": {
    "duration": 60,
    "bpm": 120,
    "language": "en"
  },
  "batch_size": 2
}