> ## 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 Song and Reference Audio API

> ACE Music integration guide - Ace Data Cloud

Use `POST /acemusic/audios` to create songs from inspiration or custom lyrics, import reference audio, cover existing works, or mash up two references. Song creation, covers, and mashups are each provided as a set of two candidates; audio upload imports one reference. The two types of operations are billed separately.

## Obtain Credentials

Enable ACE Music in the [Console](https://platform.acedata.cloud/console/applications), or use general application credentials that have permission for this service. Include `Authorization: Bearer YOUR_API_KEY` in requests. Application balance, credential quotas, and service permissions are all checked.

## Inspiration Mode

`action` defaults to `generate`. Available models are `acemusic-v1.1` (default) and `acemusic-v1`.

```bash theme={null}
curl --request POST 'https://api.acedata.cloud/acemusic/audios' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: music-draft-001' \
  --data '{
    "action": "generate",
    "model": "acemusic-v1.1",
    "custom": false,
    "prompt": "A Chinese song about hometown, in a warm folk style",
    "async": true
  }'
```

## Custom Mode

Set `custom` to `true` in `generate`, and provide `title`, `lyric`, and `style`. Lyrics may include section labels such as `[Verse]` and `[Chorus]`, or can be created first through the [Lyrics Generation API](https://platform.acedata.cloud/documents/acemusic-lyrics-integration), then edited and submitted.

```json theme={null}
{
  "action": "generate",
  "model": "acemusic-v1.1",
  "custom": true,
  "title": "The Way Home",
  "lyric": "[Verse]\nThe evening breeze blows through familiar streets\n[Chorus]\nThe lights wait for me to come home",
  "style": "Chinese folk, acoustic guitar, warm vocals",
  "async": true
}
```

## Upload Reference Audio

Use the same song endpoint, set `action=upload` and provide a valid HTTPS `audio_url`, with an optional `name`. Reference import currently supports MP3 files only. This operation does not require `model`, `custom`, or lyric fields. It only uploads and prepares the reference, and does not automatically generate another song.

The following is a request example; please replace it with an audio URL that you have the right to use:

```json theme={null}
{
  "action": "upload",
  "audio_url": "https://example.com/my-reference.mp3",
  "name": "My Reference Melody",
  "async": true
}
```

If you want to use the new reference together with an existing work, you can provide that work's platform `audio_id` when uploading. The `data` after upload completion contains one audio track, whose `id` can be used for covers or mashups. Uploading local files to a file service and importing references through this endpoint are different operations; after a reference is successfully imported, it is charged at the upload price.

## Covers and Two-Reference Mashups

Both operations use `acemusic-v1.1`, which remains the default model. Provide `lyric` and `style`, with optional `title`; do not provide `custom` or the inspiration `prompt` again. `audio_influence` controls the degree of audio reference, ranging from 1–100, with a default of 60. Style strength, instrumental-only, continuation, track separation, or timbre parameters are currently not accepted.

`cover` uses one platform track `audio_id` that you can access. Obtain the value from `response.data[*].id` of a previously successful task; it is not the generation task's `task_id`. The following ID is a request placeholder to be replaced, not an example result.

```json theme={null}
{
  "action": "cover",
  "model": "acemusic-v1.1",
  "audio_id": "YOUR_TRACK_ID",
  "lyric": "[Verse]\nThe evening breeze blows through familiar streets",
  "style": "Warm folk, acoustic guitar",
  "audio_influence": 60,
  "async": true
}
```

`mashup` uses `mashup_audio_ids`, which currently requires exactly two different platform tracks. References may come from completed upload or song tasks, and must belong to works that you can access and that are compatible with each other; incompatible combinations will be rejected.

```json theme={null}
{
  "action": "mashup",
  "model": "acemusic-v1.1",
  "mashup_audio_ids": ["YOUR_FIRST_TRACK_ID", "YOUR_SECOND_TRACK_ID"],
  "lyric": "[Verse]\nTurn two journeys into one song",
  "style": "Chinese pop, blending the melodies and rhythms of the two references",
  "async": true
}
```

## Common Fields

| Field | Description |
| - | - |
| `action` | `generate` (default), `upload`, `cover`, or `mashup` |
| `model` | Two models are available for `generate`; `cover` / `mashup` use `acemusic-v1.1`; do not provide it for `upload` |
| `custom` / `prompt` | Used only by `generate`: provide `prompt` in inspiration mode, and `lyric` / `style` / `title` in custom mode |
| `lyric` / `style` / `title` | All are required for custom generation; lyrics and style are required for covers and mashups, while title is optional |
| `audio_url` / `name` | HTTPS URL of the MP3 file to import and an optional display name |
| `audio_id` | The reference track for a cover, or the track used to associate an existing reference during upload |
| `mashup_audio_ids` | The two different reference tracks for a mashup |
| `audio_influence` | Degree of audio reference for covers / mashups, 1–100, default 60 |
| `async` | Defaults to `true`; query the result after receiving the task ID |
| `callback_url` | Optional HTTPS completion callback URL; uses asynchronous execution when provided |

## Tasks and Delivery

Save the returned `task_id` after submission, and query it through the [Tasks API](https://platform.acedata.cloud/documents/acemusic-tasks-integration). Submission acceptance only means that the task has been created. History with `type=audios` includes all four operations. The `data` in the complete result is an audio track list, and each track includes the platform track `id`, `model`, `state`, `title`, `lyric`, `style`, actual `duration` (seconds), `audio_url`, and optional `image_url`.

When an upload succeeds, one reference is delivered; generation, covers, or mashups are marked as successful for the entire group only after both audio tracks can be delivered. Partially failed tasks retain completed audio tracks and are marked as `partial_failed`; a missing cover image does not affect playback of existing audio. After browser refreshes or network interruptions, query the original task instead of resubmitting generation or upload.
The same `Idempotency-Key` with the same request content returns the original task; sending different content with the same key will cause a conflict. If a timeout occurs and the acceptance status is unclear, retain that key and the original task identity, wait for a query or contact support, and do not automatically resend with a new key.

## Fees

Generation, cover, and fusion are charged per complete two-track set, with only one charge per set; tasks that ultimately fail or partially fail are not charged a generation fee. Uploading a reference is an independent billable operation; a successful import of one reference incurs one upload fee, while ultimate failures are not charged. Queries are free; the lyrics assistant is also charged independently, and song operations do not implicitly incur additional lyrics assistant fees.

A complete two-track set costs 0.314816994048 Credits, and a successful reference upload costs 0.0157408497024 Credits. Based on the maximum plan and exchange rate benchmark as of 2026-11-17, these are equivalent to ¥0.20 and ¥0.01 respectively. Actual prices and conversions are subject to the applicable plan, discounts, site pricing, and exchange rates in the console.

## Callbacks and Errors

After completion, the final task result is pushed to `callback_url`. The recipient should deduplicate by `task_id` and return a success status; callbacks may be retried. Callback delivery failures will not trigger regeneration, re-importing, or additional charges, and results can still be retrieved using the task API.

Invalid parameters or incompatible references return 400; authentication or permission issues return 401/403; insufficient balance returns 402; rate limiting returns 429; service failures return 500. Asynchronous execution errors are expressed through the task terminal status and `error`. When troubleshooting, provide `task_id` and `trace_id`.


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