Docs
Get an API key
API reference›Music

Create Music

POST /v1/music Models: Music View .md

Starts a song and answers 202 at once with the job; poll its polling_url, or pass callback_url to be notified (the same signed webhooks as videos, with music.generation.* events). A full song takes minutes. To wait for a short one, send Prefer: wait=<seconds> (at most 60): if the job finishes in that time the answer is 200 with the finished job, otherwise 202 as usual. GET /v1/music/models lists the models with what each accepts.

One request for every model. The fields below are shared by all music models; each model's entry in GET /v1/music/models says which it honours. A field the model cannot honour, sent with a value that asks for something, is a 400 naming the field (metadata.error_type unsupported_parameter), so a request is never billed for something it did not get. A value that asks for nothing (false, [], "") is accepted. A field this API does not know is ignored and reported in the job's warnings.

Other APIs' names are accepted for the shared fields: tags (prompt) and seconds_total (fal), music_length_ms, force_instrumental, model_id and codec strings such as mp3_44100_128 in output_format (ElevenLabs), is_instrumental and audio_setting (MiniMax). aigc_watermark, enable_safety_checker and sync_mode are accepted and ignored.

minimax-music3 (MiniMax-Music3): lyrics are required, and prompt is the style caption. The model was trained on captions under three headings, each field on its own line:

Global Metadata
Basic Attributes: bpm is 92. key is E, and scale is minor. Electric Blues / Blues Rock.
...
Vocal Details
...
Arrangement
...

Free prose works too. Lyric section tags on their own lines steer the structure: [Intro], [Verse], [Pre-Chorus], [Chorus], [Post-Chorus], [Bridge], [Instrumental], [Solo], [Outro] (other spellings such as [pre chorus] or [Inst] are rewritten to these). The prompt and lyrics together may come to about 5,000 tokens. duration is the longest the song may be, 30 to 360 seconds (default 300); the song may end sooner, and you pay for the seconds it has. bpm, key and time_signature are hints: they are written into the caption's Basic Attributes line and reported as advisory_control warnings, and the model may not follow them exactly. One song per request; a seed gives the same song for the same request. Output is rendered at 44.1 kHz stereo, the model's native rate, and delivered as response_format (mp3 by default, 256 kbps) at sample_rate (default 44100); any other rate is resampled. Until 2026-10-20 the default was 32000: send sample_rate: 32000 to keep it, which matters most for pcm, raw samples with no header to say their rate.

Expected wait: while a job is pending, queue_position counts the jobs ahead of it for the same model. Once it starts, minimax-music3 renders about 0.7 seconds per second of song: a 3 minute song is ready in about 2 minutes. progress is estimated from these times.

Billing: per second of audio produced at the model's price (pricing_skus in GET /v1/music/models), each output rounded up to a whole second and never more than duration, only when the job completes. Failed and cancelled jobs are not billed.

Timestamps: timestamps: true also times the lyrics once the song is made. Each output of the finished job carries timestamps (when every word and line is sung, as POST /v1/audio/alignments returns them), the timing is billed per second of audio at aligner-1's price and shown in usage.timestamps, and usage.cost includes it. A timing that fails never fails the song: the output has no timestamps, the job has a timestamps_unavailable warning and the timing is not billed.

Guides: Async jobs, Webhooks, Write songs for MiniMax Music 3, Make songs with ACE-Step 1.5

Header parameters

  • Prefer string

    wait=<seconds>, at most 60: answer with the finished job if it completes in that time.

Body

application/json

The fields every music model shares. Each model's entry in GET /v1/music/models says which it honours; one it cannot honour is a 400 naming it. instrumental, input_references, source_audio, reference_audio, regions, negative_prompt, include, adapters and best_of are reserved for models that will honour them and refused today when they ask for something. language is honoured by models that list languages (ace-step-1.5); source_audio, reference_audio and input_references by models whose tasks take audio (ace-step-1.5 takes a reference on every task and a source on repaint, cover and extend); regions by a task that lists them (ace-step-1.5's repaint); timestamps by models whose entry says timestamps set to true; instrumental by models whose entry says instrumental set to true (ace-step-1.5); and best_of by models whose entry gives best_of a max (ace-step-1.5).

  • model string required
  • prompt string

    The style caption (minimax-music3, at most 6,000 characters; ace-step-1.5, 750). Also accepted as tags.

  • lyrics string

    The words, with section tags on their own lines (minimax-music3, at most 12,000 characters, required; ace-step-1.5, at most 4,096, and none makes an instrumental, sent to the model as [Instrumental]).

  • instrumental boolean

    true asks for a song without words: the same as leaving lyrics out, so true with lyrics is a 400, as it is on a task that works on a song you send (repaint, cover, extend). Not coerced: "true" is a 400. Also accepted as is_instrumental or force_instrumental. Models without instrumental set to true in GET /v1/music/models refuse a true with a 400 naming the field (minimax-music3).

  • duration integer

    Seconds. For minimax-music3 the longest the song may be, 30 to 360 (default 300); for ace-step-1.5 the song's exact length, 10 to 600 (default 120). A task whose length is source (repaint, cover) keeps the source's length and refuses it; for extend it is the new total, required and longer than the source, and only the seconds added are billed. Also accepted as seconds_total, or music_length_ms in milliseconds.

  • write boolean

    true makes prompt a brief, in your own words, that the API has a writer model (deepseek-v4.1-flash) turn into the song before it renders: a style caption the model follows, lyrics in Verse and Chorus sections whose lines fit the tempo, and the tempo, key and time signature. A bpm, key or time_signature you send is kept and the words are fitted to it. What was written is in the job's written; the writer's tokens are billed at its price in usage.write. A brief that cannot be written into a song that meets those rules after one retry fails the job with error_code write_failed, and nothing is billed. Leave lyrics and instrumental out; a new song (text2music) only, in a language write.languages in GET /v1/music/models lists (en on ace-step-1.5). With timestamps or best_of, the written lyrics are the ones timed. Models without write in GET /v1/music/models refuse true with a 400 naming the field (minimax-music3). Not coerced: "true" is a 400.

    default false
  • best_of integer

    How many takes, rendered from seed and the seeds after it, the one song is picked from. The lyrics of each take are aligned by aligner-1 and the take whose lines it placed with the most confidence is returned, with every take's seed and score in outputs[0].metadata.candidates. Every take is billed at the model's price, and every alignment at aligner-1's, in usage.best_of; a job takes about that many times as long. Needs lyrics the aligner can read in a language it lists, as timestamps does (a 400 naming best_of otherwise). Up to best_of.max in GET /v1/music/models (4 on ace-step-1.5); a model without it refuses the field with a 400.

    default 1at least 1
  • n integer

    How many songs to make, each from its own seed, up to the model's outputs.max_n (minimax-music3, 1).

    default 1at least 1
  • seed integer

    The same request with the same seed makes the same song. Each output reports the seed it used.

    range 0–4294967295
  • response_format string

    pcm is raw 16-bit little-endian samples with no header; opus is in Ogg at 48 kHz. Also accepted as output_format, including codec strings such as mp3_44100_128, or MiniMax's audio_setting.format.

    default mp3mp3wavflacopusaacpcm
  • sample_rate integer

    Defaults to the model's own (minimax-music3, 44100, its native rate; 32000 until 2026-10-20). Any other rate is resampled. A pcm file has no header, so a client that assumed the old 32 kHz plays a default file slow: send 32000 to keep the old rate.

    8000160002205024000320004410048000
  • bitrate integer

    Bits per second for mp3, aac and opus (default 256000); ignored with a warning for the other formats.

    320006400096000128000192000256000320000
  • bpm integer

    Tempo. Advisory on minimax-music3 (30 to 300), written into the caption; native on ace-step-1.5 (30 to 300).

  • key string

    A note with an optional accidental and scale, such as C major, F# minor or Eb. Advisory on minimax-music3, native on ace-step-1.5.

  • time_signature string

    Beats over a note value, such as 4/4, 3/4 or 6/8. Advisory on minimax-music3; native on ace-step-1.5, which takes 2/4, 3/4, 4/4 and 6/8 only.

  • task string

    What to do, from the model's tasks. minimax-music3 serves text2music. ace-step-1.5 also serves repaint (regenerate one region of source_audio), cover (re-render source_audio in the caption's style, hifi only, with cover_strength 0 to 1) and extend (continue source_audio to duration).

    default text2music
  • language string

    The language the lyrics are sung in, from the model's languages in GET /v1/music/models; matched without case and by its primary subtag, so zh-CN is zh. ace-step-1.5 takes 50 codes and unknown, and assumes en, or unknown for a song without lyrics. A model without languages refuses it.

  • timestamps boolean

    true also times the lyrics in the finished song: each output gets timestamps with a start and an end for every word and line, the shape POST /v1/audio/alignments answers with, made by aligner-1. Needs lyrics with at least one word in the Latin alphabet (an instrumental, or lyrics only in Chinese, Cyrillic or another script, is a 400), and the song's language must be one aligner-1 lists (a 400 naming them; ace-step-1.5's language, en unless sent). The timing is billed apart, per second of audio rounded up at aligner-1's price, and appears in usage.timestamps. If it fails the song still completes, the output has no timestamps and the job has a timestamps_unavailable warning; that output's timing is not billed. 503 while aligner-1 is not being served. Models without timestamps: true in GET /v1/music/models refuse a true with a 400 naming the field.

    default false
  • reference_audio string or object

    A recording whose voice and tone the song takes up, on a model whose task takes one (tasks[].requires in GET /v1/music/models; ace-step-1.5's text2music). An https URL, a base64 data URI, {"type":"audio_url","audio_url":"https://..."}, or {"type":"job_output","job_id":"music_...","index":0} for a song from one of your own jobs, kept 7 days. At most 50 MB, wav, mp3, flac, ogg, m4a or aac, 10 to 600 seconds on ace-step-1.5. A URL is fetched when the song renders, and a file it serves that breaks these rules fails the job.

    One of 2
    • string
    • Music Audio Inputobject

      One piece of audio sent to a music model. audio_url is an https URL or a base64 data URI; job_output names a song from one of your own completed jobs.

      • type string required
        audio_urljob_output
      • audio_url string or object

        For audio_url. The URL, or {url}.

        One of 2
        • string
        • object
          • url string required
      • job_id string

        For job_output. The job whose song to use.

      • index integer

        For job_output. Which of the job's outputs.

        default 0at least 0
  • source_audio string or object

    The song a task works on (ace-step-1.5's repaint, cover and extend), in the same forms as reference_audio, 10 to 600 seconds and at most 50 MB. A task that takes none refuses it.

    One of 2
    • string
    • Music Audio Inputobject

      One piece of audio sent to a music model. audio_url is an https URL or a base64 data URI; job_output names a song from one of your own completed jobs.

      • type string required
        audio_urljob_output
      • audio_url string or object

        For audio_url. The URL, or {url}.

        One of 2
        • string
        • object
          • url string required
      • job_id string

        For job_output. The job whose song to use.

      • index integer

        For job_output. Which of the job's outputs.

        default 0at least 0
  • input_references array of any

    Audio as a list, each item with its role (reference by default, or source). A role may come once, here or as its own field.

    5 fields
    • type string required
      audio_urljob_output
    • audio_url string or object

      For audio_url. The URL, or {url}.

      One of 2
      • string
      • object
        • url string required
    • job_id string

      For job_output. The job whose song to use.

    • index integer

      For job_output. Which of the job's outputs.

      default 0at least 0
    • role string
      referencesource
  • regions array of objects

    The part of the source a task works on, [{start, end}] in seconds; only a task that lists regions in tasks takes it, and others refuse it. repainting_start and repainting_end are accepted as one region. ace-step-1.5's repaint takes exactly one, which must end inside the source.

    2 fields
    • start number required
      at least 0
    • end number required

      After start.

  • quality string

    The quality tier, on a model that has them (its quality_tiers in GET /v1/music/models); a model without tiers ignores it with an unknown_parameter warning. ace-step-1.5 has turbo (the default; also auto, low, fast) and hifi (also high, hd), which takes longer and bills 7.5 times the seconds. A task may run on only some tiers (its tiers in tasks, the default first); another is a 400. Also accepted under provider.options.

  • callback_url string

    An https URL notified on completion, failure, cancellation and expiry. See GET /v1/webhooks/secret.

  • provider object

    OpenRouter's provider preferences. The routing fields (order, only, ignore, sort, allow_fallbacks, ...) are accepted and ignored. options carries the model's own settings (each model's allowed_passthrough_parameters; minimax-music3 has none) for clients that cannot add top-level fields. From OpenRouter's SDKs use options.stealth: they keep only the slugs on their closed list and drop any other, vultr included, without an error. The first form present wins, the top level before any option; a key the model does not declare is a 400 naming its path.

Responses

Accepted. The job, pending, with its polling_url, queue_position and any warnings.

application/json · music-job-payload

20 fields
  • id string required
  • object string required
    music
  • model string required
  • task string required
  • status string required
    pendingin_progresscompletedfailedcancelledexpired
  • progress integer required

    Estimated percent while rendering.

  • created_at integer required
  • completed_at integer
  • expires_at integer

    When the audio is deleted (7 days after completion).

  • polling_url string required
  • stream_url string

    While pending or in_progress on a model that streams (streaming.progressive): the song as WAV as it renders, from its first byte (GET /v1/music/{id}/stream; ?index=N for another output). Send your API key.

  • timestamps_stream_url string

    While pending or in_progress on a model that streams, for a song asked for with timestamps: true: its lyric lines as they settle while it renders, then the finished timing, as server-sent events (GET /v1/music/{id}/timestamps/stream; ?index=N for another output). Send your API key.

  • queue_position integer

    Jobs ahead of this one for the same model, while pending.

  • outputs array of objects
    12 fields
    • index integer

      Its place in outputs and in unsigned_urls; GET /v1/music/{id}/content?index=N.

    • kind string
    • role string

      What the audio is; mix is the whole song.

    • candidate integer

      Which of the n songs it belongs to.

    • content_type string
    • format string
    • duration_seconds number
    • sample_rate integer
    • channels integer
    • seed integer
    • metadata object

      With best_of, candidates: every take in the order rendered, {seed, score}, where score is the mean confidence aligner-1 placed its lyric lines with (0 to 1; null for a take it could not align). The output is the take with the highest score.

      1 field
      • candidates array of objects
        2 fields
        • seed integer
        • score number or null
    • timestamps object

      When each word and line of the lyrics is sung in this output, in seconds from the start of the file. The same lines, words and unaligned lines POST /v1/audio/alignments answers with (docs/alignments), made by aligner-1 from the output's own audio and the lyrics you sent. Present only on a job that sent timestamps set to true, and only on an output that was timed; an output that could not be has none, and the job says so in warnings (timestamps_unavailable).

      4 fields
      • separated boolean required

        Whether the vocal was separated from the music before it was timed. Always true for a song.

      • lines array of objects required

        The lines of the lyrics that were placed, in order. Section labels such as [Chorus] are not lines; they are each line's tag.

        8 fields
        • index integer required

          Which line of text this is, counting from 0 and skipping section labels and blank lines.

        • section integer required

          Which section the line is in, counting from 0, so a chorus that repeats stays two sections.

        • tag string or null required

          The label of the section (Chorus for [Chorus]), or null for lines before the first label or in text with none.

        • text string required

          The line as you wrote it.

        • start number required

          Seconds from the start of the audio to the first word.

        • end number required

          Seconds from the start of the audio to the end of the last word.

        • score number required

          Median confidence of the line's words. Higher is better; use it to judge by, not to filter on.

        • certain boolean required

          The aligner's judgement that the line is placed right. False where a word was held so long that the search plainly parked it across a gap. True is not a guarantee.

      • words array of objects required

        Every word of the lines above, in order, as written in the lyrics.

        5 fields
        • line integer required

          The index of the line the word is in.

        • text string required

          The word as you wrote it.

        • start number required

          Seconds from the start of the audio.

        • end number required

          Seconds from the start of the audio.

        • score number required

          The aligner's confidence in this word.

      • unaligned array of objects required

        Lines the model could not place, listed instead of left out.

        3 fields
        • line integer required

          The index of the line.

        • text string required
        • reason string required

          Why the line was not placed.

  • written object

    A job sent write: true, once completed: the song the writer wrote from the brief, as the model was sent it.

    5 fields
    • prompt string required

      The style caption.

    • lyrics string required
    • bpm integer required
    • key string required
    • time_signature string required
  • unsigned_urls array of strings

    outputs[N] is at unsigned_urls[N]; send your API key.

  • warnings array of objects required
    3 fields
    • code string

      advisory_control (a hint the model may not follow exactly), ignored_parameter (accepted and not used), unknown_parameter (not a music request field) timestamps_unavailable (the song is complete, but this output could not be timed; nothing was billed for the timing) or best_of_unranked (no take could be aligned, so the first take is returned; every take was rendered and is billed, no alignment is).

    • field string
    • message string
  • usage object
    7 fields
    • cost number

      Dollars, billed_seconds times the model's price, plus timestamps.cost when the lyrics were timed, best_of.cost when takes were ranked and write.cost when the song was written.

    • duration_seconds number
    • billed_seconds integer

      Seconds of song billed at the model's price, every take's with best_of. The timing of the lyrics is billed apart, in timestamps or best_of.

    • outputs integer
    • timestamps object

      The timing of the lyrics, billed against aligner-1 as POST /v1/audio/alignments bills it. Present only when at least one output was timed; an output that could not be is not billed.

      2 fields
      • billed_seconds integer required

        The seconds of audio that were timed, each output rounded up to a whole second.

      • cost number required

        Dollars for billed_seconds at aligner-1's price.

    • best_of object

      A job sent best_of above 1: how many takes were rendered, and the alignment that ranked them, billed against aligner-1 as POST /v1/audio/alignments bills it. With timestamps, the kept take's timing is this alignment, billed here once and not in timestamps. A take that could not be aligned is not billed.

      3 fields
      • takes integer required
      • billed_seconds integer required

        The seconds of audio aligned, each take rounded up to a whole second.

      • cost number required

        Dollars for billed_seconds at aligner-1's price.

    • write object

      A job sent write: true: the writer's tokens, every attempt's, billed at its row's prices as POST /v1/chat/completions bills them.

      4 fields
      • model string required
      • prompt_tokens integer required
      • completion_tokens integer required
      • cost number required

        Dollars for the tokens at the writer's prices.

  • error string

    The failure, when failed.

  • error_code string

    Why the job failed: invalid_request, payload_too_large, timeout, provider_error, server_error, or write_failed (write: true and no draft met the rules; not billed).

curl https://api.vultrinference.com/v1/music \
  -H "Authorization: Bearer $VULTR_INFERENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music3",
    "prompt": "Global Metadata\nBasic Attributes: bpm is 118. key is F, and scale is minor. Disco Pop / Nu-Disco.\nVocal Details\nBright female lead, close-miked, light doubles on the chorus.\nArrangement\nFour-on-the-floor kick, slap bass, string stabs, filtered synth swells into the chorus.",
    "lyrics": "[Verse]\nCity lights are humming low\nEvery window starts to glow\n[Chorus]\nWe keep on running through the night",
    "duration": 180,
    "response_format": "mp3",
    "callback_url": "https://example.com/hooks/music"
  }'
Response · 202
{
    "id": "music_0123456789abcdef01234567",
    "object": "music",
    "model": "string",
    "task": "string",
    "status": "pending",
    "progress": 0,
    "created_at": 1790000000,
    "polling_url": "string",
    "warnings": [
        {
            "code": "string",
            "field": "string",
            "message": "string"
        }
    ]
}