ACE-Step Music Generation — AI Integration

Use ACE-Step V1.5 REST API for AI-driven music generation. This document provides instructions for any AI assistant, agent framework, or orchestrator that can make HTTP calls.

Prerequisites

• •ACE-Step Docker container running in API mode (ACESTEP_MODE=api in .env)
• •API available at http://localhost:8501
• •Tools: curl and jq (for shell-based workflows)

Health Check

curl -s http://localhost:8501/health
# Should return: {"data":{"status":"ok","service":"ACE-Step API","version":"1.0"},...}

If health check fails, the container may be in gradio mode or not running. Check with docker compose ps and verify ACESTEP_MODE=api in .env.

Workflow

For user requests involving music generation, follow this workflow:

1. •Understand the request — What genre, mood, language, vocal style does the user want?
2. •Consult the Music Creation Guide — Use it to write captions, lyrics, and choose parameters
3. •Write a detailed caption — Style, instruments, emotion, vocal characteristics, production quality
4. •Write complete lyrics with structure tags — [Verse], [Chorus], [Bridge], etc.
5. •Calculate parameters — Duration (based on lyrics length), BPM (based on genre), key, time signature
6. •Submit the task via POST /release_task
7. •Poll for results via POST /query_result until status is 1 (success) or 2 (failed)
8. •Download audio via the URL in the result

Generation Modes

Always prefer Caption mode for the best results. Write the lyrics yourself rather than letting the LM generate them.

API Endpoints

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

Quick Example: Full Generation Flow

# 1. Submit task
TASK_ID=$(curl -s -X POST http://localhost:8501/release_task \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "Symphonic black metal, epic orchestral arrangements, blast beats, tremolo picking, aggressive male vocals, dark atmosphere",
    "lyrics": "[Intro - orchestral]\n\n[Verse 1 - aggressive]\nThrough frozen wastelands we march\nBeneath the blackened sky\nThe ancient ones await\nAs mortals fade and die\n\n[Chorus - powerful]\nWE ARE THE STORM\nWE ARE THE NIGHT\nRISING FROM DARKNESS\nINTO ETERNAL LIGHT\n\n[Outro - fade out]",
    "thinking": true,
    "param_obj": {
      "duration": 120,
      "bpm": 160,
      "key_scale": "D Minor",
      "time_signature": "4",
      "language": "en"
    }
  }' | jq -r '.data.task_id')

echo "Task: $TASK_ID"

# 2. Poll for result (repeat until status != 0)
curl -s -X POST http://localhost:8501/query_result \
  -H 'Content-Type: application/json' \
  -d "{\"task_id_list\": [\"$TASK_ID\"]}" | jq .

# 3. Download audio (use the file URL from the result)
# curl -o output.mp3 "http://localhost:8501/v1/audio?path=<path-from-result>"

Request Parameters (/release_task)

Core Parameters

Music Attributes (in param_obj or top-level)

Generation Control

Audio Task Parameters

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

Important: The result field is a JSON string that must be parsed. It contains an array of result objects, each with a file field containing the download URL.

Tips for AI Assistants

1. •Always use thinking: true — This enables the 5Hz LM for much better quality
2. •Write lyrics yourself — Don't rely on sample_mode for serious requests. Write complete, well-structured lyrics with proper structure tags
3. •Be generous with duration — Too short is worse than too long. Calculate based on lyrics length (3-5 sec per line + intro/outro)
4. •Match caption and lyrics — Instruments mentioned in caption should appear as tags in lyrics. Don't contradict yourself
5. •Use uppercase for intensity — WE ARE THE CHAMPIONS generates louder, more powerful vocals than we are the champions
6. •Poll patiently — Generation can take 30 seconds to several minutes depending on duration and model settings. Poll every 5-10 seconds
7. •Check actual output — When thinking: true, the LM may enhance your caption/lyrics. Check the result JSON for what was actually used

For detailed guidance on writing captions, lyrics, and choosing parameters, see music-creation-guide.md. For the complete API reference with all parameters and examples, see API.md.