Retrieve a song
November 14, 2026 (November 16, 2026)
Table of contents
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
songIdis URL-encoded in the path (it contains:and@), for exampleuser%3A1234-example%40example.com-song%3Aso_3f9c2a7d81e64b05a9d2c4e7.
Request Headers
Authorization: Bearer {API token}
API tokenis required, see Setup useapi.net for details.
Responses
-
{ "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 } ] } } } -
{ "error": "Path parameter songId (not-a-song) is not a valid songId (user:<id>-<email>-song:so_…)", "code": 400 } -
Invalid API token.
{ "error": "useapi.net ⁝ Unauthorized", "code": 401 } -
{ "error": "Song user:5678-someone@example.com-song:so_6b2e8d4a9c1f47e3a0d5b7c2 is not yours", "code": 403 } -
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.