Generate songs
November 14, 2026 (November 16, 2026)
Table of contents
Make two songs with ACE Music in one request, with vocals or instrumental, on ACE Music v1, ACE Music v1.1 Preview or the free ACE-Step v1.5 XL. Each song comes back with a public mp3 link, cover art, its title, style and lyrics, and a songId you can cover, remix, edit, mash up, split into stems, download as WAV, MIDI or MusicXML, or read as a score.
Two ways to make songs
The fields you send pick the way, as on the ACE Music website:
| Way | Send | What ACE Music does |
|---|---|---|
| Idea | prompt, and optionally up to 3 references and up to 3 images | Writes the style, lyrics and title from your idea, then makes the songs |
| Your own texts | style and lyrics (or instrumental: true), with an optional title, mode and the options | Sings your lyrics in your style, or covers, remixes, edits or mashes up songs |
A request with any of mode, style, lyrics, title, instrumental, referenceAudio or an option takes the second way. Never send prompt together with them: the API answers 400 and names what to drop. To have ACE Music write lyrics you can still edit, use POST /music/lyrics and POST /music/style first.
Modes
mode applies to the second way. A reference is a songId: a song made by the API, one from GET /music, or your own audio uploaded with POST /files.
mode | references | Runs on | What it does |
|---|---|---|---|
generate (default) | none | any model | New songs from style (required) and your lyrics. No lyrics makes an instrumental |
cover | 1 song | acemusic-v1.1, or ACE-Step on ace-step-1.5-xl | The song in a new style, following its melody, chords and structure |
remix | 1 song | ace-step-1.5-xl only, the default for this mode | ACE-Step’s remix: coverStrength keeps the original, remixStrength moves away from it |
edit | 1 song | ace-step-1.5-xl only, the default for this mode | Rewrites the part between start and end seconds, with new lyrics for that part |
mashup | 2 or 3 songs | acemusic-v1.1 | One new song from several. Without lyrics, ACE Music combines the songs’ own words |
instrumental: true works only with mode generate. A cover, remix, edit or mashup keeps the words of the songs it is made from, so other modes answer 400 to it.
ACE Music v1.1 follows a song by the melody it reads from the song’s score. A cover or mashup of an ACE Music v1 song reads its score first when it has none (free for ACE Music v1 songs, a few seconds). ACE-Step songs are not read automatically: if ACE Music answers ref_no_melody, call GET /music/score on the song first (1 credit), then try again.
Model switching
model is the model you ask for. As on the ACE Music website, a request that must read a song runs on ACE Music v1.1 Preview, the model that reads: a mashup, a cover asked on acemusic-v1, and a prompt with more than one reference on ace-step-1.5-xl. ACE Music can also switch a request itself, for example a prompt with a reference song on acemusic-v1, to keep its tune. The job reports both: model (asked) and modelUsed (ran). The credits and the text limits follow the model that runs, so a switched ACE-Step request costs 4 credits.
Cost
ACE Music charges per request when it accepts it: 4 credits on acemusic-v1 and acemusic-v1.1 (two songs, 2 credits a song) and nothing on ace-step-1.5-xl, which runs even on an account with 0 credits. An account with too few credits answers 412 with the cost. A song ACE Music could not make shows refunded: true when ACE Music gave its credits back. See Pricing.
Sync, async and webhooks
- Every request runs as a job. Sync (the default): the POST waits and answers
200with the finished job record, or with the job’s error code and the record. In our tests an ACE-Step request took 20 to 95 seconds, ACE Music v1.1 Preview about 35 to 75 seconds, ACE Music v1 about 80 to 105 seconds and a stem split about 90 seconds. If the job is still running after 100 seconds, the POST answers202with the job as it stands: fetch the result with GET /jobs/jobid. Always checkstatus: onlycompletedcarries the links. - Async: pass
async: true. The POST answers201at once with the job instatus: "processing". Poll GET /jobs/jobidor wait for the webhook. replyUrlreceives onePOSTof the final job record, as JSON, when the job completes or fails, for sync and async requests alike. WithoutreplyUrl, the defaultreplyUrlof your useapi.net account is used, see POST account, when it passes the same checks as a request’s: a publichttpsURL.- A job that has not finished 30 minutes after it started fails with
504. ACE Music may still finish it and has likely charged for it, so look for its songs with GET /music before you run it again. - Each account runs at most
maxJobsrequests at a time (default4, which is ACE Music’s own limit, range1to4, set with POST /accounts). GET /jobs shows what is running. A job can be read for 7 days.
https://api.useapi.net/v1/acemusic/music
Request Headers
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
API tokenis required, see Setup useapi.net for details.
Request Body
From an idea:
{
"prompt": "A short cheerful ukulele tune about a sunny Saturday morning at the farmers market",
"model": "ace-step-1.5-xl"
}
From your own style and lyrics:
{
"style": "synthwave, retro drum machine, warm analog pads, male vocals",
"lyrics": "[Verse]\nMorning light on the window pane\nCoffee steam and a quiet lane\n[Chorus]\nHold on, hold on, the day is new\nEvery road leads back to you",
"title": "Neon Morning",
"model": "acemusic-v1",
"duration": 120,
"async": true,
"replyUrl": "https://your-domain.com/webhook",
"replyRef": "neon-morning-1"
}
A cover of one of your songs:
{
"mode": "cover",
"references": ["user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7"],
"style": "acoustic folk, fingerpicked guitar, soft female vocals"
}
Idea:
promptis required for an idea, unlessreferencesorimagesare given: the song in your own words. ACE Music writes the style, lyrics and title.
Maximum length:2000characters.imagesis optional, up to3image ids from POST /files (user:<id>-<email>-media:cx_…), pictures the songs are about. Withpromptonly.
Your own texts:
modeis optional, see Modes.
Supported values:generate(default),cover,remix,edit,mashup.styleis required formodegenerate: genre, instruments, mood, tempo and vocals.
Maximum length:1000characters,512onace-step-1.5-xl.lyricsis optional, your lyrics with[verse]/[chorus]section tags. Inmodegenerate, no lyrics makes an instrumental. Inedit, the words for the part you rewrite.
Maximum length:5000characters,2000onace-step-1.5-xl.instrumentalis optional,truefor songs with no vocals, withmodegenerateonly. Not together withlyrics.titleis optional, the songs’ title.
Maximum length:80characters.- The options below.
Both ways:
modelis optional, the model to ask for, see Model switching.
Supported values:acemusic-v1(default),acemusic-v1.1,ace-step-1.5-xl(the default forremixandedit).referencesis optional, an array ofsongIds (user:<id>-<email>-song:so_…) from a finished job, GET /music or POST /files. Withprompt, up to3songs that guide the new ones. With amode, as many as the Modes table says. Each id once.emailis optional, the account to run on. When omitted, the account that holds thereferencesandimagesruns the request, or, with none, a healthy account with a freemaxJobsslot. Every song and image of one request must be on the same account.asyncis optional,trueto answer201at once and run the job in the background. Default:false.replyUrlis optional, a publichttpsURL that receives onePOSTof the job record when the job completes or fails. It works with sync and async requests.
Callback body has the same JSON shape as GET /jobs/jobidresponse.
Maximum length:2048characters.replyRefis optional, your own reference echoed back in the job record.
Maximum length:1024characters.
Any other parameter returns 400 Parameter <name> not supported.
Options
Each option works only where the table says, checked against the model that runs. Anywhere else the API answers 400 Parameter <name> does not apply to mode <mode> on <model>.
| Option | Values | Where |
|---|---|---|
duration | Song length in seconds: 30 to 600 on acemusic-v1, 10 to 240 on ace-step-1.5-xl. Default: the model decides | generate on acemusic-v1 or ace-step-1.5-xl |
negative | Styles to avoid, up to 200 characters | generate on acemusic-v1 or ace-step-1.5-xl |
styleInfluence | 0 to 100, default 80: how strictly your style is followed, as written when high, freely when low | acemusic-v1, acemusic-v1.1 |
audioInfluence | 0 to 100, default 60: how closely the reference is followed, its chords, sections, tempo, key and sound | acemusic-v1.1 with references (cover, mashup) |
bpm | 30 to 200 | generate on ace-step-1.5-xl |
timeSignature | 2/4, 3/4, 4/4, 6/8 | generate on ace-step-1.5-xl |
thinking | 0 to 100: ACE-Step plans the whole song first, creative when low, steady when high | generate on ace-step-1.5-xl |
key | C major, C minor, C# major … B minor: C, C#, D, Eb, E, F, F#, G, Ab, A, Bb and B, each major or minor | generate, cover, remix on ace-step-1.5-xl |
coverStrength | 0 to 100, default 20: how much of the original stays | cover, remix on ace-step-1.5-xl |
remixStrength | 0 to 100, default 0: how far it moves away from the original | cover, remix on ace-step-1.5-xl |
start, end | Seconds, 0 to 600, end at least 1 second after start. Required for edit | edit |
referenceAudio | A songId whose sound guides the result | any mode on ace-step-1.5-xl |
Responses
-
Sync mode, the job has finished. It is
completedwhen at least one of its two songs succeeded, here both: a song that failed carries its ownerror. EachaudioUrlis a public mp3 link.playUrlis a direct link to the same MP3 for players, valid untilplayUrlExpires(about an hour): some browsers (Brave) block the redirect behindaudioUrl. StoreaudioUrl, playplayUrl. For about a minute after a song is made ACE Music serves it ataudioUrlitself, so the answer that comes right then, as here, hasplayUrlequal toaudioUrlwith a one-minuteplayUrlExpires: read the job or the song again later for a fresh link.{ "jobid": "j1114201530412583907m-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot:acemusic", "type": "music", "status": "completed", "email": "example@example.com", "created": "2026-11-14T20:15:30.412Z", "model": "ace-step-1.5-xl", "modelUsed": "ace-step-1.5-xl", "songs": [ { "songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", "taskId": "so_3f9c2a7d81e64b05a9d2c4e7", "status": "succeeded", "title": "Farmers Market Sunshine", "model": "ace-step-1.5-xl", "style": "Upbeat indie folk, bright cheerful acoustic ukulele strumming, light hand percussion, shaker, warm upright bass, sweet breezy female vocals, sunny acoustic production.", "lyrics": "[verse 1]\nWoven tote bag swinging by my side\nMorning breeze and the sky open wide\n…\n\n[chorus]\nOh it's Saturday morning down at the square\n…", "instrumental": false, "duration": 135.02, "audioUrl": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3", "playUrl": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3", "playUrlExpires": "2026-11-14T20:17:20.318Z", "coverUrl": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7-cover.jpg?v=1794685678498", "pageUrl": "https://acemusic.ai/song/k4m8q2vz7xpd", "created": "2026-11-14T20:15:30.439Z", "finished": "2026-11-14T20:16:14.205Z", "kind": "original", "score": false }, { "songId": "user:1234-example@example.com-song:so_b6e14d0c9a7f4382be51f0a3", "taskId": "so_b6e14d0c9a7f4382be51f0a3", "status": "succeeded", "title": "Farmers Market Sunshine", "model": "ace-step-1.5-xl", "style": "Upbeat indie folk, bright cheerful acoustic ukulele strumming, light hand percussion, shaker, warm upright bass, sweet breezy female vocals, sunny acoustic production.", "lyrics": "[verse 1]\nWoven tote bag swinging by my side\nMorning breeze and the sky open wide\n…\n\n[chorus]\nOh it's Saturday morning down at the square\n…", "instrumental": false, "duration": 135.02, "audioUrl": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3.mp3", "playUrl": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3.mp3", "playUrlExpires": "2026-11-14T20:17:20.318Z", "coverUrl": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3-cover.jpg?v=1794685679611", "pageUrl": "https://acemusic.ai/song/w7n3c5r9t2hb", "created": "2026-11-14T20:15:30.440Z", "finished": "2026-11-14T20:16:14.205Z", "kind": "original", "score": false } ], "completed": "2026-11-14T20:16:14.205Z", "job_state": "completed", "outputs": [ { "ok": true, "url": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3", "url_auth": "none", "mime": "audio/mpeg", "expires_at": null, "ref": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", "thumbnail_url": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7-cover.jpg?v=1794685678498" }, { "ok": true, "url": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3.mp3", "url_auth": "none", "mime": "audio/mpeg", "expires_at": null, "ref": "user:1234-example@example.com-song:so_b6e14d0c9a7f4382be51f0a3", "thumbnail_url": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3-cover.jpg?v=1794685679611" } ] } -
async: true, the job is running, here an idea onacemusic-v1. While ACE Music writes the lyrics, the songs areplanningandUntitled. Poll GET /jobs/jobidor wait for the webhook.{ "jobid": "j1114202212045711826m-u1234-email:example@example.com-task:so_8c1d4f7a2b9e4c06a3f5d7e1.so_e2a7b9c4d6f84a1b95c3e0d8-bot:acemusic", "type": "music", "status": "processing", "email": "example@example.com", "created": "2026-11-14T20:22:12.045Z", "model": "acemusic-v1", "modelUsed": "acemusic-v1", "songs": [ { "songId": "user:1234-example@example.com-song:so_8c1d4f7a2b9e4c06a3f5d7e1", "taskId": "so_8c1d4f7a2b9e4c06a3f5d7e1", "status": "planning", "title": "Untitled", "model": "acemusic-v1", "style": null, "lyrics": null, "instrumental": false, "duration": null, "audioUrl": null, "playUrl": null, "playUrlExpires": null, "coverUrl": null, "pageUrl": null, "created": "2026-11-14T20:22:12.068Z", "finished": null, "kind": "original", "score": false }, { "songId": "user:1234-example@example.com-song:so_e2a7b9c4d6f84a1b95c3e0d8", "taskId": "so_e2a7b9c4d6f84a1b95c3e0d8", "status": "planning", "title": "Untitled", "model": "acemusic-v1", "style": null, "lyrics": null, "instrumental": false, "duration": null, "audioUrl": null, "playUrl": null, "playUrlExpires": null, "coverUrl": null, "pageUrl": null, "created": "2026-11-14T20:22:12.069Z", "finished": null, "kind": "original", "score": false } ], "replyUrl": "https://your-domain.com/webhook", "replyRef": "lofi-1", "job_state": "in_progress", "outputs": [ { "ok": false, "url": null, "url_auth": "none", "mime": "audio/mpeg", "expires_at": null, "ref": "user:1234-example@example.com-song:so_8c1d4f7a2b9e4c06a3f5d7e1", "thumbnail_url": null }, { "ok": false, "url": null, "url_auth": "none", "mime": "audio/mpeg", "expires_at": null, "ref": "user:1234-example@example.com-song:so_e2a7b9c4d6f84a1b95c3e0d8", "thumbnail_url": null } ] } -
Sync mode, the songs were still being made after 100 seconds. The body is the job as it stands, the same shape as
201, withstatus: "processing". Fetch the result with GET /jobs/jobidor wait for the webhook. -
A parameter is missing or invalid, the parameters mix the two ways, or ACE Music refused the request. A few of the answers:
{ "error": "Send prompt or lyrics, not both: drop lyrics to have ACE Music write the song from your prompt, or drop prompt to sing your own lyrics (with style)", "code": 400 }{ "error": "mode mashup takes 2 to 3 songs in references", "code": 400 }{ "error": "Parameter bpm does not apply to mode generate on acemusic-v1", "code": 400 }{ "error": "Song user:1234-example2@example.com-song:so_5a0e3c8b1d7f4e92a6c4b8d0 is on account example2@example.com, not example@example.com: songs and images only work on the account that holds them", "code": 400 }{ "error": "Please add at least one ACE Music account first: https://useapi.net/docs/api-acemusic-v1/post-acemusic-accounts", "code": 400 }Sync mode, ACE Music could not read the melody of a referenced song (
ref_no_melody), usually an ACE-Step song with no score yet. Read its score with GET /music/score, then send the request again. The body is the failed job record, and the credits came back (refunded: true):{ "jobid": "j1114200257596846480m-u1234-email:example@example.com-task:so_9a4f1c7e3b2d4a8c96e0b5d2.so_0c6b8e2a4f1d4b7a83e9c5f1-bot:acemusic", "type": "music", "status": "failed", "email": "example@example.com", "created": "2026-11-14T20:02:57.596Z", "model": "ace-step-1.5-xl", "modelUsed": "acemusic-v1.1", "songs": [ { "songId": "user:1234-example@example.com-song:so_9a4f1c7e3b2d4a8c96e0b5d2", "taskId": "so_9a4f1c7e3b2d4a8c96e0b5d2", "status": "failed", "title": "Untitled", "model": "acemusic-v1.1", "style": "upbeat pop mashup, bright synths", "lyrics": null, "instrumental": false, "duration": null, "audioUrl": null, "playUrl": null, "playUrlExpires": null, "coverUrl": null, "pageUrl": null, "created": "2026-11-14T20:02:57.619Z", "finished": null, "kind": "mashup", "score": false, "error": { "code": "ref_no_melody", "message": "No melody could be found in the reference" }, "refunded": true }, { "songId": "user:1234-example@example.com-song:so_0c6b8e2a4f1d4b7a83e9c5f1", "taskId": "so_0c6b8e2a4f1d4b7a83e9c5f1", "status": "failed", "title": "Untitled", "model": "acemusic-v1.1", "style": "upbeat pop mashup, bright synths", "lyrics": null, "instrumental": false, "duration": null, "audioUrl": null, "playUrl": null, "playUrlExpires": null, "coverUrl": null, "pageUrl": null, "created": "2026-11-14T20:02:57.620Z", "finished": null, "kind": "mashup", "score": false, "error": { "code": "ref_no_melody", "message": "No melody could be found in the reference" }, "refunded": true } ], "completed": "2026-11-14T20:03:46.414Z", "code": 400, "error": "ACE Music could not read the melody of the referenced song (ref_no_melody): read its score first with GET /music/score, then try again. ACE Music refunded the credits", "job_state": "failed", "outputs": [ { "ok": false, "url": null, "url_auth": "none", "mime": "audio/mpeg", "expires_at": null, "ref": "user:1234-example@example.com-song:so_9a4f1c7e3b2d4a8c96e0b5d2", "thumbnail_url": null }, { "ok": false, "url": null, "url_auth": "none", "mime": "audio/mpeg", "expires_at": null, "ref": "user:1234-example@example.com-song:so_0c6b8e2a4f1d4b7a83e9c5f1", "thumbnail_url": null } ], "error_info": { "code": "input_rejected", "message": "ACE Music could not read the melody of the referenced song (ref_no_melody): read its score first with GET /music/score, then try again. ACE Music refunded the credits", "retry": { "mode": "never", "action": "replace_input" }, "vendor_code": "ref_no_melody" } } -
Invalid API token.
{ "error": "useapi.net ⁝ Unauthorized", "code": 401 } -
A
songIdor image id belongs to another useapi.net user.{ "error": "Song user:5678-someone@example.com-song:so_c155273ac66b4f2fa0c0dad1 is not yours", "code": 403 } -
{ "error": "Account example@example.com is not configured", "code": 404 } -
The account has too few credits for
acemusic-v1oracemusic-v1.1.costis what the request needs. Withoutemail, the API first tries your other accounts.ace-step-1.5-xlneeds no credits.{ "error": "Generating the songs: Not enough credits — a generation costs 4.", "code": 412, "cost": 4 } -
Sync mode, ACE Music could not make either song. The body is the failed job record, the same shape as the
ref_no_melodyexample under400, withcode: 422, ACE Music’s reason and code inerrorand each song’s ownerror. A song showsrefunded: truewhen ACE Music gave its credits back. -
The account named by
email, or the account that holds the references, is running itsmaxJobs. Without them, every account is. ACE Music can answer429itself while songs of the account are still being made. Retry after theRetry-Afterheader (30 seconds).{ "error": "Account example@example.com is running 4 of 4 jobs (maxJobs). Wait for one to finish, or raise maxJobs with POST /accounts", "code": 429 }{ "error": "All 3 usable ACE Music accounts are running their maximum number of jobs (maxJobs), please retry shortly", "code": 429 } -
ACE Music may have accepted the request, and charged for it, but its answer was lost, or it answered with something unexpected after accepting it. Check GET /music before you send it again: the songs may be there.
-
ACE Music is busy, could not be reached before the request was sent, or the session is being renewed. Nothing was charged: retry after the
Retry-Afterheader.When ACE Music may have accepted the request but its answer was lost, the API answers
502(or504on a timeout) instead, saying it may already have charged: check GET /music before you send it again. -
ACE Music did not answer within 30 seconds after the request was sent: it may have accepted it and charged for it. Check GET /music before you send it again.
{ "error": "Generating the songs: ACE Music did not answer within 30 s. It may already have charged for this: check GET /music before retrying", "code": 504 } -
596 Account Error
ACE Music refused the stored email and password of the account. Add it again with the current password, see Setup ACE Music.
{ "error": "Account example@example.com: ACE Music refused the stored email and password. Update the password with POST /accounts to resume using this account", "code": 596 }
Model
The job record. GET /jobs/jobid and the replyUrl webhook return the same shape. A failed sync job answers with the HTTP status in code and the failed record as the body.
The job record, field by field, and the types it uses (Song, Output, ErrorInfo)
{ // TypeScript, all fields are optional
jobid: string // the job's id, `j…-u<id>-email:<email>-task:…-bot:acemusic`. It names the account and
// the song or songs the job is about. Read the job with GET /jobs/{jobid}
type: 'music' | 'stems' // music: POST /music. stems: POST /music/stems
status: 'processing' | 'completed' | 'failed' // processing: ACE Music is making the songs or the split (every job
// starts here). completed: done, a song job once at least one of its two songs succeeded.
// failed: done without a result, error says why and code is the HTTP status
email: string // the ACE Music account the job runs on
created: string // ISO 8601
completed?: string // ISO 8601, when the job completed or failed
model?: string // music: the model you asked for
modelUsed?: string // music: the model that made the songs. It differs from model when the request ran on
// another one: a request that must read a song (a mashup, a cover asked on acemusic-v1, a
// prompt with more than one reference on ace-step-1.5-xl) runs on acemusic-v1.1, and ACE
// Music can also switch a request itself
songs?: (Song | DeletedSong)[] // music: the request's two songs, see Song below. A song deleted since, with
// DELETE /music/{songId} or on acemusic.ai, is a DeletedSong
stems?: { // on a stems job: the split
mode: 'vocals' | 'all' // the split you asked for
songId: string // the song that was split
songStatus?: 'deleted' // the song was deleted, its stems went with it (the job failed with code 404)
tracks: { // one per stem
type: string // vocals: vocal, instrumental. all: vocals, `backing_vocals`, drums, bass, guitar,
// keyboard, strings, synth, woodwinds, fx (the stems ACE Music found)
url: string | null // signed mp3 link, valid 24 hours
duration?: number // seconds
}[]
expires?: string // ISO 8601, when the track links stop working (read the job again for fresh ones)
}
error?: string // status 'failed': why
code?: number // status failed: the HTTP status of the failure. 400: ACE Music could not read a
// referenced song's melody (read its score with GET /music/score, then run it again). 404:
// the account was removed, or a split's song was deleted. 422: ACE Music could not make
// the songs or the split. 504: not finished within 30 minutes (ACE Music may still finish
// it). 596: the account was signed out
replyUrl?: string // the replyUrl you sent: it receives this record when the job ends
replyRef?: string // the replyRef you sent, echoed back
job_state: 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled' | 'expired' | 'unknown'
// where the job is, in the same words for every useapi.net API
outputs: Output[] // one entry per file the job made, see Output below
error_info?: ErrorInfo // only on a failed job: why, and whether to retry, see ErrorInfo below
}
Song: each item of songs in the job record above.
{ // TypeScript, all fields are optional
songId: string // user:<id>-<email>-song:so_…, the song's id: use it as a reference, to split, download or delete
taskId: string // ACE Music's own id of the song (so_…)
status: 'planning' | 'scoring' | 'queued' | 'running' | 'succeeded' | 'failed' | 'interrupted'
// ACE Music's progress on the song
title: string | null // the song's title (ACE Music writes one for a prompt request)
model: string | null // acemusic-v1, acemusic-v1.1 or ace-step-1.5-xl. null for an uploaded file
style: string | null // the style the song was made with (ACE Music writes it for a prompt request)
lyrics: string | null // [verse] / [chorus] tagged
instrumental: boolean | null // true for a song with no vocals
duration: number | null // seconds
audioUrl: string | null // public mp3 link, https://acemusic.ai/data/<taskId>.mp3, once the song succeeded.
// It never changes: store this one. null for an uploaded file: get its audio with
// GET /music/download
playUrl?: string | null // a direct link to the song's audio for players, valid until playUrlExpires: about an
// hour for a made song (the same mp3 as audioUrl), 24 hours for an upload (its own audio,
// in the format it was uploaded in). Some browsers (Brave) block the redirect behind
// audioUrl: store audioUrl, play playUrl. For about a minute after a song is made it is
// audioUrl itself (ACE Music serves the file directly then). In job records,
// GET /music/{songId} and an audio upload's POST /files answer, not in GET /music. null
// while the song is not finished, or when the link could not be read
playUrlExpires?: string | null // ISO 8601, when playUrl stops working: read the job or the song again for a fresh one
coverUrl: string | null // cover art (jpg)
pageUrl: string | null // the song's page on acemusic.ai, when ACE Music made one
created: string | null // ISO 8601
finished: string | null // ISO 8601
kind: 'original' | 'cover' | 'mashup' | 'edit' | 'upload' // how the song was made: original (a prompt or mode
// generate), cover (mode cover, and mode remix too), mashup, edit, or upload (a file
// sent with POST /files)
score: boolean // true when ACE Music already has the song's score (GET /music/score)
error?: { // a failed song
code?: string // ACE Music's code, e.g. `ref_no_melody`, `song_not_made`
message?: string // ACE Music's own words
reason?: string // ACE Music's reason, when it gives one
}
refunded?: boolean // ACE Music gave the credits back for a failed song
stems?: { // splits made with POST /music/stems. Their track links are signed (24 hours) on
// GET /music/{songId}, null elsewhere
vocals?: Split // mode vocals: vocal and instrumental
all?: Split // mode all: every stem ACE Music found
}
upload?: { // an uploaded audio file (POST /files)
seconds?: number // its length, counted against the account's upload minutes
bpm?: number // the tempo ACE Music read
transcription?: string // done once ACE Music has read its lyrics, style and melody
}
}
Split: each split in stems of a Song above (vocals, all).
{ // TypeScript
status?: string // ACE Music's progress on the split
tracks: { // one per stem
type?: string // the stem, e.g. vocals, drums, bass
url: string | null // signed mp3 link (24 hours) on GET /music/{songId}, null elsewhere
duration?: number // seconds
}[]
}
DeletedSong: an item of songs whose song was deleted since, with DELETE /music/{songId} or on acemusic.ai.
{ // TypeScript
songId: string // the song's id, as it was
taskId: string // ACE Music's own id of the song (so_…)
status: 'deleted' // deleted with DELETE /music/{songId} or on acemusic.ai
}
Output: each item of outputs in the job record above.
{ // TypeScript
ok: boolean // true when this file is ready to use
url: string | null // the link to the file, always absolute
url_auth: 'none' | 'bearer' // none: open the link as it is. bearer: send your API token with it
mime: string // the file type, e.g. audio/mpeg
expires_at: string | null // ISO 8601, when the link stops working. null when it does not expire
ref: string | null // the id to use for this file in later calls
thumbnail_url?: string | null // a cover or preview image
text?: string // the text, when the output is text
}
ErrorInfo: the error_info of a failed job above.
{ // TypeScript
code: string // the kind of failure, in the same words for every useapi.net API, e.g. `timeout`,
// `generation_failed`, `input_rejected`, `not_found`, `account_unhealthy`
message: string // what went wrong, in the API's own words
retry: { // whether and when to send it again
mode: 'never' | 'now' | 'backoff' | 'after' | 'after_reset' | 'other_account'
// never: do not send it again as it is (see action). now: send it again right
// away. backoff: send it again later, waiting longer each time. after: send it again
// once the wait in seconds has passed. after_reset: send it again once the account's credits or
// usage limit reset. other_account: send it on another account
seconds?: number // mode after: wait this long (or the Retry-After header)
max?: number // retry at most this many times
action?: string // what to change first, e.g. `fix_body`, `replace_input`, `add_credits`, `upgrade_plan`
}
vendor_code?: string // the code the vendor answered with
}
Examples
-
curl -X POST "https://api.useapi.net/v1/acemusic/music" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "prompt": "A short cheerful ukulele tune about a sunny Saturday morning at the farmers market", "model": "ace-step-1.5-xl" }' -
const token = "API token"; const apiUrl = "https://api.useapi.net/v1/acemusic"; const headers = { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }; const response = await fetch(`${apiUrl}/music`, { method: "POST", headers, body: JSON.stringify({ style: "synthwave, retro drum machine, warm analog pads, male vocals", lyrics: "[Verse]\nMorning light on the window pane\n[Chorus]\nHold on, the day is new", model: "acemusic-v1", async: true }) }); let job = await response.json(); console.log("submitted", response.status, job.jobid); while (job.status === "processing") { await new Promise(r => setTimeout(r, 10000)); job = await (await fetch(`${apiUrl}/jobs/${encodeURIComponent(job.jobid)}`, { headers })).json(); console.log(job.status); } if (job.status === "completed") job.songs.forEach(song => console.log(song.title, 'store:', song.audioUrl, 'play:', song.playUrl)); else console.log("error", job.code, job.error); -
import time import requests from urllib.parse import quote token = "API token" apiUrl = "https://api.useapi.net/v1/acemusic" headers = {"Content-Type": "application/json", "Authorization": f"Bearer {token}"} data = { "style": "synthwave, retro drum machine, warm analog pads, male vocals", "lyrics": "[Verse]\nMorning light on the window pane\n[Chorus]\nHold on, the day is new", "model": "acemusic-v1", "async": True } job = requests.post(f"{apiUrl}/music", headers=headers, json=data).json() print("submitted", job.get("jobid")) while job.get("status") == "processing": time.sleep(10) job = requests.get(f"{apiUrl}/jobs/{quote(job['jobid'], safe='')}", headers=headers).json() print(job.get("status")) if job.get("status") == "completed": for song in job["songs"]: print(song["title"], "store:", song["audioUrl"], "play:", song.get("playUrl")) else: print("error", job.get("code"), job.get("error"))
Try It
Leave a field empty to leave it out. references and images take ids separated by commas. The songs play above the JSON once the job is completed.