# Create Music

`POST https://api.vultrinference.com/v1/music`

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 32 kHz stereo and delivered as `response_format` (`mp3` by default, 256 kbps).

**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.

## Header parameters

- `Prefer` (string): `wait=<seconds>`, at most 60: answer with the finished job if it completes in that time.

## Body (application/json)

- `model` (string, required)
- `prompt` (string): The style caption (minimax-music3, at most 6,000 characters). Also accepted as `tags`.
- `lyrics` (string): The words, with section tags on their own lines (minimax-music3, at most 12,000 characters; required).
- `duration` (integer): Seconds. For minimax-music3 the longest the song may be, 30 to 360 (default 300). Also accepted as `seconds_total`, or `music_length_ms` in milliseconds.
- `n` (integer): How many songs to make, each from its own seed, up to the model's `outputs.max_n` (minimax-music3, 1). [default 1, at 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 mp3, mp3, wav, flac, opus, aac, pcm]
- `sample_rate` (integer): Defaults to the model's own (minimax-music3, 32000). [8000, 16000, 22050, 24000, 32000, 44100, 48000]
- `bitrate` (integer): Bits per second for `mp3`, `aac` and `opus` (default 256000); ignored with a warning for the other formats. [32000, 64000, 96000, 128000, 192000, 256000, 320000]
- `bpm` (integer): Tempo. Advisory on minimax-music3 (30 to 300), written into the caption.
- `key` (string): A note with an optional accidental and scale, such as `C major`, `F# minor` or `Eb`. Advisory on minimax-music3.
- `time_signature` (string): Beats over a note value, such as `4/4`, `3/4` or `6/8`. Advisory on minimax-music3.
- `task` (string): What to do, from the model's `tasks`. minimax-music3 serves `text2music`. [default text2music]
- `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

- `202`: Accepted. The job, pending, with its polling_url, queue_position and any warnings. (music-job-payload)
- `200`: With Prefer: wait, the job finished in time. (music-job-payload)
- `400`: A field the model cannot honour, a value out of range or a malformed field. The message names the field. (error-payload)
- `401`: The API key is missing, unknown or not active. Send it as Authorization: Bearer <key>. (error-payload)
- `404`: Unknown music model (error-payload)
- `503`: The model has no valid capability spec at the moment and is not served. (error-payload)

## Example

```bash
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"
  }'
```

```python
import os
import requests

response = requests.post(
    "https://api.vultrinference.com/v1/music",
    headers={"Authorization": f"Bearer {os.environ['VULTR_INFERENCE_API_KEY']}"},
    json={
        "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",
    },
)
print(response.json())
```

```javascript
const response = await fetch("https://api.vultrinference.com/v1/music", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VULTR_INFERENCE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "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"
  }),
});
console.log(await response.json());
```