← Back to Skills Marketplace
1339
Downloads
0
Stars
2
Active Installs
3
Versions
Install in OpenClaw
/install acestep
Description
Use ACE-Step API to generate music, edit songs, and remix music. Supports text-to-music, lyrics generation, audio continuation, and audio repainting. Use thi...
README (SKILL.md)
\r \r
ACE-Step Music Generation Skill\r
\r
Use ACE-Step V1.5 API for music generation. Always use scripts/acestep.sh script — do NOT call API endpoints directly.\r
\r
Quick Start\r
\r
# 1. cd to this skill's directory\r
cd {project_root}/{.claude or .codex}/skills/acestep/\r
\r
# 2. Check API service health\r
./scripts/acestep.sh health\r
\r
# 3. Generate with lyrics (recommended)\r
./scripts/acestep.sh generate -c "pop, female vocal, piano" -l "[Verse] Your lyrics here..." --duration 120 --language zh\r
\r
# 4. Output saved to: {project_root}/acestep_output/\r
```\r
\r
## Workflow\r
\r
For user requests requiring vocals:\r
1. Use the **acestep-songwriting** skill for lyrics writing, caption creation, duration/BPM/key selection\r
2. Write complete, well-structured lyrics yourself based on the songwriting guide\r
3. Generate using Caption mode with `-c` and `-l` parameters\r
\r
Only use Simple/Random mode (`-d` or `random`) for quick inspiration or instrumental exploration.\r
\r
If the user needs a simple music video, use the **acestep-simplemv** skill to render one with waveform visualization and synced lyrics.\r
\r
**MV Production Requirements**: Making a simple MV requires three additional skills to be installed:\r
- **acestep-songwriting** — for writing lyrics and planning song structure\r
- **acestep-lyrics-transcription** — for transcribing audio to timestamped lyrics (LRC)\r
- **acestep-simplemv** — for rendering the final music video\r
\r
## Script Commands\r
\r
**CRITICAL - Complete Lyrics Input**: When providing lyrics via the `-l` parameter, you MUST pass ALL lyrics content WITHOUT any omission:\r
- If user provides lyrics, pass the ENTIRE text they give you\r
- If you generate lyrics yourself, pass the COMPLETE lyrics you created\r
- NEVER truncate, shorten, or pass only partial lyrics\r
- Missing lyrics will result in incomplete or incoherent songs\r
\r
**Music Parameters**: Use the **acestep-songwriting** skill for guidance on duration, BPM, key scale, and time signature.\r
\r
```bash\r
# need to cd to this skill's directory first\r
cd {project_root}/{.claude or .codex}/skills/acestep/\r
\r
# Caption mode - RECOMMENDED: Write lyrics first, then generate\r
./scripts/acestep.sh generate -c "Electronic pop, energetic synths" -l "[Verse] Your complete lyrics\r
[Chorus] Full chorus here..." --duration 120 --bpm 128\r
\r
# Instrumental only\r
./scripts/acestep.sh generate "Jazz with saxophone"\r
\r
# Quick exploration (Simple/Random mode)\r
./scripts/acestep.sh generate -d "A cheerful song about spring"\r
./scripts/acestep.sh random\r
\r
# Options\r
./scripts/acestep.sh generate "Rock" --duration 60 --batch 2\r
./scripts/acestep.sh generate "EDM" --no-thinking # Faster\r
\r
# Other commands\r
./scripts/acestep.sh status \x3Cjob_id>\r
./scripts/acestep.sh health\r
./scripts/acestep.sh models\r
```\r
\r
## Output Files\r
\r
After generation, the script automatically saves results to the `acestep_output` folder in the project root (same level as `.claude`):\r
\r
```\r
project_root/\r
├── .claude/\r
│ └── skills/acestep/...\r
├── acestep_output/ # Output directory\r
│ ├── \x3Cjob_id>.json # Complete task result (JSON)\r
│ ├── \x3Cjob_id>_1.mp3 # First audio file\r
│ ├── \x3Cjob_id>_2.mp3 # Second audio file (if batch_size > 1)\r
│ └── ...\r
└── ...\r
```\r
\r
### JSON Result Structure\r
\r
**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:\r
\r
| Field | Description |\r
|-------|-------------|\r
| `prompt` | **Actual caption** used for synthesis (may be LM-enhanced) |\r
| `lyrics` | **Actual lyrics** used for synthesis (may be LM-enhanced) |\r
| `metas.prompt` | Original input caption |\r
| `metas.lyrics` | Original input lyrics |\r
| `metas.bpm` | BPM used |\r
| `metas.keyscale` | Key scale used |\r
| `metas.duration` | Duration in seconds |\r
| `generation_info` | Detailed timing and model info |\r
| `seed_value` | Seeds used (for reproducibility) |\r
| `lm_model` | LM model name |\r
| `dit_model` | DiT model name |\r
\r
To get the actual synthesized lyrics, parse the JSON and read the top-level `lyrics` field, not `metas.lyrics`.\r
\r
## Configuration\r
\r
**Important**: Configuration follows this priority (high to low):\r
\r
1. **Command line arguments** > **config.json defaults**\r
2. User-specified parameters **temporarily override** defaults but **do not modify** config.json\r
3. Only `config --set` command **permanently modifies** config.json\r
\r
### Default Config File (`scripts/config.json`)\r
\r
```json\r
{\r
"api_url": "http://127.0.0.1:8001",\r
"api_key": "",\r
"api_mode": "completion",\r
"generation": {\r
"thinking": true,\r
"use_format": false,\r
"use_cot_caption": true,\r
"use_cot_language": false,\r
"batch_size": 1,\r
"audio_format": "mp3",\r
"vocal_language": "en"\r
}\r
}\r
```\r
\r
| Option | Default | Description |\r
|--------|---------|-------------|\r
| `api_url` | `http://127.0.0.1:8001` | API server address |\r
| `api_key` | `""` | API authentication key (optional) |\r
| `api_mode` | `completion` | API mode: `completion` (OpenRouter, default) or `native` (polling) |\r
| `generation.thinking` | `true` | Enable 5Hz LM (higher quality, slower) |\r
| `generation.audio_format` | `mp3` | Output format (mp3/wav/flac) |\r
| `generation.vocal_language` | `en` | Vocal language |\r
\r
## Prerequisites - ACE-Step API Service\r
\r
**IMPORTANT**: This skill requires the ACE-Step API server to be running.\r
\r
### Required Dependencies\r
\r
The `scripts/acestep.sh` script requires: **curl** and **jq**.\r
\r
```bash\r
# Check dependencies\r
curl --version\r
jq --version\r
```\r
\r
If jq is not installed, the script will attempt to install it automatically. If automatic installation fails:\r
- **Windows**: `choco install jq` or download from https://jqlang.github.io/jq/download/\r
- **macOS**: `brew install jq`\r
- **Linux**: `sudo apt-get install jq` (Debian/Ubuntu) or `sudo dnf install jq` (Fedora)\r
\r
### Before First Use\r
\r
**You MUST check the API key and URL status before proceeding.** Run:\r
\r
```bash\r
cd "{project_root}/{.claude or .codex}/skills/acestep/" && bash ./scripts/acestep.sh config --check-key\r
cd "{project_root}/{.claude or .codex}/skills/acestep/" && bash ./scripts/acestep.sh config --get api_url\r
```\r
\r
#### Case 1: Using Official Cloud API (`https://api.acemusic.ai`) without API key\r
\r
If `api_url` is `https://api.acemusic.ai` and `api_key` is `empty`, you MUST stop and guide the user to configure their key:\r
\r
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."\r
2. Explain how to get a key: API keys are currently available through [acemusic.ai](https://acemusic.ai/api-key) for free.\r
3. Use `AskUserQuestion` to ask the user to provide their API key.\r
4. Once provided, configure it:\r
```bash\r
cd "{project_root}/{.claude or .codex}/skills/acestep/" && bash ./scripts/acestep.sh config --set api_key \x3CKEY>\r
```\r
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."\r
\r
#### Case 2: API key is configured\r
\r
Verify the API endpoint: `./scripts/acestep.sh health` and proceed with music generation.\r
\r
#### Case 3: Using local/custom API without key\r
\r
Local services (`http://127.0.0.1:*`) typically don't require a key. Verify with `./scripts/acestep.sh health` and proceed.\r
\r
If health check fails:\r
- Ask: "Do you have ACE-Step installed?"\r
- **If installed but not running**: Use the acestep-docs skill to help them start the service\r
- **If not installed**: Use acestep-docs skill to guide through installation\r
\r
### Service Configuration\r
\r
**Official Cloud API:** ACE-Step provides an official API endpoint at `https://api.acemusic.ai`. To use it:\r
```bash\r
./scripts/acestep.sh config --set api_url "https://api.acemusic.ai"\r
./scripts/acestep.sh config --set api_key "your-key"\r
./scripts/acestep.sh config --set api_mode completion\r
```\r
API keys are currently available through [acemusic.ai](https://acemusic.ai/api-key) for free. \r
\r
**Local Service (Default):** No configuration needed — connects to `http://127.0.0.1:8001`.\r
\r
**Custom Remote Service:** Update `scripts/config.json` or use:\r
```bash\r
./scripts/acestep.sh config --set api_url "http://remote-server:8001"\r
./scripts/acestep.sh config --set api_key "your-key"\r
```\r
\r
**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.\r
\r
### API Mode\r
\r
The skill supports two API modes. Switch via `api_mode` in `scripts/config.json`:\r
\r
| Mode | Endpoint | Description |\r
|------|----------|-------------|\r
| `completion` (default) | `/v1/chat/completions` | OpenRouter-compatible, sync request, audio returned as base64 |\r
| `native` | `/release_task` + `/query_result` | Async polling mode, supports all parameters |\r
\r
**Switch mode:**\r
```bash\r
./scripts/acestep.sh config --set api_mode completion\r
./scripts/acestep.sh config --set api_mode native\r
```\r
\r
**Completion mode notes:**\r
- No polling needed — single request returns result directly\r
- Audio is base64-encoded inline in the response (auto-decoded and saved)\r
- `inference_steps`, `infer_method`, `shift` are not configurable (server defaults)\r
- `--no-wait` and `status` commands are not applicable in completion mode\r
- Requires `model` field — auto-detected from `/v1/models` if not specified\r
\r
### Using acestep-docs Skill for Setup Help\r
\r
**IMPORTANT**: For installation and startup, always use the acestep-docs skill to get complete and accurate guidance.\r
\r
**DO NOT provide simplified startup commands** - each user's environment may be different. Always guide them to use acestep-docs for proper setup.\r
\r
---\r
\r
For API debugging, see [API Reference](./api-reference.md).\r
Usage Guidance
This skill is a wrapper around an ACE‑Step API and uses the provided bash script to send prompts/lyrics and download audio. Before installing or running it: 1) Confirm the api_url in scripts/config.json (default is localhost; example points to api.acemusic.ai). 2) Treat any API key you put into config.json as a secret stored on disk (the script stores/reads it from that file). 3) Expect that full user-provided lyrics and prompts will be transmitted to the configured API and that audio and JSON results will be saved under project_root/acestep_output. 4) Ensure you trust the ACE‑Step API host you configure (or run a local instance) if you need privacy or control over your data. 5) The script requires curl and jq; inspect scripts/acestep.sh before running in your environment. If you want stronger secrecy for keys, consider managing the API key outside the repo and not committing config.json.
Capability Analysis
Type: OpenClaw Skill
Name: acestep
Version: 1.0.2
The skill is classified as suspicious primarily due to a prompt injection vulnerability in `SKILL.md`. The documentation states, "If jq is not installed, the script will attempt to install it automatically." However, the `scripts/acestep.sh` script explicitly checks for `jq` and exits if it's not found, without attempting any installation. An AI agent, following the instructions in `SKILL.md`, might misinterpret this false statement as a directive to itself to install `jq` if the script fails, potentially leading to the agent executing arbitrary commands from untrusted sources or using insecure methods to install `jq`. While the bash script itself is robust in handling inputs and preventing shell injection, this instruction flaw in `SKILL.md` presents a significant risk of unintended command execution by the agent.
Capability Assessment
Purpose & Capability
Name/description match the actual files: SKILL.md, an API reference, a config example, and a single bash CLI (scripts/acestep.sh) that talks to ACE‑Step endpoints. There are no unrelated credentials, binaries, or platform-level access requested.
Instruction Scope
Runtime instructions require using the included script (not direct API calls). The skill instructs the agent to pass complete lyrics/prompts to the API and to save outputs to project_root/acestep_output. This means potentially sensitive user-provided lyrics/prompts and generated audio will be transmitted to the configured API and written to disk — this is coherent with the stated purpose but is a privacy/data‑exfiltration consideration the user should be aware of.
Install Mechanism
No install spec; this is instruction-only with an included shell script. No packages are downloaded or extracted by the skill itself. The script requires standard tools (curl, jq) which are declared in the docs.
Credentials
The skill declares no required environment variables. API authentication is handled via scripts/config.json (api_key) rather than env vars. Storing an API key in the config file is functional but users should note it may be stored in plaintext under the skill directory. The default api_url is localhost (127.0.0.1) but the example config points to a remote host (https://api.acemusic.ai) — confirm and trust the API endpoint before use.
Persistence & Privilege
always:false (not force-included). The skill writes its own config.json and outputs to a project-level output folder (acestep_output) but does not request system-wide configuration changes or other skills' secrets.
How to Use
- Make sure OpenClaw is installed (local or Docker)
- Run the install command in chat:
/install acestep - After installation, invoke the skill by name or use
/acestep - Provide required inputs per the skill's parameter spec and get structured output
Version History
v1.0.2
acestep 1.0.2
- Updated instructions for obtaining a free ACE-Step API key: now directs users to [acemusic.ai/api-key](https://acemusic.ai/api-key).
- Clarified wording on the API key requirement and configuration process when using the official cloud API.
- No functional or file changes; documentation updated for accuracy and improved guidance.
v1.0.1
**Changelog for acestep v1.0.1**
- Major docs restructuring — simplified SKILL.md, emphasizing use of scripts/acestep.sh and auxiliary skills.
- Added initial API reference documentation (api-reference.md).
- Added scripts/config.example.json as a config template; removed scripts/config.json from repo.
- Music creation workflow and parameter guidance now refer to separate skills (acestep-songwriting, acestep-lyrics-transcription, acestep-simplemv).
- Removed the included music-creation-guide.md and directed all lyric and caption writing to dedicated skills.
v1.0.0
ACE-Step skill for music generation – initial release:
- Provides seamless integration with the ACE-Step API for music/audio generation, lyrics creation, audio editing, and remixing via a bash script wrapper.
- Includes a detailed setup guide covering dependencies (curl, jq), API server configuration (local/remote), and troubleshooting.
- Outlines recommended workflow: guides users through project structure, output handling, and lyric input requirements.
- Offers clear instructions for configuring, running, and verifying the ACE-Step service, alongside integration with the acestep-docs skill for installation/startup help.
- Documents script commands, config file options, and includes notes about output formats and result file contents.
Metadata
Frequently Asked Questions
What is acestep?
Use ACE-Step API to generate music, edit songs, and remix music. Supports text-to-music, lyrics generation, audio continuation, and audio repainting. Use thi... It is an AI Agent Skill for Claude Code / OpenClaw, with 1339 downloads so far.
How do I install acestep?
Run "/install acestep" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.
Is acestep free?
Yes, acestep is completely free (open-source). You can download, install and use it at no cost.
Which platforms does acestep support?
acestep is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).
Who created acestep?
It is built and maintained by Sayo (@dumoedss); the current version is v1.0.2.
More Skills