Docs
Get an API key
Workflows›Make songs with ACE-Step 1.5

Make songs with ACE-Step 1.5

Make songs and instrumentals with ACE-Step 1.5, have the API write one from a brief, set tempo, key and length, and repaint, cover or extend a song.

View .md

ACE-Step 1.5 makes a song, with vocals or without, from a short style caption and optional lyrics. It renders fast, takes the tempo, key and time signature as settings of its own, and makes the length you ask for to the second. It also works on a song you already have: it can repaint part of it, cover it in another style, or make it longer.

Field What it is Limit
prompt The caption: genre, mood, instruments and voice. Required. 750 characters
lyrics The words to sing, in tagged sections. Leave it out for an instrumental. 4,096 characters
duration The song's length in seconds, exactly. 10 to 600, 120 by default
quality turbo (the default) or hifi.

Everything else is optional: bpm, key and time_signature set the music, seed makes a take repeatable, response_format picks the file type, and write: true has the API write the song from a brief. Its model page has every field and the price.

A song is an async job: you create it, then poll it or get a webhook. It is usually done in seconds, so Prefer: wait on the create request often answers with the finished song.

Make a song

This 30-second song is done in a few seconds on turbo. The Python version asks for hifi.

Create a song and download it
# Create the song and wait up to 60 seconds for it (Prefer: wait); a 30-second turbo song is done in a few seconds, so it answers 200
curl -s https://api.vultrinference.com/v1/music \
  -H "Authorization: Bearer $VULTR_INFERENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{
    "model": "ace-step-1.5",
    "prompt": "Indie folk, warm female alto, fingerpicked acoustic guitar, soft brushed drums, intimate and hopeful",
    "lyrics": "[Verse]\nMorning light on the kitchen floor\nCoffee cups and an open door\n\n[Chorus]\nStay a while, stay a while\nThe day can wait for us",
    "duration": 30,
    "bpm": 96,
    "key": "G major",
    "time_signature": "4/4",
    "seed": 7
  }' | tee song.json | jq '{id, status, usage}'

# Download it once its status is completed
curl -s -o song.mp3 "https://api.vultrinference.com/v1/music/$(jq -r .id song.json)/content" \
  -H "Authorization: Bearer $VULTR_INFERENCE_API_KEY"

Turbo or hifi

quality picks the model the song renders on:

Tier Also accepts Model A 3-minute song renders in Billed
turbo (default) auto, low, fast ACE-Step 1.5 XL turbo, 8 steps about 5 seconds the song's seconds
hifi high, hd ACE-Step 1.5 XL SFT, 50 steps with guidance about 35 seconds 7.5 times the song's seconds

Turbo is quick and cheap enough to try many captions and seeds. Hifi is a different model, so the same request and seed make a different song on it, not a finer render of the turbo take. Any other quality is a 400 that lists the tiers.

The caption

ACE-Step reads the caption as a description of the sound. Name the genre and subgenre, the mood, the main instruments and the voice, in a sentence or a list of tags:

text
Indie folk, warm female alto, fingerpicked acoustic guitar, soft brushed drums, intimate and hopeful

Keep it to the music: the story belongs in the lyrics. The model reads at most about 200 tokens of caption, so the API holds prompt to 750 characters rather than let the end be cut off without a word.

What helps, from ACE-Step's own guide:

  • Be specific and cover several things at once. "Sad piano ballad with a breathy female vocal" steers far more than "a sad song". Genre, mood, instruments, the voice and how it is produced (close-miked, tape warmth, live room) each narrow it further.
  • Describe the sound, not the feeling. Words for what a listener hears (warm, crisp, airy, punchy, lo-fi, polished) shape the mix; "emotional" or "realistic" do little.
  • Don't ask for things that pull against each other. "Classical strings" and "hardcore metal" together usually blur into neither. If you want both, say how the song moves between them: "starts with soft strings, turns into heavy metal in the second half".
  • Leave tempo and key out of the caption. Send them as the fields below; a caption that says "slow ballad" beside bpm: 160 gives the model two answers.
  • Write less for surprises, more for control. A short caption leaves the model room; a detailed one holds it closer.

Tempo, key and time signature

bpm, key and time_signature are fields the model takes directly, not hints written into the caption:

Field Values
bpm 30 to 300
key A note with an optional accidental and scale: C major, F# minor, Eb
time_signature 2/4, 3/4, 4/4 or 6/8

Any other time signature is a 400 that lists these four. Leave a field out and the model chooses.

The lyrics

The lyrics are sections in order, each a tag in square brackets followed by its lines:

text
[Verse]
Morning light on the kitchen floor
Coffee cups and an open door

[Chorus]
Stay a while, stay a while
The day can wait for us

[Bridge]
And if the rain comes in

[Chorus]
Stay a while, stay a while

The tags it knows are [Intro], [Verse], [Pre-Chorus], [Chorus], [Bridge], [Interlude], [Instrumental] and [Outro]. Spacing and case do not matter ([pre chorus] is [Pre-Chorus]), and [Inst] is read as [Instrumental]. Any other tag is passed on as you wrote it. Everything that is not a tag is sung, so keep stage directions and singer names in the caption.

A few things in the lyrics shape the performance:

Write The model
[Chorus - anthemic], [Bridge - whispered] Sings the section that way. One word after the dash is plenty: a long list of them may be sung as words.
[Guitar Solo], [Build], [Drop], [Breakdown], [Fade Out] Plays a section without words, or changes the energy.
A line in CAPITALS Sings it harder, close to shouting.
(words in parentheses) Sings them as backing vocals.
A blank line between sections Keeps sections apart.

Lines of 6 to 10 syllables sing best, because the model fits syllables to the beat: a 14-syllable line after a 6-syllable one gets rushed. Keep lines in the same place in each verse about the same length. And keep the lyrics in step with the caption: a caption about a violin and a [Guitar Solo] tag give the model two different songs.

The model reads about 2,000 tokens of lyrics, which is why lyrics is held to 4,096 characters.

The lyrics' language

language tells the model which language the lyrics are in: en (the default), zh, ja, ko, es, fr, de and 44 more, listed under languages in GET /v1/music/models. yue is Cantonese. A regional tag such as zh-CN or pt-BR is read as its language. Name the language whenever the lyrics are not English. A song without lyrics is sent as unknown.

Instrumentals

Leave lyrics out, or send instrumental: true, for a song with no vocals; the model is sent [Instrumental] as its lyrics, the way ACE-Step's makers write one. instrumental: true with lyrics is a 400.

Describe the lead instrument in the caption, not a voice. In our tests, with no singer named, no take of 16 had a voice; with a caption that named one, 2 of 8 still did.

Let the API write the song

Send write: true with a brief in prompt, what the song is about in your own words, and leave lyrics out. Before the song renders, a writer model (deepseek-v4.1-flash) turns the brief into a short caption with a clear voice, lyrics in verses and choruses whose lines fit the tempo, and the tempo, key and time signature:

JSON
{
  "model": "ace-step-1.5",
  "prompt": "Two old friends sharing a slow rainy morning",
  "write": true,
  "duration": 90
}

The finished job shows what was written under written (prompt, lyrics, bpm, key, time_signature), so you can keep it, change a line and send it again as your own lyrics. A bpm, key or time_signature you send is kept, and the words are fitted to it. In our tests the written songs sang more of their words than songs written by hand for the same briefs.

The writer's tokens are billed at its price, in usage.write and the job's cost. If the brief cannot be made into a song that meets the rules after one retry, the job fails with write_failed and nothing is billed. The writer writes English only for now: another language is a 400. write: true with lyrics or instrumental is a 400, and so is any task but a new song. It works with best_of and timestamps, which then use the written lyrics.

A reference recording

reference_audio gives the model a recording whose voice and tone the song takes up, such as a singer or a mix you like. Send one of:

  • an https URL: the API fetches it when the song renders
  • a base64 data URI: data:audio/mpeg;base64,...
  • a song from one of your own jobs: {"type": "job_output", "job_id": "music_...", "index": 0}, kept for 7 days

It must be 10 to 600 seconds long and at most 50 MB, in wav, mp3, flac, ogg, m4a or aac. A data URI or a job's song is checked when you send the request, and anything wrong is a 400. A URL is checked when the song renders, and if the file breaks these rules the job fails with invalid_request and is not billed.

input_references takes the same audio as a list, each item with "role": "reference"; send a reference once, either way.

Length

duration is the song's exact length: 10 to 600 seconds, 120 by default. Unlike a model whose duration is only a ceiling, ACE-Step fills the time you ask for, so fit the lyrics to it: a few sections for 30 seconds, a full verse-chorus song for three minutes or more.

You pay per second of audio, rounded up, at the tier's price. A 30-second song costs 30 seconds on turbo and 225 on hifi.

Takes and seeds

The same request with the same seed makes the same song on the same tier. Keep a seed you like and change one thing at a time, such as a line of lyrics or the tempo; changing the tier changes the model, and with it the song. ACE-Step makes one song per request (n is 1); for several candidates, send several requests, each billed on its own.

Let the API pick the best take

Every take of the same request comes out a little different, and some sing their lyrics more clearly than others. best_of (2 to 4) has the API render that many takes, from your seed and the seeds after it, and send back the one that sings its lyrics most clearly:

JSON
{
  "model": "ace-step-1.5",
  "prompt": "Indie folk, warm female alto, fingerpicked guitar",
  "lyrics": "[Verse]\nMorning light on the kitchen floor\n...",
  "best_of": 3
}

The API times each take's lyrics with aligner-1 and keeps the take whose lines it placed with the most confidence. In our tests that was the best-sung take in 5 of 6 songs. The song's outputs[0].metadata.candidates lists every take's seed and score, so you can render another one again by its seed.

You pay for every take, and for timing each one's lyrics: best_of: 3 on a 120 s turbo song is 3 × $0.024 for the takes plus about 3 × $0.004 for the timing, in usage.best_of. It takes about three times as long. It needs lyrics in a language aligner-1 reads (English, French, German, Spanish and the others it lists); an instrumental, or lyrics it cannot read, is a 400. With timestamps: true too, the kept take's timing comes at no extra charge.

Getting the song

ACE-Step sends the finished file, not a stream, so its jobs have no stream_url. Poll the job at the pace openai-poll-after-ms asks for, send Prefer: wait=60 on the create request, or set callback_url for a webhook.

GET /v1/music/{id}/content gives the song as mp3 (the default, 256 kbps), wav, flac, opus, aac or raw pcm, at 48 kHz in stereo, the model's native rate. sample_rate asks for another (8 to 48 kHz). It is kept for 7 days.

Work on a song you have

Three tasks take a song as source_audio, in any of the forms a reference takes: an https URL, a base64 data URI, or one of your own jobs' songs ({"type": "job_output", "job_id": "music_...", "index": 0}). It must be 10 to 600 seconds long and at most 50 MB. Each also takes a reference_audio.

task What it does Tiers Length Billed
repaint Makes one part of the song again turbo (default) or hifi the source's the whole song at its tier
cover Plays the song again in the caption's style hifi only the source's the whole song at hifi
extend Makes the song longer turbo (default) or hifi duration, the new total only the seconds added

The model renders the whole song even when it changes only a part of it, which is why a repaint and a cover bill the whole song.

Repaint part of a song

Name the part to make again as regions, one {start, end} in seconds of the source, and send the whole song's caption and lyrics. The rest of the song is kept.

JSON
{
  "model": "ace-step-1.5",
  "task": "repaint",
  "source_audio": {"type": "job_output", "job_id": "music_6f0c...", "index": 0},
  "regions": [{"start": 42, "end": 58}],
  "prompt": "Indie folk, warm female alto, fingerpicked acoustic guitar",
  "lyrics": "[Verse]\n...\n[Chorus]\n..."
}

repainting_start and repainting_end work as well, as one region. A region must end inside the source; leave duration out, since the song keeps the source's length.

Cover a song

A cover follows the source's structure and melody and plays it in the style the caption describes. Send the lyrics it should sing; without any, the model is told the song is an instrumental, as for a new song. cover_strength, 0 to 1 (1 when left out), is how closely it holds to the source: below 1 it blends in a render from the caption alone, so lower values change the style more. It runs on hifi only, so a quality other than hifi (or high, hd) is a 400.

Only cover a song you hold the rights to.

Extend a song

Set duration to the song's new total length, longer than the source and at most 600 seconds, and send the whole song's lyrics, the lines it already sings and the ones to add, in order. The added part sings the lines the source has not yet sung; given only the new lines, it tends to sing nothing.

A finished song ends in a fade or a silence, so the continuation starts about a second before the source's music ends, at most 10 seconds before the end of the file, and that much of the ending is made again. You pay only for the seconds you added: a 30-second song extended to 60 seconds bills 30.

What these refuse

You send You get
duration with repaint or cover 400: the song keeps the source's length
repaint without regions, or a region past the source's end 400 naming the field
extend without duration, or no longer than the source 400
cover with quality turbo 400: cover runs on hifi only
A source shorter than 10 s or longer than 600 s 400

A source sent as a URL is checked when the song renders, so a problem with it fails the job with invalid_request instead, and the job is not billed.

What it does not do yet

Separating a stem, adding a part, or completing a song's tracks need another ACE-Step model, which is not served yet: task takes text2music, repaint, cover and extend.

You send You get
Any other task 400 naming the tasks it serves
n above 1 400: one song per request

When something sounds wrong

You hear Why Do
A name or a stage direction sung Everything in lyrics that is not a tag is sung Keep only the sung words in the lyrics
Words hard to make out Turbo follows the lyrics less closely than hifi in our tests Try the song on hifi
Not the tempo or key you wanted A field left out is the model's choice Send bpm, key and time_signature
A 400 on time_signature Only 2/4, 3/4, 4/4 and 6/8 Use the nearest of the four