Skip to main content
Query song, reference upload, and lyrics tasks via 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 items list and a count quantity; 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.