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