ACE Music Tasks and History API
Query song and lyrics tasks through POST /acemusic/tasks. Queries are free, require valid credentials and this API permission; you can still read your own results with a zero balance. Clients cannot access other users' works by passing other user IDs.
¶ Single Task
curl --request POST 'https://api.acedata.cloud/acemusic/tasks' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"action":"retrieve","id":"YOUR_TASK_ID"}'
Use the platform task_id returned by song or lyrics generation for id. The query returns a task record, including status, public creation parameters, time information, and response; final song results are located in response.data. HTTP success only indicates that the query succeeded; you must check the status of the task and each song.
¶ Batch and History
- Batch query:
{"action":"retrieve_batch","ids":["TASK_ID_1","TASK_ID_2"]}. Up to 100 IDs at a time. - Paginated history:
{"action":"list","page":1,"page_size":20}. Page numbers start from 1, with up to 100 entries per page. - Batch and history results contain an
itemslist and acount; each record follows the single-task format.
¶ Status and Recovery
Tasks continue to be processed during the queueing, generation, and delivery stages. Upon complete success, both candidates can be downloaded; final partial failure is partial_failed, and completed candidates are still retained. Failure details provide a public error; retain the platform task ID and Trace ID when troubleshooting.
It is recommended to poll at intervals of several seconds and gradually back off, stopping after reaching a terminal state. Continue querying the original task after an interface refresh or connection interruption. Platform recovery processing will not proactively create new billable generations; if the acceptance status is unclear, further verification may be needed, and you cannot determine that it can be resent based on waiting time alone.
Use the audio_url of completed tracks in response.data for playback, and the download format is subject to the actual returned file. Playback can continue without a cover; tracks without an audio address have not yet been delivered.
