ACE Music - AI Music Generation

Generate music via ACE Music's free hosted API (ACE-Step 1.5 model).

Setup

API Key is stored in env ACE_MUSIC_API_KEY. If not set:

1. Open https://acemusic.ai/playground/api-key in the browser for the user
2. Ask them to sign up (free) and paste the API key
3. Store it: export ACE_MUSIC_API_KEY=<key> or add to TOOLS.md

Quick Generation

Use scripts/generate.sh for one-shot generation:

# Simple prompt (AI decides everything)
scripts/generate.sh "upbeat pop song about summer" --duration 30 --output summer.mp3

# With lyrics
scripts/generate.sh "gentle acoustic ballad, female vocal" \
  --lyrics "[Verse 1]\nSunlight through the window\n\n[Chorus]\nWe are the dreamers" \
  --duration 60 --output ballad.mp3

# Instrumental only
scripts/generate.sh "lo-fi hip hop beats, chill, rainy day" --instrumental --duration 120 --output lofi.mp3

# Natural language (AI writes everything)
scripts/generate.sh "write me a jazz song about coffee" --sample-mode --output jazz.mp3

# Specific settings
scripts/generate.sh "rock anthem" --bpm 140 --key "E minor" --language en --seed 42 --output rock.mp3

# Multiple variations
scripts/generate.sh "electronic dance track" --batch 3 --output edm.mp3

Script outputs file path(s) to stdout. Send the file to the user.

Advanced Usage (curl/direct API)

For covers, repainting, or audio input — see references/api-docs.md for full API spec.

Key task types:

• text2music (default) — generate from text/lyrics
• cover — cover an existing song (requires audio input)
• repaint — modify a section of existing audio

Parameters Guide

Want	Use
Specific style	Describe in prompt: "jazz, saxophone solo, smoky bar"
Custom lyrics	--lyrics "[Verse]...[Chorus]..."
AI writes everything	--sample-mode
No vocals	--instrumental
Longer songs	--duration 120 (seconds)
Specific tempo	--bpm 120
Specific key	--key "C major"
Multiple outputs	--batch 3
Reproducible	--seed 42
Non-English vocals	--language ja (zh, en, ja, ko, etc.)

Notes

• API is free forever (confirmed by ACE Music team)
• Base URL: https://api.acemusic.ai
• Audio returned as base64 MP3, decoded automatically by the script
• Duration: if omitted, AI decides based on content
• For best results, use tagged mode (prompt + lyrics separated)