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, or use general application credentials that have permission for this service. IncludeAuthorization: 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.
Custom Mode
Setcustom 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, then edited and submitted.
Upload Reference Audio
Use the same song endpoint, setaction=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:
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 useacemusic-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.
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.
Common Fields
Tasks and Delivery
Save the returnedtask_id after submission, and query it through the Tasks API. 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 tocallback_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.
