Generate songs

November 14, 2026 (November 16, 2026)

Table of contents

  1. Request Headers
  2. Request Body
  3. Options
  4. Responses
  5. Model
  6. Examples
  7. Try It

Make two songs with ACE Music in one request, with vocals or instrumental, on ACE Music v1, ACE Music v1.1 Preview or the free ACE-Step v1.5 XL. Each song comes back with a public mp3 link, cover art, its title, style and lyrics, and a songId you can cover, remix, edit, mash up, split into stems, download as WAV, MIDI or MusicXML, or read as a score.

Two ways to make songs

The fields you send pick the way, as on the ACE Music website:

Way Send What ACE Music does
Idea prompt, and optionally up to 3 references and up to 3 images Writes the style, lyrics and title from your idea, then makes the songs
Your own texts style and lyrics (or instrumental: true), with an optional title, mode and the options Sings your lyrics in your style, or covers, remixes, edits or mashes up songs

A request with any of mode, style, lyrics, title, instrumental, referenceAudio or an option takes the second way. Never send prompt together with them: the API answers 400 and names what to drop. To have ACE Music write lyrics you can still edit, use POST /music/lyrics and POST /music/style first.

Modes

mode applies to the second way. A reference is a songId: a song made by the API, one from GET /music, or your own audio uploaded with POST /files.

mode references Runs on What it does
generate (default) none any model New songs from style (required) and your lyrics. No lyrics makes an instrumental
cover 1 song acemusic-v1.1, or ACE-Step on ace-step-1.5-xl The song in a new style, following its melody, chords and structure
remix 1 song ace-step-1.5-xl only, the default for this mode ACE-Step’s remix: coverStrength keeps the original, remixStrength moves away from it
edit 1 song ace-step-1.5-xl only, the default for this mode Rewrites the part between start and end seconds, with new lyrics for that part
mashup 2 or 3 songs acemusic-v1.1 One new song from several. Without lyrics, ACE Music combines the songs’ own words

instrumental: true works only with mode generate. A cover, remix, edit or mashup keeps the words of the songs it is made from, so other modes answer 400 to it.

ACE Music v1.1 follows a song by the melody it reads from the song’s score. A cover or mashup of an ACE Music v1 song reads its score first when it has none (free for ACE Music v1 songs, a few seconds). ACE-Step songs are not read automatically: if ACE Music answers ref_no_melody, call GET /music/score on the song first (1 credit), then try again.

Model switching

model is the model you ask for. As on the ACE Music website, a request that must read a song runs on ACE Music v1.1 Preview, the model that reads: a mashup, a cover asked on acemusic-v1, and a prompt with more than one reference on ace-step-1.5-xl. ACE Music can also switch a request itself, for example a prompt with a reference song on acemusic-v1, to keep its tune. The job reports both: model (asked) and modelUsed (ran). The credits and the text limits follow the model that runs, so a switched ACE-Step request costs 4 credits.

Cost

ACE Music charges per request when it accepts it: 4 credits on acemusic-v1 and acemusic-v1.1 (two songs, 2 credits a song) and nothing on ace-step-1.5-xl, which runs even on an account with 0 credits. An account with too few credits answers 412 with the cost. A song ACE Music could not make shows refunded: true when ACE Music gave its credits back. See Pricing.

Sync, async and webhooks

  • Every request runs as a job. Sync (the default): the POST waits and answers 200 with the finished job record, or with the job’s error code and the record. In our tests an ACE-Step request took 20 to 95 seconds, ACE Music v1.1 Preview about 35 to 75 seconds, ACE Music v1 about 80 to 105 seconds and a stem split about 90 seconds. If the job is still running after 100 seconds, the POST answers 202 with the job as it stands: fetch the result with GET /jobs/jobid. Always check status: only completed carries the links.
  • Async: pass async: true. The POST answers 201 at once with the job in status: "processing". Poll GET /jobs/jobid or wait for the webhook.
  • replyUrl receives one POST of the final job record, as JSON, when the job completes or fails, for sync and async requests alike. Without replyUrl, the default replyUrl of your useapi.net account is used, see POST account, when it passes the same checks as a request’s: a public https URL.
  • A job that has not finished 30 minutes after it started fails with 504. ACE Music may still finish it and has likely charged for it, so look for its songs with GET /music before you run it again.
  • Each account runs at most maxJobs requests at a time (default 4, which is ACE Music’s own limit, range 1 to 4, set with POST /accounts). GET /jobs shows what is running. A job can be read for 7 days.

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

Request Headers
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
Request Body

From an idea:

{
  "prompt": "A short cheerful ukulele tune about a sunny Saturday morning at the farmers market",
  "model": "ace-step-1.5-xl"
}

From your own style and lyrics:

{
  "style": "synthwave, retro drum machine, warm analog pads, male vocals",
  "lyrics": "[Verse]\nMorning light on the window pane\nCoffee steam and a quiet lane\n[Chorus]\nHold on, hold on, the day is new\nEvery road leads back to you",
  "title": "Neon Morning",
  "model": "acemusic-v1",
  "duration": 120,
  "async": true,
  "replyUrl": "https://your-domain.com/webhook",
  "replyRef": "neon-morning-1"
}

A cover of one of your songs:

{
  "mode": "cover",
  "references": ["user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7"],
  "style": "acoustic folk, fingerpicked guitar, soft female vocals"
}

Idea:

  • prompt is required for an idea, unless references or images are given: the song in your own words. ACE Music writes the style, lyrics and title.
    Maximum length: 2000 characters.
  • images is optional, up to 3 image ids from POST /files (user:<id>-<email>-media:cx_…), pictures the songs are about. With prompt only.

Your own texts:

  • mode is optional, see Modes.
    Supported values: generate (default), cover, remix, edit, mashup.
  • style is required for mode generate: genre, instruments, mood, tempo and vocals.
    Maximum length: 1000 characters, 512 on ace-step-1.5-xl.
  • lyrics is optional, your lyrics with [verse] / [chorus] section tags. In mode generate, no lyrics makes an instrumental. In edit, the words for the part you rewrite.
    Maximum length: 5000 characters, 2000 on ace-step-1.5-xl.
  • instrumental is optional, true for songs with no vocals, with mode generate only. Not together with lyrics.
  • title is optional, the songs’ title.
    Maximum length: 80 characters.
  • The options below.

Both ways:

  • model is optional, the model to ask for, see Model switching.
    Supported values: acemusic-v1 (default), acemusic-v1.1, ace-step-1.5-xl (the default for remix and edit).
  • references is optional, an array of songIds (user:<id>-<email>-song:so_…) from a finished job, GET /music or POST /files. With prompt, up to 3 songs that guide the new ones. With a mode, as many as the Modes table says. Each id once.
  • email is optional, the account to run on. When omitted, the account that holds the references and images runs the request, or, with none, a healthy account with a free maxJobs slot. Every song and image of one request must be on the same account.
  • async is optional, true to answer 201 at once and run the job in the background. Default: false.
  • replyUrl is optional, a public https URL that receives one POST of the job record when the job completes or fails. It works with sync and async requests.
    Callback body has the same JSON shape as GET /jobs/jobid response.
    Maximum length: 2048 characters.
  • replyRef is optional, your own reference echoed back in the job record.
    Maximum length: 1024 characters.

Any other parameter returns 400 Parameter <name> not supported.

Options

Each option works only where the table says, checked against the model that runs. Anywhere else the API answers 400 Parameter <name> does not apply to mode <mode> on <model>.

Option Values Where
duration Song length in seconds: 30 to 600 on acemusic-v1, 10 to 240 on ace-step-1.5-xl. Default: the model decides generate on acemusic-v1 or ace-step-1.5-xl
negative Styles to avoid, up to 200 characters generate on acemusic-v1 or ace-step-1.5-xl
styleInfluence 0 to 100, default 80: how strictly your style is followed, as written when high, freely when low acemusic-v1, acemusic-v1.1
audioInfluence 0 to 100, default 60: how closely the reference is followed, its chords, sections, tempo, key and sound acemusic-v1.1 with references (cover, mashup)
bpm 30 to 200 generate on ace-step-1.5-xl
timeSignature 2/4, 3/4, 4/4, 6/8 generate on ace-step-1.5-xl
thinking 0 to 100: ACE-Step plans the whole song first, creative when low, steady when high generate on ace-step-1.5-xl
key C major, C minor, C# major … B minor: C, C#, D, Eb, E, F, F#, G, Ab, A, Bb and B, each major or minor generate, cover, remix on ace-step-1.5-xl
coverStrength 0 to 100, default 20: how much of the original stays cover, remix on ace-step-1.5-xl
remixStrength 0 to 100, default 0: how far it moves away from the original cover, remix on ace-step-1.5-xl
start, end Seconds, 0 to 600, end at least 1 second after start. Required for edit edit
referenceAudio A songId whose sound guides the result any mode on ace-step-1.5-xl
Responses
  • 200 OK

    Sync mode, the job has finished. It is completed when at least one of its two songs succeeded, here both: a song that failed carries its own error. Each audioUrl is a public mp3 link. 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. For about a minute after a song is made ACE Music serves it at audioUrl itself, so the answer that comes right then, as here, has playUrl equal to audioUrl with a one-minute playUrlExpires: read the job or the song again later for a fresh link.

    {
      "jobid": "j1114201530412583907m-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot:acemusic",
      "type": "music",
      "status": "completed",
      "email": "example@example.com",
      "created": "2026-11-14T20:15:30.412Z",
      "model": "ace-step-1.5-xl",
      "modelUsed": "ace-step-1.5-xl",
      "songs": [
        {
          "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…\n\n[chorus]\nOh it's Saturday morning down at the square\n…",
          "instrumental": false,
          "duration": 135.02,
          "audioUrl": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3",
          "playUrl": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3",
          "playUrlExpires": "2026-11-14T20:17:20.318Z",
          "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
        },
        {
          "songId": "user:1234-example@example.com-song:so_b6e14d0c9a7f4382be51f0a3",
          "taskId": "so_b6e14d0c9a7f4382be51f0a3",
          "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…\n\n[chorus]\nOh it's Saturday morning down at the square\n…",
          "instrumental": false,
          "duration": 135.02,
          "audioUrl": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3.mp3",
          "playUrl": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3.mp3",
          "playUrlExpires": "2026-11-14T20:17:20.318Z",
          "coverUrl": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3-cover.jpg?v=1794685679611",
          "pageUrl": "https://acemusic.ai/song/w7n3c5r9t2hb",
          "created": "2026-11-14T20:15:30.440Z",
          "finished": "2026-11-14T20:16:14.205Z",
          "kind": "original",
          "score": false
        }
      ],
      "completed": "2026-11-14T20:16:14.205Z",
      "job_state": "completed",
      "outputs": [
        {
          "ok": true,
          "url": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3",
          "url_auth": "none",
          "mime": "audio/mpeg",
          "expires_at": null,
          "ref": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7",
          "thumbnail_url": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7-cover.jpg?v=1794685678498"
        },
        {
          "ok": true,
          "url": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3.mp3",
          "url_auth": "none",
          "mime": "audio/mpeg",
          "expires_at": null,
          "ref": "user:1234-example@example.com-song:so_b6e14d0c9a7f4382be51f0a3",
          "thumbnail_url": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3-cover.jpg?v=1794685679611"
        }
      ]
    }
    
  • 201 Created

    async: true, the job is running, here an idea on acemusic-v1. While ACE Music writes the lyrics, the songs are planning and Untitled. Poll GET /jobs/jobid or wait for the webhook.

    {
      "jobid": "j1114202212045711826m-u1234-email:example@example.com-task:so_8c1d4f7a2b9e4c06a3f5d7e1.so_e2a7b9c4d6f84a1b95c3e0d8-bot:acemusic",
      "type": "music",
      "status": "processing",
      "email": "example@example.com",
      "created": "2026-11-14T20:22:12.045Z",
      "model": "acemusic-v1",
      "modelUsed": "acemusic-v1",
      "songs": [
        {
          "songId": "user:1234-example@example.com-song:so_8c1d4f7a2b9e4c06a3f5d7e1",
          "taskId": "so_8c1d4f7a2b9e4c06a3f5d7e1",
          "status": "planning",
          "title": "Untitled",
          "model": "acemusic-v1",
          "style": null,
          "lyrics": null,
          "instrumental": false,
          "duration": null,
          "audioUrl": null,
          "playUrl": null,
          "playUrlExpires": null,
          "coverUrl": null,
          "pageUrl": null,
          "created": "2026-11-14T20:22:12.068Z",
          "finished": null,
          "kind": "original",
          "score": false
        },
        {
          "songId": "user:1234-example@example.com-song:so_e2a7b9c4d6f84a1b95c3e0d8",
          "taskId": "so_e2a7b9c4d6f84a1b95c3e0d8",
          "status": "planning",
          "title": "Untitled",
          "model": "acemusic-v1",
          "style": null,
          "lyrics": null,
          "instrumental": false,
          "duration": null,
          "audioUrl": null,
          "playUrl": null,
          "playUrlExpires": null,
          "coverUrl": null,
          "pageUrl": null,
          "created": "2026-11-14T20:22:12.069Z",
          "finished": null,
          "kind": "original",
          "score": false
        }
      ],
      "replyUrl": "https://your-domain.com/webhook",
      "replyRef": "lofi-1",
      "job_state": "in_progress",
      "outputs": [
        {
          "ok": false,
          "url": null,
          "url_auth": "none",
          "mime": "audio/mpeg",
          "expires_at": null,
          "ref": "user:1234-example@example.com-song:so_8c1d4f7a2b9e4c06a3f5d7e1",
          "thumbnail_url": null
        },
        {
          "ok": false,
          "url": null,
          "url_auth": "none",
          "mime": "audio/mpeg",
          "expires_at": null,
          "ref": "user:1234-example@example.com-song:so_e2a7b9c4d6f84a1b95c3e0d8",
          "thumbnail_url": null
        }
      ]
    }
    
  • 202 Accepted

    Sync mode, the songs were still being made after 100 seconds. The body is the job as it stands, the same shape as 201, with status: "processing". Fetch the result with GET /jobs/jobid or wait for the webhook.

  • 400 Bad Request

    A parameter is missing or invalid, the parameters mix the two ways, or ACE Music refused the request. A few of the answers:

    {
      "error": "Send prompt or lyrics, not both: drop lyrics to have ACE Music write the song from your prompt, or drop prompt to sing your own lyrics (with style)",
      "code": 400
    }
    
    {
      "error": "mode mashup takes 2 to 3 songs in references",
      "code": 400
    }
    
    {
      "error": "Parameter bpm does not apply to mode generate on acemusic-v1",
      "code": 400
    }
    
    {
      "error": "Song user:1234-example2@example.com-song:so_5a0e3c8b1d7f4e92a6c4b8d0 is on account example2@example.com, not example@example.com: songs and images only work on the account that holds them",
      "code": 400
    }
    
    {
      "error": "Please add at least one ACE Music account first: https://useapi.net/docs/api-acemusic-v1/post-acemusic-accounts",
      "code": 400
    }
    

    Sync mode, ACE Music could not read the melody of a referenced song (ref_no_melody), usually an ACE-Step song with no score yet. Read its score with GET /music/score, then send the request again. The body is the failed job record, and the credits came back (refunded: true):

    {
      "jobid": "j1114200257596846480m-u1234-email:example@example.com-task:so_9a4f1c7e3b2d4a8c96e0b5d2.so_0c6b8e2a4f1d4b7a83e9c5f1-bot:acemusic",
      "type": "music",
      "status": "failed",
      "email": "example@example.com",
      "created": "2026-11-14T20:02:57.596Z",
      "model": "ace-step-1.5-xl",
      "modelUsed": "acemusic-v1.1",
      "songs": [
        {
          "songId": "user:1234-example@example.com-song:so_9a4f1c7e3b2d4a8c96e0b5d2",
          "taskId": "so_9a4f1c7e3b2d4a8c96e0b5d2",
          "status": "failed",
          "title": "Untitled",
          "model": "acemusic-v1.1",
          "style": "upbeat pop mashup, bright synths",
          "lyrics": null,
          "instrumental": false,
          "duration": null,
          "audioUrl": null,
          "playUrl": null,
          "playUrlExpires": null,
          "coverUrl": null,
          "pageUrl": null,
          "created": "2026-11-14T20:02:57.619Z",
          "finished": null,
          "kind": "mashup",
          "score": false,
          "error": {
            "code": "ref_no_melody",
            "message": "No melody could be found in the reference"
          },
          "refunded": true
        },
        {
          "songId": "user:1234-example@example.com-song:so_0c6b8e2a4f1d4b7a83e9c5f1",
          "taskId": "so_0c6b8e2a4f1d4b7a83e9c5f1",
          "status": "failed",
          "title": "Untitled",
          "model": "acemusic-v1.1",
          "style": "upbeat pop mashup, bright synths",
          "lyrics": null,
          "instrumental": false,
          "duration": null,
          "audioUrl": null,
          "playUrl": null,
          "playUrlExpires": null,
          "coverUrl": null,
          "pageUrl": null,
          "created": "2026-11-14T20:02:57.620Z",
          "finished": null,
          "kind": "mashup",
          "score": false,
          "error": {
            "code": "ref_no_melody",
            "message": "No melody could be found in the reference"
          },
          "refunded": true
        }
      ],
      "completed": "2026-11-14T20:03:46.414Z",
      "code": 400,
      "error": "ACE Music could not read the melody of the referenced song (ref_no_melody): read its score first with GET /music/score, then try again. ACE Music refunded the credits",
      "job_state": "failed",
      "outputs": [
        {
          "ok": false,
          "url": null,
          "url_auth": "none",
          "mime": "audio/mpeg",
          "expires_at": null,
          "ref": "user:1234-example@example.com-song:so_9a4f1c7e3b2d4a8c96e0b5d2",
          "thumbnail_url": null
        },
        {
          "ok": false,
          "url": null,
          "url_auth": "none",
          "mime": "audio/mpeg",
          "expires_at": null,
          "ref": "user:1234-example@example.com-song:so_0c6b8e2a4f1d4b7a83e9c5f1",
          "thumbnail_url": null
        }
      ],
      "error_info": {
        "code": "input_rejected",
        "message": "ACE Music could not read the melody of the referenced song (ref_no_melody): read its score first with GET /music/score, then try again. ACE Music refunded the credits",
        "retry": {
          "mode": "never",
          "action": "replace_input"
        },
        "vendor_code": "ref_no_melody"
      }
    }
    
  • 401 Unauthorized

    Invalid API token.

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

    A songId or image id belongs to another useapi.net user.

    {
      "error": "Song user:5678-someone@example.com-song:so_c155273ac66b4f2fa0c0dad1 is not yours",
      "code": 403
    }
    
  • 404 Not Found

    {
      "error": "Account example@example.com is not configured",
      "code": 404
    }
    
  • 412 Precondition Failed

    The account has too few credits for acemusic-v1 or acemusic-v1.1. cost is what the request needs. Without email, the API first tries your other accounts. ace-step-1.5-xl needs no credits.

    {
      "error": "Generating the songs: Not enough credits — a generation costs 4.",
      "code": 412,
      "cost": 4
    }
    
  • 422 Unprocessable Entity

    Sync mode, ACE Music could not make either song. The body is the failed job record, the same shape as the ref_no_melody example under 400, with code: 422, ACE Music’s reason and code in error and each song’s own error. A song shows refunded: true when ACE Music gave its credits back.

  • 429 Too Many Requests

    The account named by email, or the account that holds the references, is running its maxJobs. Without them, every account is. ACE Music can answer 429 itself while songs of the account are still being made. Retry after the Retry-After header (30 seconds).

    {
      "error": "Account example@example.com is running 4 of 4 jobs (maxJobs). Wait for one to finish, or raise maxJobs with POST /accounts",
      "code": 429
    }
    
    {
      "error": "All 3 usable ACE Music accounts are running their maximum number of jobs (maxJobs), please retry shortly",
      "code": 429
    }
    
  • 502 Bad Gateway

    ACE Music may have accepted the request, and charged for it, but its answer was lost, or it answered with something unexpected after accepting it. Check GET /music before you send it again: the songs may be there.

  • 503 Service Unavailable

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

    When ACE Music may have accepted the request but its answer was lost, the API answers 502 (or 504 on a timeout) instead, saying it may already have charged: check GET /music before you send it again.

  • 504 Gateway Timeout

    ACE Music did not answer within 30 seconds after the request was sent: it may have accepted it and charged for it. Check GET /music before you send it again.

    {
      "error": "Generating the songs: ACE Music did not answer within 30 s. It 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.

    {
      "error": "Account example@example.com: ACE Music refused the stored email and password. Update the password with POST /accounts to resume using this account",
      "code": 596
    }
    
Model

The job record. GET /jobs/jobid and the replyUrl webhook return the same shape. A failed sync job answers with the HTTP status in code and the failed record as the body.

The job record, field by field, and the types it uses (Song, Output, ErrorInfo)
{ // TypeScript, all fields are optional
  jobid: string                  // the job's id, `j…-u<id>-email:<email>-task:…-bot:acemusic`. It names the account and
                                 // the song or songs the job is about. Read the job with GET /jobs/{jobid}
  type: 'music' | 'stems'        // music: POST /music. stems: POST /music/stems
  status: 'processing' | 'completed' | 'failed'   // processing: ACE Music is making the songs or the split (every job
                                 // starts here). completed: done, a song job once at least one of its two songs succeeded.
                                 // failed: done without a result, error says why and code is the HTTP status
  email: string                  // the ACE Music account the job runs on
  created: string                // ISO 8601
  completed?: string             // ISO 8601, when the job completed or failed
  model?: string                 // music: the model you asked for
  modelUsed?: string             // music: the model that made the songs. It differs from model when the request ran on
                                 // another one: a request that must read a song (a mashup, a cover asked on acemusic-v1, a
                                 // prompt with more than one reference on ace-step-1.5-xl) runs on acemusic-v1.1, and ACE
                                 // Music can also switch a request itself
  songs?: (Song | DeletedSong)[] // music: the request's two songs, see Song below. A song deleted since, with
                                 // DELETE /music/{songId} or on acemusic.ai, is a DeletedSong
  stems?: {                      // on a stems job: the split
    mode: 'vocals' | 'all'       // the split you asked for
    songId: string               // the song that was split
    songStatus?: 'deleted'       // the song was deleted, its stems went with it (the job failed with code 404)
    tracks: {                    // one per stem
      type: string               // vocals: vocal, instrumental. all: vocals, `backing_vocals`, drums, bass, guitar,
                                 // keyboard, strings, synth, woodwinds, fx (the stems ACE Music found)
      url: string | null         // signed mp3 link, valid 24 hours
      duration?: number          // seconds
    }[]
    expires?: string             // ISO 8601, when the track links stop working (read the job again for fresh ones)
  }
  error?: string                 // status 'failed': why
  code?: number                  // status failed: the HTTP status of the failure. 400: ACE Music could not read a
                                 // referenced song's melody (read its score with GET /music/score, then run it again). 404:
                                 // the account was removed, or a split's song was deleted. 422: ACE Music could not make
                                 // the songs or the split. 504: not finished within 30 minutes (ACE Music may still finish
                                 // it). 596: the account was signed out
  replyUrl?: string               // the replyUrl you sent: it receives this record when the job ends
  replyRef?: string               // the replyRef you sent, echoed back
  job_state: 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled' | 'expired' | 'unknown'
                                 // where the job is, in the same words for every useapi.net API
  outputs: Output[]              // one entry per file the job made, see Output below
  error_info?: ErrorInfo         // only on a failed job: why, and whether to retry, see ErrorInfo below
}

Song: each item of songs in the job record above.

{ // 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
  }[]
}

DeletedSong: an item of songs whose song was deleted since, with DELETE /music/{songId} or on acemusic.ai.

{ // TypeScript
  songId: string                 // the song's id, as it was
  taskId: string                 // ACE Music's own id of the song (so_…)
  status: 'deleted'              // deleted with DELETE /music/{songId} or on acemusic.ai
}

Output: each item of outputs in the job record above.

{ // TypeScript
  ok: boolean                    // true when this file is ready to use
  url: string | null             // the link to the file, always absolute
  url_auth: 'none' | 'bearer'    // none: open the link as it is. bearer: send your API token with it
  mime: string                   // the file type, e.g. audio/mpeg
  expires_at: string | null      // ISO 8601, when the link stops working. null when it does not expire
  ref: string | null             // the id to use for this file in later calls
  thumbnail_url?: string | null  // a cover or preview image
  text?: string                  // the text, when the output is text
}

ErrorInfo: the error_info of a failed job above.

{ // TypeScript
  code: string                   // the kind of failure, in the same words for every useapi.net API, e.g. `timeout`,
                                 // `generation_failed`, `input_rejected`, `not_found`, `account_unhealthy`
  message: string                // what went wrong, in the API's own words
  retry: {                       // whether and when to send it again
    mode: 'never' | 'now' | 'backoff' | 'after' | 'after_reset' | 'other_account'
                                 // never: do not send it again as it is (see action). now: send it again right
                                 // away. backoff: send it again later, waiting longer each time. after: send it again
                                 // once the wait in seconds has passed. after_reset: send it again once the account's credits or
                                 // usage limit reset. other_account: send it on another account
    seconds?: number             // mode after: wait this long (or the Retry-After header)
    max?: number                 // retry at most this many times
    action?: string              // what to change first, e.g. `fix_body`, `replace_input`, `add_credits`, `upgrade_plan`
  }
  vendor_code?: string           // the code the vendor answered with
}
Examples
  • curl -X POST "https://api.useapi.net/v1/acemusic/music" \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer …" \
       -d '{
         "prompt": "A short cheerful ukulele tune about a sunny Saturday morning at the farmers market",
         "model": "ace-step-1.5-xl"
       }'
    
  • const token = "API token";
    const apiUrl = "https://api.useapi.net/v1/acemusic";
    const headers = { "Content-Type": "application/json", "Authorization": `Bearer ${token}` };
    
    const response = await fetch(`${apiUrl}/music`, {
      method: "POST",
      headers,
      body: JSON.stringify({
        style: "synthwave, retro drum machine, warm analog pads, male vocals",
        lyrics: "[Verse]\nMorning light on the window pane\n[Chorus]\nHold on, the day is new",
        model: "acemusic-v1",
        async: true
      })
    });
    let job = await response.json();
    console.log("submitted", response.status, job.jobid);
    
    while (job.status === "processing") {
      await new Promise(r => setTimeout(r, 10000));
      job = await (await fetch(`${apiUrl}/jobs/${encodeURIComponent(job.jobid)}`, { headers })).json();
      console.log(job.status);
    }
    if (job.status === "completed")
      job.songs.forEach(song => console.log(song.title, 'store:', song.audioUrl, 'play:', song.playUrl));
    else
      console.log("error", job.code, job.error);
    
  • import time
    import requests
    from urllib.parse import quote
    
    token = "API token"
    apiUrl = "https://api.useapi.net/v1/acemusic"
    headers = {"Content-Type": "application/json", "Authorization": f"Bearer {token}"}
    
    data = {
        "style": "synthwave, retro drum machine, warm analog pads, male vocals",
        "lyrics": "[Verse]\nMorning light on the window pane\n[Chorus]\nHold on, the day is new",
        "model": "acemusic-v1",
        "async": True
    }
    job = requests.post(f"{apiUrl}/music", headers=headers, json=data).json()
    print("submitted", job.get("jobid"))
    
    while job.get("status") == "processing":
        time.sleep(10)
        job = requests.get(f"{apiUrl}/jobs/{quote(job['jobid'], safe='')}", headers=headers).json()
        print(job.get("status"))
    
    if job.get("status") == "completed":
        for song in job["songs"]:
            print(song["title"], "store:", song["audioUrl"], "play:", song.get("playUrl"))
    else:
        print("error", job.get("code"), job.get("error"))
    
Try It

Leave a field empty to leave it out. references and images take ids separated by commas. The songs play above the JSON once the job is completed.