AUG 21, 2026

MiniMax API v1 can now generate from a reference track. Upload a piece of audio, get a musicId back, and hand that to POST /music/create — the song it writes is built in the character of what you uploaded.

Two calls, and the first one is free.

Table of contents

  1. Upload the reference
  2. Cover it
  3. Lyric volume is the length dial
  4. Anything on the account can be a reference
  5. Notes

Upload the reference

POST /music/reference takes the raw bytes of an MP3 or WAV. This is the one endpoint in the music API that is not JSON or form-encoded — the body is the file, and Content-Type has to match it.

curl --location 'https://api.useapi.net/v1/minimax/music/reference?name=Stadium%20Reference' \
--header 'Authorization: Bearer user:12345-…' \
--header 'Content-Type: audio/mpeg' \
--data-binary '@reference.mp3'

The clip used below is 21 seconds of a stomping, chant-driven groove:

It comes back complete — no polling, no waiting:

{
  "musicId": "user:12345-minimax:123456789012345678-music:987654321098766",
  "title": "Stadium Reference",
  "duration": 21408,
  "statusLabel": "completed",
  "typeLabel": "reference",
  "lyrics": "[Verse]\n…"
}

Two things worth noticing. lyrics is filled in — MiniMax transcribes whatever singing it hears during the upload, which is how you recover the original words if you want the cover to keep them. And audio_url points at MiniMax’s own re-encoded copy, not your file, so you can play back exactly what the model will be working from.

Uploading costs no credits, and the reference is permanent. One upload backs any number of covers.

Cover it

Pass that musicId as referenceMusicId. Your prompt sets the genre and arrangement, your lyrics set the words.

curl --location 'https://api.useapi.net/v1/minimax/music/create' \
--header 'Authorization: Bearer user:12345-…' \
--form 'referenceMusicId="user:12345-minimax:123456789012345678-music:987654321098766"' \
--form 'title="Ship It Friday"' \
--form 'prompt="stadium stomp and clap rock anthem, huge gang vocals, boot stomps and handclaps, distorted guitar riff, arena crowd, no drum kit until the chorus"' \
--form 'lyrics="[Verse]
Warn me, storm me, you can never ground me
Test me, stress me, everybody doubt me
Page me, rage me, watch the pipeline turning
Roll me, hold me, but the green light'\''s burning

[Chorus]
Ship it! Ship it! Friday!
Nobody'\''s rolling back today"'

Twenty-one seconds, generated in about forty-five. Same length as the reference, same stomp underneath, different genre on top.

Lyric volume is the length dial

There is no duration parameter, and the reference does not set the length either — the amount of lyrics you supply does. That turns out to matter more than it sounds.

Against the same 21-second reference, holding everything else constant:

lyrics Result
None 51 s — the model writes its own, at length
246 characters 21 s
1,031 characters 30-45 s, and audibly rushed

The failure mode is worth knowing about. A thousand characters of lyrics over a thirty-second track is roughly 32 characters of text per second of audio, and it sounds exactly like it reads — crammed. Trim the words back to about 12 characters per second and the same prompt, the same reference and the same idea land properly. Three very different genre prompts at that density all came out within 0.7 s of each other, and within 0.5 s of the reference.

So if a result feels wrong, cut lyrics before you rewrite the prompt.

Anything on the account can be a reference

referenceMusicId is not limited to uploads. Any musicId on the same account works, including songs this API generated earlier — so you can take a track you like and re-cut it in another genre without uploading anything.

Uploaded references live in the same history as your songs, and GET /music keeps them apart with a new type parameter:

curl --location 'https://api.useapi.net/v1/minimax/music/?type=reference' \
--header 'Authorization: Bearer user:12345-…'

type defaults to song, so uploading references never changes what an existing integration sees. Every row also carries typeLabel, and a cover carries referenceMusicId pointing back at what it was built from.

Notes

  • Covers cost the same 300 credits as any other song. Uploads are free.
  • instrumental cannot be combined with referenceMusicId. MiniMax accepts the pair and then fails the track, so the API rejects it up front rather than spending your credits on something that will never render.
  • Streaming works with covers. Set stream to true and you can play it while it renders, exactly as with a normal generation.
  • Only use material you have the rights to. A reference you upload is audio you are responsible for.

Full reference: POST music/reference and POST music/create.