ACE-Step Music Generation Skill

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

Quick Start

CODEBLOCK0

Workflow

For user requests requiring vocals:

1. 1. Use the acestep-songwriting skill for lyrics writing, caption creation, duration/BPM/key selection
2. Write complete, well-structured lyrics yourself based on the songwriting 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.

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

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.

CODEBLOCK1

Output Files

After generation, the script automatically saves results to the acestep_output folder in the project root (same level as .claude):

CODEBLOCK2

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.

Configuration

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

1. 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)

CODEBLOCK3

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: curl and jq.

CODEBLOCK4

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: INLINECODE40
• Linux: sudo apt-get install jq (Debian/Ubuntu) or sudo dnf install jq (Fedora)

Before First Use

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

CODEBLOCK5

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

If api_url is https://api.acemusic.ai and api_key is empty, you MUST stop and guide the user to configure their key:

1. 1. 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."
2. Explain how to get a key: API keys are currently available through acemusic.ai for free.
3. Use AskUserQuestion to ask the user to provide their API key.
4. Once provided, configure it:

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

1. 5. 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."

Case 2: API key is configured

Verify the API endpoint: ./scripts/acestep.sh health and proceed with music generation.

Case 3: Using local/custom API without key

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

Service Configuration

Official Cloud API: ACE-Step provides an official API endpoint at https://api.acemusic.ai. To use it:

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

Local Service (Default): No configuration needed — connects to http://127.0.0.1:8001.

Custom Remote Service: Update scripts/config.json or use:
CODEBLOCK8

API Key Handling: When checking whether an API key is configured, use config --check-key which only reports configured or 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 Mode

The skill supports two API modes. Switch via api_mode in scripts/config.json:

Switch mode:
CODEBLOCK9

Completion mode notes:

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

Using acestep-docs Skill for Setup Help

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.