> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# ACE Music Tasks and History API

> ACE Music integration guide - Ace Data Cloud

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

```bash theme={null}
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"}'
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.