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.opensnake.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 items list and a count; 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.