ACE Music Song Generation API

ACE Music supports generating a set of song candidates from a single creative inspiration or custom lyrics. Available models are acemusic-v1.1 (default) and acemusic-v1. One complete generation includes two candidates, which can be previewed and downloaded as MP3 files separately.

Obtain Credentials

Enable ACE Music in the Console, or use general application credentials that have already been granted access to this service. Requests carry Authorization: Bearer YOUR_API_KEY. Application balance, credential quota, and service permissions will all be checked.

Inspiration Mode

curl --request POST 'https://api.acedata.cloud/acemusic/audios' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: music-draft-001' \
  --data '{
    "action": "generate",
    "model": "acemusic-v1.1",
    "custom": false,
    "prompt": "A Chinese song about hometown, in a warm folk style",
    "async": true
  }'

Custom Mode

Set custom to true, and provide title, lyric, and style. Lyrics can include section labels such as [Verse] and [Chorus], or can first be created through the Lyrics Generation API, then edited and submitted.

{
  "action": "generate",
  "model": "acemusic-v1.1",
  "custom": true,
  "title": "The Road Home",
  "lyric": "[Verse]\nThe evening breeze blows through familiar streets\n[Chorus]\nThe lights wait for me to return home",
  "style": "Chinese folk, acoustic guitar, warm vocals",
  "async": true
}
Field Description
action Currently only generate is supported; may be omitted
model acemusic-v1.1 or acemusic-v1
custom false uses inspiration mode; true uses custom lyrics
prompt Required creative description in inspiration mode
lyric / style / title Lyrics, music style, and title in custom mode
async Defaults to true; query results after receiving the task ID
callback_url Optional HTTPS completion callback URL; asynchronous execution is used when provided

The current generation API does not accept audio uploads, covers, continuations, stems, or timbre parameters. Style descriptions affect the creative direction; the performance and actual duration of the finished product are subject to the result.

Tasks and Delivery

Save the task_id returned upon submission, and query it through the Task API. Submission acceptance only indicates that the task has been created. The data in the complete result is a track list, and each track includes the platform track id, model, state, title, lyric, style, actual duration (seconds), audio_url, and optional image_url.

The entire group is marked as successful only after both audio tracks are deliverable. Partial failures retain completed tracks, and the task is marked as partial_failed; a missing cover does not affect playback of existing audio. After browser refreshes or network interruptions, query the original task instead of submitting the generation again.

The same Idempotency-Key with the same request content returns the original task; sending different content with the same key causes a conflict. When a timeout occurs and the acceptance status is unclear, retain that key and the original task identity, wait for a query or contact support, and do not automatically resend with a different key.

Fees

Charges are based on generation tasks, and a complete set of two tracks is charged only once. Fully failed or partially failed tasks are not charged a generation fee; task queries are free. The lyrics assistant is an independent paid API, and song generation does not automatically incur additional lyrics assistant fees.

Prices are subject to the corresponding plan in the Console. Under the highest-tier plan and exchange rate basis on 2026-11-17, one complete generation is equivalent to ¥0.20 CNY, approximately US$0.02995; different plans, discounts, site markups, and subsequent exchange rate changes will affect the converted amount.

Callbacks and Errors

After completion, the final task result is pushed to callback_url. The receiver should deduplicate by task_id and return a success status; callbacks may be retried. Callback delivery failures do not regenerate songs or incur additional charges, and results can still be obtained through the Task API.

Invalid parameters return 400; authentication or permission issues return 401/403; insufficient balance returns 402; rate limiting returns 429; service failures return 500. Asynchronous execution errors are expressed through the task terminal state and error. When troubleshooting, provide task_id and trace_id.