Retrieve a song’s score

November 14, 2026 (November 16, 2026)

Table of contents

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

Get the score of a finished song in ABC notation: the vocal melody, an instrumental line, chords and sections, which any ABC tool turns into sheet music or MIDI. It works on every ACE Music plan, the Free plan included.

ACE Music reads the score from the song on the first request and keeps it with the song. ACE Music v1.1 Preview songs come with their score already, because that model writes one before the audio. Reading the score of an ACE-Step v1.5 XL song costs 1 credit the first time, and ACE Music v1 songs cost nothing in our tests. The API waits up to a minute for the reading, then answers 202: call again a minute later.

ACE Music v1.1 follows a song’s melody from its score. A cover or mashup on POST /music reads the score of an ACE Music v1 song that has none by itself, for free. An ACE-Step song is not read automatically: when a cover or mashup of it fails with ref_no_melody, call this endpoint on the song first (1 credit), then send the request again. On a paid plan the same score downloads as MusicXML with GET /music/download and format=musicxml.

https://api.useapi.net/v1/acemusic/music/score?songId=songId

Request Headers
Authorization: Bearer {API token}
Query Parameters
  • songId is required, a finished song’s songId (user:<id>-<email>-song:so_…), URL-encoded.
Responses
  • 200 OK

    {
      "songId": "user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7",
      "abc": "X:1\nT:\nM:4/4\nL:1/16\nQ:1/4=142\nV: Vocal clef=treble name=\"Vocal Melody\" snm=\"Vocal\"\nV: Ins clef=treble name=\"Ins Melody\" snm=\"Inst.\"\nK:G\n% intro\nV: Vocal\nz8\"G\"z8|\"G\"z16|\"G\"z16|\"G\"z16|\nV: Ins\nZ|z2GABGDGcGDBGGAG|BGGAGGBGcGGBGGAG|g3a3b2c'3b3g2|\n% verse\nV: Vocal\n\"G\"b8z2a2b2c'2|\"C\"c'8e6d2|\"G\"d16|\"G\"z8g4a4|\n…",
      "musicxml": "GET /music/download?songId=user%3A1234-example%40example.com-song%3Aso_4e7b2c9d0a5f4183b6d8e2c7&format=musicxml (paid plans)"
    }
    
  • 202 Accepted

    ACE Music is still reading the score. Call again in a minute.

    {
      "songId": "user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7",
      "status": "processing",
      "message": "ACE Music is still reading the score: call again in a minute"
    }
    
  • 400 Bad Request

    {
      "error": "Parameter songId is required",
      "code": 400
    }
    
  • 401 Unauthorized

    Invalid API token.

    {
      "error": "useapi.net ⁝ Unauthorized",
      "code": 401
    }
    
  • 404 Not Found

    The song was deleted, or its account is not connected.

  • 409 Conflict

    The song is not finished, or it failed.

  • 412 Precondition Failed

    The account has no credit left to read an ACE-Step song’s score.

  • 422 Unprocessable Entity

    {
      "error": "ACE Music could not read a score from song user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7",
      "code": 422
    }
    
  • 502 Bad Gateway

    ACE Music may have started reading the score, and charged its credit, but its answer was lost or unexpected. Call again: a score already read costs nothing.

  • 503 Service Unavailable

    ACE Music is busy, could not be reached before the score read was sent, or the session is being renewed. Nothing was charged: retry after the Retry-After header.

  • 504 Gateway Timeout

    ACE Music did not answer within 30 seconds after the score read was sent: it may have started it and charged its credit. Call again: a score already read costs nothing.

    {
      "error": "Reading the score: ACE Music did not answer within 30 s. ACE Music 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 account. Add it again with the current password, see Setup ACE Music.

Model

The song’s score in ABC notation, or a 202 answer while ACE Music is still reading it.

The score, field by field
{ // TypeScript, all fields are optional
  songId: string                 // the song you asked for
  abc?: string                   // the score in ABC notation: header, a Vocal and an Ins voice, chords in quotes, % sections
  musicxml?: string              // how to get the same score as MusicXML (paid plans)
  status?: 'processing'          // only on 202: ACE Music is still reading the score
  message?: string               // only on 202: the score is still being read, call again in a minute
}
Examples
  • SONGID="user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"
    curl -H "Authorization: Bearer …" \
         "https://api.useapi.net/v1/acemusic/music/score?songId=$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$SONGID")"
    
  • const token = "API token";
    const songId = "user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7";
    const response = await fetch(`https://api.useapi.net/v1/acemusic/music/score?${new URLSearchParams({ songId })}`, {
      headers: { "Authorization": `Bearer ${token}` }
    });
    const result = await response.json();
    console.log(response.status, result.abc ?? result.message);
    
  • import requests
    
    token = "API token"
    songId = "user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"
    response = requests.get("https://api.useapi.net/v1/acemusic/music/score", headers={"Authorization": f"Bearer {token}"}, params={"songId": songId})
    result = response.json()
    print(response.status_code, result.get("abc") or result)
    
Try It