Retrieve the Library
November 14, 2026 (November 16, 2026)
Table of contents
List the songs in an account’s ACE Music Library, newest first: songs made through the API or on acemusic.ai, and audio uploaded with POST /files. Each one has a songId for POST /music references, stems, downloads and scores. ACE Music keeps every song until it is deleted, so this is also where to find the songs of a job older than 7 days.
Songs in this list carry audioUrl but no playUrl (it would cost one more call per song): read a song with GET /music/songId for its playUrl, the direct link for players.
The list is read live from ACE Music, which leaves failed songs out of it. Page through it with after: each page returns next, the value for the following page, and null on the last one.
https://api.useapi.net/v1/acemusic/music?email=
limit&after=after
Request Headers
Authorization: Bearer {API token}
API tokenis required, see Setup useapi.net for details.
Query Parameters
emailis optional with one account, and required when more than one is configured: the account whose Library to list.limitis optional, the number of songs per page.
Range:1to60. Default:20.afteris optional, thenextvalue of the previous page.
Responses
-
{ "email": "example@example.com", "songs": [ { "songId": "user:1234-example@example.com-song:so_7d2e9b4c1a8f4e6d93b0c5a1", "taskId": "so_7d2e9b4c1a8f4e6d93b0c5a1", "status": "succeeded", "title": "paper-boat-demo", "model": null, "style": "Gentle indie folk ballad, slow contemplative tempo. Fingerpicked acoustic guitar, warm bass and soft ambient textures, breathy female vocals.", "lyrics": "[verse]\nFold the morning into paper\nSend it down the gutter stream\nSail away, little paper boat\nCarry every quiet dream", "instrumental": false, "duration": 35, "audioUrl": null, "coverUrl": "https://acemusic.ai/data/so_7d2e9b4c1a8f4e6d93b0c5a1-cover.jpg?v=1794686793115", "pageUrl": null, "created": "2026-11-14T20:06:23.708Z", "finished": "2026-11-14T20:06:35.653Z", "kind": "upload", "score": true, "upload": { "seconds": 35, "bpm": 88, "transcription": "done" } }, { "songId": "user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "taskId": "so_4e7b2c9d0a5f4183b6d8e2c7", "status": "succeeded", "title": "Orchestral Morning", "model": "acemusic-v1", "style": "cinematic orchestral, soaring strings, choir, epic drums", "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", "instrumental": false, "duration": 44.71, "audioUrl": "https://acemusic.ai/data/so_4e7b2c9d0a5f4183b6d8e2c7.mp3", "coverUrl": "https://acemusic.ai/data/so_4e7b2c9d0a5f4183b6d8e2c7-cover.jpg?v=1794686500022", "pageUrl": "https://acemusic.ai/song/p6x2d8m4f9qa", "created": "2026-11-14T20:01:32.508Z", "finished": "2026-11-14T20:02:03.716Z", "kind": "original", "score": false } ], "next": "1794686492508~so_4e7b2c9d0a5f4183b6d8e2c7~1794686492508_1431913" } -
{ "error": "Parameter email is required when more than one account is configured", "code": 400 }{ "error": "Parameter limit (61) is more than 60", "code": 400 } -
Invalid API token.
{ "error": "useapi.net ⁝ Unauthorized", "code": 401 } -
{ "error": "Account example@example.com is not configured", "code": 404 } -
596 Account Error
ACE Music refused the stored email and password. Add the account again with the current password.
{ "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
One page of the account’s Library, newest song first, with the cursor for the next page.
The Library page, field by field, and the types it uses (Song, Split)
{ // TypeScript, all fields are optional
email: string // the account listed
songs: Song[] // newest first, see Song below
next: string | null // pass as `after` for the next page, null on the last page
}
Song: each item of songs 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
}[]
}
Examples
-
curl "https://api.useapi.net/v1/acemusic/music?email=example%40example.com&limit=20" \ -H "Authorization: Bearer …" -
const token = "API token"; const email = "example@example.com"; let after = null; do { const params = new URLSearchParams({ email, limit: "60" }); if (after) params.set("after", after); const page = await (await fetch(`https://api.useapi.net/v1/acemusic/music?${params}`, { headers: { "Authorization": `Bearer ${token}` } })).json(); page.songs.forEach(song => console.log(song.songId, song.title, song.audioUrl)); after = page.next; } while (after); -
import requests token = "API token" params = {"email": "example@example.com", "limit": 60} while True: page = requests.get("https://api.useapi.net/v1/acemusic/music", headers={"Authorization": f"Bearer {token}"}, params=params).json() for song in page["songs"]: print(song["songId"], song["title"], song["audioUrl"]) if not page.get("next"): break params["after"] = page["next"]