POST /acemusic/tasks. Queries are free, require valid credentials and this API permission; results can still be read when the balance is zero. Clients cannot access other users’ works by passing another user ID.
Single Task
id uses the platform task_id returned by generation, reference upload, cover, mashup, or lyrics generation. The query returns a task record, including status, public creation parameters, time information, and response; the final song results are located in response.data. HTTP success only indicates that the query succeeded; the task and status of each song must be checked.
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 acountquantity; each record follows the single-task format.
Status and Recovery
Tasks continue processing through queuing, generation, and delivery stages.type=audios includes generate, upload, cover, and mashup, with no need to add new task types. There is one reference upon successful upload; when generation, cover, and mashup are fully successful, both candidate songs can be downloaded; final partial failure is partial_failed, and completed candidates are still retained. Failure details provide public error; retain the platform task ID and Trace ID during 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 a new charged generation; if the acceptance status is unclear, further verification may be needed, and it cannot be determined that resubmission is allowed 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 cover art; tracks without an audio address have not yet been delivered.
