Retrieve the Library

November 14, 2026

Table of contents

  1. Request Headers
  2. Query Parameters
  3. Responses
  4. Model
  5. Examples
  6. Try It

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=email&limit=limit&after=after

Request Headers 
Authorization: Bearer {API token}
Query Parameters
  • email is optional with one account, and required when more than one is configured: the account whose Library to list.
  • limit is optional, the number of songs per page.
    Range: 1 to 60. Default: 20.
  • after is optional, the next value of the previous page.
Responses

  • 200 OK

    {
  "email": "[email protected]",
  "songs": [
    {
      "songId": "user:[email protected]: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:[email protected]: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"
}

  • 400 Bad Request

    {
  "error": "Parameter email is required when more than one account is configured",
  "code": 400
}

    {
  "error": "Parameter limit (61) is more than 60",
  "code": 400
}

  • 401 Unauthorized

    Invalid API token.

    {
  "error": "useapi.net ⁝ Unauthorized",
  "code": 401
}

  • 404 Not Found

    {
  "error": "Account [email protected] 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 [email protected]: ACE Music refused the stored email and password. Update the password with POST /accounts to resume using this account",
  "code": 596
}
Model 
{ // 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:

{ // TypeScript, all fields are optional
  songId: string                 // user:<id>-<email>-song:so_…  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'
  title: string | null
  model: string | null           // acemusic-v1 | acemusic-v1.1 | 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
  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        // the same mp3 as a direct link for players, valid until playUrlExpires (about an hour):
                                 // some browsers (Brave) block the redirect behind audioUrl. Store audioUrl, play playUrl.
                                 // For about a minute after the song is made it is audioUrl itself (ACE Music serves the
                                 // file directly then). In job records and GET /music/{songId} only, not in GET /music or
                                 // POST /files. 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
                                 // an upload (kind 'upload'): no audioUrl; playUrl is its own audio, signed for 24 hours
  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'
  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
    reason?: string
  }
  refunded?: boolean             // ACE Music gave the credits back for a failed song
  stems?: {                      // splits made with POST /music/stems
    vocals?: { status?: string, tracks: { type?: string, url: string | null, duration?: number }[] }
    all?: { status?: string, tracks: { type?: string, url: string | null, duration?: number }[] }
  }                              // track links are signed (24 hours) on GET /music/{songId}, null elsewhere
  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
  }
}
Examples 
  • curl "https://api.useapi.net/v1/acemusic/music?email=example%40example.com&limit=20" \
   -H "Authorization: Bearer …"

  • const token = "API token";
const email = "[email protected]";
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": "[email protected]", "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"]
Try It