Retrieve a job
November 14, 2026 (November 16, 2026)
Table of contents
Fetch a job by its jobid. POST /music and POST /music/stems return one. After an async request, or a sync one that answered 202, poll this endpoint until status is completed or failed.
Songs take 20 seconds to about 2 minutes and a stem split about 1.5 minutes, so polling every 10 seconds is enough. A job still running 30 minutes after it started fails with 504 when it is read. ACE Music may still finish it later, and a later read then shows it completed.
Every read asks ACE Music for the job’s songs, so links are always fresh: each song’s playUrl and the stem track links are read again. playUrl is a direct link to the same MP3 for players, valid until playUrlExpires (about an hour): some browsers (Brave) block the redirect behind audioUrl. Store audioUrl, play playUrl. Stem track links are valid for 24 hours from the read.
After the job ends, nothing of it is kept on our side: the record is rebuilt from the songs ACE Music keeps in the account’s Library. A song deleted since, with DELETE /music/songId or on acemusic.ai, is listed as { songId, taskId, status: "deleted" } with no links, and the job keeps its status from the song still there. A job none of whose songs ACE Music has any more answers 404, and any job answers 410 once it is older than 7 days.
Instead of polling, pass replyUrl (and optionally replyRef) with the POST: when the job completes or fails, the API sends one POST of this same job record, as JSON, to that URL. See Model.
https://api.useapi.net/v1/acemusic/jobs/
jobid
jobidis URL-encoded in the path (it contains:and@), for examplej1114201530412583907m-u1234-email%3Aexample%40example.com-task%3Aso_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot%3Aacemusic.
Request Headers
Authorization: Bearer {API token}
API tokenis required, see Setup useapi.net for details.
Responses
-
A song job (the songs are cut short here, see POST /music for full songs):
{ "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", "duration": 135.02, "audioUrl": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3", "playUrl": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261114T201722Z&X-Amz-Expires=3599&…", "playUrlExpires": "2026-11-14T21:17:21.000Z", "coverUrl": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7-cover.jpg?v=1794685678498", "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", "duration": 135.02, "audioUrl": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3.mp3", "playUrl": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261114T201723Z&X-Amz-Expires=3599&…", "playUrlExpires": "2026-11-14T21:17:22.000Z", "coverUrl": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3-cover.jpg?v=1794685679611", "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" } ] }The same job after its second song was deleted with DELETE /music/
songId, its song cut short the same way:{ "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", "audioUrl": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3", "playUrl": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261114T201722Z&X-Amz-Expires=3599&…", "playUrlExpires": "2026-11-14T21:17:21.000Z" }, { "songId": "user:1234-example@example.com-song:so_b6e14d0c9a7f4382be51f0a3", "taskId": "so_b6e14d0c9a7f4382be51f0a3", "status": "deleted" } ], "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": null }, { "ok": false, "url": null, "url_auth": "none", "mime": "audio/mpeg", "expires_at": null, "ref": "user:1234-example@example.com-song:so_b6e14d0c9a7f4382be51f0a3", "thumbnail_url": null } ] }A stem split, read a few minutes after it finished. Its track links are signed again on every read, so
expiresand eachexpires_atare 24 hours after the read:{ "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:35:59.230Z" }, "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:35:59.256Z", "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:35:59.256Z", "ref": null } ] }A job that is still running or that failed answers
200too: checkstatus, and for a failed jobcodeanderror. -
{ "error": "Path parameter jobid (not-a-job) is not a valid ACE Music job id", "code": 400 } -
Invalid API token.
{ "error": "useapi.net ⁝ Unauthorized", "code": 401 } -
The job belongs to another useapi.net user.
{ "error": "Not your job", "code": 403 } -
ACE Music has none of the job’s songs any more (deleted and then emptied from the trash on acemusic.ai), or the job’s account was removed.
{ "error": "Job j1114201530412583907m-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot:acemusic not found: ACE Music has none of its songs", "code": 404 }{ "error": "Account example@example.com is not configured: the job cannot be read", "code": 404 } -
The job is older than 7 days. Its songs are still in the account’s Library: read them with GET /music.
{ "error": "Job has expired: jobs can be read for 7 days", "code": 410 }
Model
The job record. POST /music and POST /music/stems return it too, and it is the body of the replyUrl webhook.
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
}
status | Meaning |
|---|---|
processing | ACE Music is making the songs or the split. Every job starts here. |
completed | Done. A song job is completed when at least one of its two songs succeeded. A song that failed carries its own error, and a song deleted since shows status: "deleted". |
failed | Done without a result. error says why and code is the HTTP status. |
code | Meaning |
|---|---|
400 | 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 run the request again. The songs show refunded: true: ACE Music gave the credits back. |
404 | The account was removed with DELETE /accounts/email while the job ran, or a stem split’s song was deleted (its stems went with it, stems.songStatus is deleted). |
422 | ACE Music could not make the songs or the split, and error has ACE Music’s reason. A failed song shows refunded: true when ACE Music gave its credits back. |
504 | The job did not finish within 30 minutes. ACE Music may still finish it and has likely charged for it: read the job again later (it shows completed once ACE Music finished it) or look for its songs with GET /music before you run it again. |
596 | The account was signed out while the job ran: ACE Music refused the stored password. ACE Music may still finish the job. Update the password with POST /accounts, then read the job again. |
The replyUrl webhook is one POST with Content-Type: application/json and this record as the body, sent once when the job completes or fails (a 10-second timeout, no retries, redirects are not followed). Use replyRef to match the callback to your own records.
Examples
-
JOBID="j1114201530412583907m-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot:acemusic" curl -H "Authorization: Bearer …" \ "https://api.useapi.net/v1/acemusic/jobs/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$JOBID")" -
const token = "API token"; const jobid = "j1114201530412583907m-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot:acemusic"; const apiUrl = `https://api.useapi.net/v1/acemusic/jobs/${encodeURIComponent(jobid)}`; let job; do { await new Promise(resolve => setTimeout(resolve, 10000)); const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}` } }); job = await response.json(); console.log(job.status); } while (job.status === "processing"); console.log("job", job); -
import requests, time, urllib.parse token = "API token" jobid = "j1114201530412583907m-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot:acemusic" apiUrl = "https://api.useapi.net/v1/acemusic/jobs/" + urllib.parse.quote(jobid, safe="") headers = {"Authorization": f"Bearer {token}"} while True: time.sleep(10) job = requests.get(apiUrl, headers=headers).json() print(job.get("status")) if job.get("status") != "processing": break print(job)
Try It
The songs or stem tracks play above the JSON once the job is completed.