Split a song into stems
November 14, 2026 (November 16, 2026)
Table of contents
Split a finished song into stems with ACE Music’s stem splitter, on the account that holds the song. Stems need a paid ACE Music plan (Creator or Artist).
mode | Tracks | Credits |
|---|---|---|
vocals (default) | vocal and instrumental | 5 |
all | every stem ACE Music finds, such as vocals, backing_vocals, drums, bass, guitar, keyboard, strings, synth, woodwinds and fx | 60 |
Each track is an MP3 behind a signed link valid for 24 hours (expires). Read the job again with GET /jobs/jobid, or the song with GET /music/songId, for fresh links. A song that was already split in that mode answers at once with its tracks.
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/stems
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
{
"songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7",
"mode": "all",
"async": true,
"replyUrl": "https://your-domain.com/webhook",
"replyRef": "stems-1"
}
songIdis required, a finished song’ssongId(user:<id>-<email>-song:so_…). The split runs on the account that holds it.modeis optional.
Supported values:vocals(default),all.asyncis optional,trueto answer201at once and run the split in the background. Default:false.replyUrlis optional, a publichttpsURL that receives onePOSTof the job record when the split completes or fails.
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.
Responses
-
The split is done.
{ "jobid": "j1114203012775104298s-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.0-bot:acemusic", "type": "stems", "status": "completed", "email": "example@example.com", "created": "2026-11-14T20:30:12.775Z", "stems": { "mode": "vocals", "songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", "tracks": [ { "type": "vocal", "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/stem/202611/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…", "duration": 135.02 }, { "type": "instrumental", "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/stem/202611/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…", "duration": 135.02 } ], "expires": "2026-11-15T20:31:40.508Z" }, "completed": "2026-11-14T20:31:39.143Z", "job_state": "completed", "outputs": [ { "ok": true, "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/stem/202611/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…", "url_auth": "none", "mime": "audio/mpeg", "expires_at": "2026-11-15T20:31:40.531Z", "ref": null }, { "ok": true, "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/stem/202611/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…", "url_auth": "none", "mime": "audio/mpeg", "expires_at": "2026-11-15T20:31:40.531Z", "ref": null } ] } -
async: true, the split is running. A sync request that is still running after 100 seconds answers202with the same body.{ "jobid": "j1114203348120936514s-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.2-bot:acemusic", "type": "stems", "status": "processing", "email": "example@example.com", "created": "2026-11-14T20:33:48.120Z", "stems": { "mode": "all", "songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", "tracks": [] }, "replyUrl": "https://your-domain.com/webhook", "replyRef": "stems-1", "job_state": "in_progress", "outputs": [] } -
Sync mode, the split was still running 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. -
{ "error": "Parameter mode (drums) valid values: vocals,all", "code": 400 } -
Invalid API token.
{ "error": "useapi.net ⁝ Unauthorized", "code": 401 } -
The account is on the Free plan, or the song belongs to another useapi.net user.
{ "error": "Splitting the song into stems needs a paid ACE Music plan (the account is on free): Downloads come with a paid plan", "code": 403 } -
The account has too few credits for the split.
costis what it needs. -
Sync mode, ACE Music could not split the song. The body is the failed job record, with ACE Music’s reason in
error. -
The song’s account is running its
maxJobs. 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 } -
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 the song with GET /music/
songIdbefore you send it again: its stems 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. -
ACE Music did not answer within 30 seconds after the request was sent: it may have accepted it and charged for it. Check the song with GET /music/
songIdbefore you send it again.{ "error": "Splitting the song into stems: 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 song’s account. Add it again with the current password.
Model
The job record. GET /jobs/jobid and the replyUrl webhook return the same shape.
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/stems" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer …" \ -d '{ "songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", "mode": "vocals" }' -
const token = "API token"; const response = await fetch("https://api.useapi.net/v1/acemusic/music/stems", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }, body: JSON.stringify({ songId: "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", mode: "vocals" }) }); const job = await response.json(); console.log(response.status, job.status); job.stems?.tracks.forEach(track => console.log(track.type, track.url)); -
import requests token = "API token" response = requests.post( "https://api.useapi.net/v1/acemusic/music/stems", headers={"Authorization": f"Bearer {token}"}, json={"songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7", "mode": "vocals"} ) job = response.json() print(response.status_code, job.get("status")) for track in (job.get("stems") or {}).get("tracks", []): print(track["type"], track["url"])
Try It
The tracks play above the JSON once the split is completed.