> ## 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 任务与历史 API

> ACE Music 集成指南 - Ace Data Cloud

通过 `POST /acemusic/tasks` 查询歌曲、参考上传和歌词任务。查询免费、需要有效凭据和该 API 权限；余额为零仍可读取自己的结果。客户端不能通过传入其他用户 ID 访问他人作品。

## 单个任务

```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` 使用生成、参考上传、翻唱、融合或歌词生成返回的平台 `task_id`。查询返回任务记录，包含状态、公开创作参数、时间信息与 `response`；最终歌曲结果位于 `response.data`。HTTP 成功仅表示查询成功，须检查任务和每首歌曲的状态。

## 批量和历史

* 批量查询：`{"action":"retrieve_batch","ids":["TASK_ID_1","TASK_ID_2"]}`。一次最多 100 个 ID。
* 分页历史：`{"action":"list","page":1,"page_size":20}`。页码从 1 开始，每页最多 100 条。
* 批量和历史结果为 `items` 列表与 `count` 数量；每条记录遵循单任务格式。

## 状态与恢复

任务在排队、生成和交付阶段持续处理。`type=audios` 包含 `generate`、`upload`、`cover` 和 `mashup`，无需新增任务类型。上传成功时有一首参考；生成、翻唱与融合完整成功时两首候选均可下载；最终部分失败为 `partial_failed`，已完成的候选仍保留。失败详情提供可公开的 `error`，排查时保留平台任务 ID 和 Trace ID。

建议数秒间隔轮询并逐步退避，达到终态后停止。界面刷新或连接中断后继续查询原任务。平台恢复处理不会主动创建新的收费生成；受理状态不明确时可能需要进一步核查，不能仅凭等待时间判定可以重发。

播放使用 `response.data` 中已完成音轨的 `audio_url`，下载格式以实际返回文件为准。没有封面可继续播放；尚无音频地址的音轨仍未交付。


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