Retrieve a song

November 14, 2026

Table of contents

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

Read one song from the ACE Music Library of the account that holds it: its status, title, style, lyrics, length, model, mp3 and cover links, and the stems of any split made of it, with each track as a signed link valid for 24 hours. Find songIds in a finished job, in GET /music or in the answer of POST /files.

The mp3 link of a generated song is public. 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. Each read gives a fresh one. An uploaded audio file has no public audioUrl: its playUrl is a direct link to your upload, signed for 24 hours (also from GET /music/download). For WAV, MIDI or MusicXML use the same endpoint.

https://api.useapi.net/v1/acemusic/music/songId

  • songId is URL-encoded in the path (it contains : and @), for example user%3A1234-example%40example.com-song%3Aso_3f9c2a7d81e64b05a9d2c4e7.
Request Headers 
Authorization: Bearer {API token}
Responses

  • 200 OK

    {
  "songId": "user:[email protected]:so_3f9c2a7d81e64b05a9d2c4e7",
  "taskId": "so_3f9c2a7d81e64b05a9d2c4e7",
  "status": "succeeded",
  "title": "Farmers Market Sunshine",
  "model": "ace-step-1.5-xl",
  "style": "Upbeat indie folk, bright cheerful acoustic ukulele strumming, light hand percussion, shaker, warm upright bass, sweet breezy female vocals, sunny acoustic production.",
  "lyrics": "[verse 1]\nWoven tote bag swinging by my side\nMorning breeze and the sky open wide\n…",
  "instrumental": false,
  "duration": 135.02,
  "audioUrl": "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",
  "coverUrl": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7-cover.jpg?v=1794685678498",
  "pageUrl": "https://acemusic.ai/song/k4m8q2vz7xpd",
  "created": "2026-11-14T20:15:30.439Z",
  "finished": "2026-11-14T20:16:14.205Z",
  "kind": "original",
  "score": false,
  "stems": {
    "vocals": {
      "status": "done",
      "tracks": [
        {
          "type": "vocal",
          "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/stem/202611/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…",
          "duration": 135.02
        },
        {
          "type": "instrumental",
          "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/stem/202611/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…",
          "duration": 135.02
        }
      ]
    }
  }
}

  • 400 Bad Request

    {
  "error": "Path parameter songId (not-a-song) is not a valid songId (user:<id>-<email>-song:so_…)",
  "code": 400
}

  • 401 Unauthorized

    Invalid API token.

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

  • 403 Forbidden

    {
  "error": "Song user:[email protected]:so_6b2e8d4a9c1f47e3a0d5b7c2 is not yours",
  "code": 403
}

  • 404 Not Found

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

    {
  "error": "Song user:[email protected]:so_3f9c2a7d81e64b05a9d2c4e7 not found (deleted on acemusic.ai?)",
  "code": 404
}
Model 
{ // 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 
  • SONGID="user:[email protected]:so_3f9c2a7d81e64b05a9d2c4e7"
curl -H "Authorization: Bearer …" \
     "https://api.useapi.net/v1/acemusic/music/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$SONGID")"

  • const token = "API token";
const songId = "user:[email protected]:so_3f9c2a7d81e64b05a9d2c4e7";
const response = await fetch(`https://api.useapi.net/v1/acemusic/music/${encodeURIComponent(songId)}`, {
  headers: { "Authorization": `Bearer ${token}` }
});
console.log(response.status, await response.json());

  • import requests
from urllib.parse import quote

token = "API token"
songId = "user:[email protected]:so_3f9c2a7d81e64b05a9d2c4e7"
response = requests.get(f"https://api.useapi.net/v1/acemusic/music/{quote(songId, safe='')}",
                        headers={"Authorization": f"Bearer {token}"})
print(response.status_code, response.json())
Try It

A finished song plays above the JSON.