Download a song

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 a finished song as MP3, WAV, MIDI or MusicXML.

format Plans What comes back
mp3 (default) every plan JSON with the song’s public mp3 link, the same as its audioUrl, and playUrl, the same mp3 as a direct link for players until playUrlExpires. For a file uploaded with POST /files, its own audio in the format it was uploaded in, as a signed link valid for 24 hours
wav Creator, Artist JSON with a signed link valid for 24 hours. Not for ace-step-1.5-xl songs, which ACE Music makes as MP3 only
midi Creator, Artist The .mid file itself, audio/midi
musicxml Creator, Artist The MusicXML score itself, application/vnd.recordare.musicxml+xml

For mp3, 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.

ACE Music makes WAV, MIDI and MusicXML on the first request for a song. The API waits up to a minute for it, then answers 202: call again a minute later. For the score as ABC notation, use GET /music/score.

https://api.useapi.net/v1/acemusic/music/download?songId=songId&format=format

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

    The file’s link as JSON for mp3 and wav, or the file itself for midi and musicxml. With format: mp3 (the default) on a made song:

    {
      "songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7",
      "format": "mp3",
      "url": "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=20261114T204512Z&X-Amz-Expires=3599&…",
      "playUrlExpires": "2026-11-14T21:45:11.000Z",
      "fileName": "Farmers Market Sunshine.mp3"
    }
    

    wav, and mp3 of an uploaded file:

    {
      "songId": "user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7",
      "format": "wav",
      "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….wav?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…",
      "fileName": "Orchestral Morning.wav",
      "expires": "2026-11-15T20:07:29.242Z"
    }
    

    midi and musicxml answer with the file itself, with Content-Disposition: attachment; filename="<title>.mid" (or .musicxml).

  • 202 Accepted

    ACE Music is still making the file. Call again in a minute.

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

    {
      "error": "ace-step-1.5-xl songs are made lossy: no WAV (use mp3)",
      "code": 400
    }
    
    {
      "error": "Parameter format (flac) valid values: mp3,wav,midi,musicxml",
      "code": 400
    }
    
  • 401 Unauthorized

    Invalid API token.

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

    WAV, MIDI and MusicXML need a paid ACE Music plan, or the song belongs to another useapi.net user.

    {
      "error": "Downloading the wav needs a paid ACE Music plan (the account is on free): Downloads come with a paid plan",
      "code": 403
    }
    
  • 404 Not Found

    {
      "error": "Song user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7 not found (deleted on acemusic.ai?)",
      "code": 404
    }
    
  • 409 Conflict

    The song is not finished, or it failed.

    {
      "error": "Song user:1234-example@example.com-song:so_8c1d4f7a2b9e4c06a3f5d7e1 is running: nothing to download yet",
      "code": 409
    }
    
  • 503 Service Unavailable

    ACE Music is busy, did not answer in time, could not be reached, answered with a server error, or the session is being renewed. Nothing was charged: retry after the Retry-After header.

    {
      "error": "Downloading the wav: ACE Music did not answer within 30 s, please retry shortly",
      "code": 503
    }
    
Model

A link to the song in the format you asked for, or a 202 answer while ACE Music is still making the file.

The download link, field by field
{ // TypeScript, all fields are optional
  songId: string                 // the song you asked for
  format: 'mp3' | 'wav' | 'midi' | 'musicxml'   // the format you asked for
  url?: string                   // mp3 of a made song: the public link, the same as audioUrl. mp3 of a file uploaded
                                 // with POST /files: its own audio, in the format it was uploaded in, as a signed link.
                                 // wav, and a midi that ACE Music redirects: a signed link. Not on 202
  playUrl?: string | null        // mp3 of a made song: the same mp3 as a direct link for players, valid until
                                 // playUrlExpires (about an hour). null when the link could not be read
  playUrlExpires?: string | null // ISO 8601, when playUrl stops working
  fileName?: string              // the song's title with the file's extension. Not on 202
  expires?: string               // ISO 8601, when a signed link stops working (24 hours)
  status?: 'processing'          // only on 202: ACE Music is still making the file
  message?: string               // only on 202: which file is still being made, and to call again in a minute
}
Examples
  • SONGID="user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7"
    curl -H "Authorization: Bearer …" -o song.mid \
         "https://api.useapi.net/v1/acemusic/music/download?format=midi&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 params = new URLSearchParams({ songId, format: "wav" });
    const response = await fetch(`https://api.useapi.net/v1/acemusic/music/download?${params}`, {
      headers: { "Authorization": `Bearer ${token}` }
    });
    const result = await response.json();
    console.log(response.status, result.url, result.expires);
    
  • import requests
    
    token = "API token"
    params = {"songId": "user:1234-example@example.com-song:so_4e7b2c9d0a5f4183b6d8e2c7", "format": "musicxml"}
    response = requests.get("https://api.useapi.net/v1/acemusic/music/download", headers={"Authorization": f"Bearer {token}"}, params=params)
    if response.status_code == 200 and "json" not in response.headers.get("content-type", ""):
        with open("song.musicxml", "wb") as f:
            f.write(response.content)
    else:
        print(response.status_code, response.json())
    
Try It

An mp3 or wav plays above the JSON. A MIDI file or a MusicXML score comes back as a download link.