Retrieve the Library

November 14, 2026 (November 16, 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": "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"
    }
    
  • 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 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"]
    
Try It