Skip to main content
POST
ACE Music Audios

Authorizations

Authorization
string
header
required

Headers

Idempotency-Key
string

Reuse the same key for the same creation request to retrieve its original task. A different payload with the same key is rejected.

Body

application/json
prompt
string
required

Creation idea. Required when custom is false.

Required string length: 1 - 20000
action
enum<string>
default:generate

generate creates new songs, upload imports one MP3 audio reference, cover reworks one owned track, and mashup blends exactly two owned tracks.

Available options:
generate
custom
enum<boolean>
default:false

Only used by generate: false for an idea, true for supplied lyrics.

Available options:
false
model
enum<string>
default:acemusic-v1.1

Generation supports both models. Cover and mashup use acemusic-v1.1. Omit for upload.

Available options:
acemusic-v1.1,
acemusic-v1
lyric
string

Lyrics for custom generation, cover or mashup.

Required string length: 1 - 20000
style
string

Musical style for custom generation, cover or mashup.

Required string length: 1 - 20000
title
string

Required for custom generation; optional for cover and mashup.

Required string length: 1 - 20000
async
boolean
default:true

Return a persistent task ID; query /acemusic/tasks for the result.

callback_url
string<uri>

Optional HTTPS callback for the final result. Implies asynchronous execution.

Required string length: 1 - 20000
audio_url
string<uri>

HTTPS URL of an MP3 source file for upload. Use audio_id or mashup_audio_ids for already imported or generated tracks.

Required string length: 1 - 20000
Pattern: ^https://
name
string

Optional display name for an upload.

Required string length: 1 - 20000
audio_id
string

Public platform track ID owned by the caller. Required for cover; optional on upload to associate the import with an existing reference track.

Required string length: 1 - 20000
mashup_audio_ids
string[]

Exactly two distinct caller-owned public track IDs. The selected references must be compatible with each other.

Required array length: 2 elements
Required string length: 1 - 20000
audio_influence
number
default:60

Audio reference strength for cover and mashup. Defaults to 60.

Required range: 1 <= x <= 100

Response

Request accepted or result available. Generation, cover and mashup target two tracks; upload targets one. Inspect the original task state before treating it as complete.

task_id
string
required
trace_id
string