Retrieve a song

November 14, 2026 (November 16, 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:1234-example@example.com-song: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:5678-someone@example.com-song:so_6b2e8d4a9c1f47e3a0d5b7c2 is not yours",
      "code": 403
    }
    
  • 404 Not Found

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

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

The song, with its audio links and the signed links of the stems of any split.

The song, field by field, and the type it uses (Split)
{ // 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
  • SONGID="user:1234-example@example.com-song: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:1234-example@example.com-song: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:1234-example@example.com-song: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.