POST music/reference

Upload Reference Music

August 21, 2026

Request Headers
Request Body
Query Parameters
Responses
Model
Examples
Try It

Uploads an audio file and registers it on the MiniMax account as a reference track. The response carries a musicId you pass to POST music/create as referenceMusicId, which produces a cover — a new song built in the character of the reference.

Upload once and reuse. A reference is a permanent record on the account, so the same musicId can back any number of covers — there is no need to re-send the file per song.

MiniMax transcribes the lyrics from the audio during upload and returns them, which is how you get the original words if you want the cover to keep them.

https://api.useapi.net/v1/minimax/music/reference?account={account}&name={name}

Request Headers

Authorization: Bearer {API token}
Content-Type: audio/mpeg

API token is required, see Setup useapi.net for details.
Content-Type is required and must match the file you are sending. Supported values: audio/mpeg, audio/mp3, audio/wav, audio/wave, audio/x-wav.

Request Body

The raw bytes of the audio file — not JSON, and not multipart/form-data.

Query Parameters

account is optional when only one account is configured. If you have several MiniMax accounts configured, this parameter becomes required.
name is optional, the title the reference is stored under. Max length 40. Defaults to a timestamp.

Notes:

Both MP3 and WAV are accepted. MiniMax re-encodes whatever you send to MP3 and serves it back from its own CDN, so the audio_url in the response is a re-hosted copy rather than your original file.
There is no length limit worth planning around. A 20-second excerpt and a full 3-minute song both upload and both work as references.
The reference does not set the cover’s length — lyrics does, exactly as it does for an ordinary song. To get a cover close to the reference’s length, pass the reference’s own lyrics back in.
How strongly the reference comes through varies, and a detailed prompt competes with it. Omit prompt entirely and the model takes its cues from the audio alone.
Uploading does not generate anything and costs no credits. Only POST music/create does.
References appear in GET music under type=reference, and are hidden from the default type=song listing.
You do not have to upload at all to make a cover. Any song already on the account works as a reference — pass its musicId straight to referenceMusicId.
Only upload audio you have the rights to use.

Responses

201 Created

The reference is ready immediately — statusLabel is already completed and audio_url already points at the stored copy.

{
  "musicId": "user:12345-minimax:123456789012345678-music:987654321098766",
  "title": "Last Train 20s",
  "idea": "",
  "lyrics": "[Chorus]\nin my ear.\n\n[Verse]",
  "audio_url": "https://cdn.hailuoai.video/moss/prod/2026-08-21-09/moss-audio/user_music/1700000000000000000-987654321098766.mp3",
  "cover_url": "https://cdn.hailuoai.video/moss/staging/2025-06-22-16/music_cover/1700000000000000002-other_44.png",
  "model": "",
  "status": 2,
  "statusLabel": "completed",
  "statusFinal": true,
  "typeLabel": "reference",
  "instrumental": false,
  "duration": 20036,
  "create_time": 1787276488868,
  "update_time": 1787276488868,
  "is_favorite": false,
  "tag_list": []
}

400 Bad Request

An unsupported Content-Type:

{
  "error": "Content-Type (image/png) not supported. Valid values: audio/mpeg,audio/mp3,audio/wav,audio/wave,audio/x-wav",
  "code": 400
}

An empty body:

{
  "error": "Content is empty",
  "code": 400
}

401 Unauthorized

{
  "error": "Unauthorized",
  "code": 401
}

596 Account Error

{
  "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.",
  "code": 596
}

Model

{ // TypeScript, all fields are optional
  musicId: string,       // Pass to POST music/create as referenceMusicId
  title: string,         // The name you supplied
  idea: string,          // Always empty on a reference
  lyrics: string,        // Transcribed from the audio by MiniMax
  audio_url: string,     // MiniMax's re-hosted copy of your file
  cover_url: string,     // Cover art, assigned automatically
  model: string,         // Always empty on a reference
  status: number,        // 2 — a reference is complete on arrival
  statusLabel: string,
  statusFinal: boolean,
  typeLabel: string,     // Always "reference" here
  instrumental: boolean,
  duration: number,      // Milliseconds
  create_time: number,
  update_time: number,
  is_favorite: boolean,
  tag_list: [{ tag_name: string, tag_type: number }]
}

Examples

curl "https://api.useapi.net/v1/minimax/music/reference?name=Last%20Train%2020s" \
  -H "Authorization: Bearer …" \
  -H "Content-Type: audio/mpeg" \
  --data-binary "@reference.mp3"

import { readFile } from "node:fs/promises";

const file = await readFile("reference.mp3");

const response = await fetch("https://api.useapi.net/v1/minimax/music/reference?name=Last Train 20s", {
  method: "POST",
  headers: {
    "Authorization": "Bearer …",
    "Content-Type": "audio/mpeg"
  },
  body: file
});

const reference = await response.json();

console.log(reference.musicId, reference.duration, reference.lyrics);

import requests

with open("reference.mp3", "rb") as file:
    response = requests.post(
        "https://api.useapi.net/v1/minimax/music/reference",
        headers={
            "Authorization": "Bearer …",
            "Content-Type": "audio/mpeg"
        },
        params={"name": "Last Train 20s"},
        data=file.read()
    )

reference = response.json()

print(reference["musicId"], reference["duration"])
print(reference["lyrics"])

Then turn it into a cover:

curl "https://api.useapi.net/v1/minimax/music/create" \
  -H "Authorization: Bearer …" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceMusicId": "user:12345-minimax:123456789012345678-music:987654321098766",
    "prompt": "italo disco, driving synth bass, bright arpeggios",
    "title": "Last Train Italo"
  }'

Try It

Pick an MP3 or WAV and upload it. The musicId that comes back is what POST music/create takes as referenceMusicId, and the player above the response plays MiniMax’s stored copy — which is what the model will actually follow, not the file on your disk.