The MiniMax Music API can create a vocal song from a style prompt and lyrics, generate an instrumental without lyrics, or produce a new rendition from reference audio through the dedicated cover model. This guide separates those workflows, shows the exact model IDs and endpoints, and explains how to save the returned audio safely.
Independent-site notice: MiniMax-AI.chat is an independent educational website. It is not MiniMax or an official MiniMax Open Platform property. API access, billing, model availability, generated audio, and account limits are supplied by MiniMax through its official developer platform.
Last verified: August 20, 2026. API availability was rechecked against MiniMax’s official Music Generation reference and pay-as-you-go page. Endpoint fields and the retained examples were rechecked for existing accounts that still have hosted access. MiniMax’s public MiniMax-Music3 checkpoint, local serving route, and Community License remain a separate self-managed path.
Verification scope: The hosted payloads were rechecked against the documented schema, and the existing Node.js and Python examples remain unchanged. No billable hosted request or local inference run was performed for this update, so this page makes no independent claim about generated audio quality.
Hosted workflow: the examples below are retained for existing paying accounts with confirmed MiniMax Music API access. They are not a current signup path. The text-only MiniMax-AI.chat demo does not generate music, upload reference audio, charge a MiniMax balance, or expose Music 3.0. MiniMax also publishes the separate MiniMaxAI/MiniMax-Music3 checkpoint for self-managed inference; that local route does not use the Open Platform model IDs or hosted endpoint. Keep hosted API keys and generation requests on a trusted server.
Availability update — effective August 20, 2026: MiniMax’s official Music Generation reference says the paid Music Generation and Lyrics Generation APIs are no longer available to new users. Existing paying users can continue using the current API services, subject to the entitlement shown in their account. The free API IDs
music-3.0-free,music-2.6-free, andmusic-cover-freehave been discontinued. The hosted examples below are retained for existing eligible accounts; they are not a current signup path. New users can use MiniMax Audio or evaluate the self-managedMiniMaxAI/MiniMax-Music3checkpoint.
How the hosted MiniMax Music API works
- If an existing paid account still has Music API access, use
music-3.0for text-to-music ormusic-coverfor a rendition based on reference audio. Confirm the entitlement in the official console before integrating. - Send JSON to
POST https://api.minimax.io/v1/music_generationwith a server-side Bearer API key. - For a vocal song, supply lyrics or set
lyrics_optimizer: trueand leavelyricsempty. - For an instrumental, set
is_instrumental: trueand provide a descriptive prompt. - Choose
output_format: "url"for a downloadable URL oroutput_format: "hex"for hex-encoded audio. A URL expires after 24 hours. - Persist the audio in storage you control and retain the request parameters, trace ID, rights record, and moderation decision.
The official music reference documents a synchronous HTTP request with optional streaming; it does not document a create-task, task-status, or polling route for music. With stream: false, the complete response arrives on the original request. With stream: true, only hex output is supported.
Hosted Music API model and workflow matrix
| Model ID | Use it for | Access and documented limit | Important restriction |
|---|---|---|---|
music-3.0 | Vocal songs, automatic lyrics, or instrumentals | Existing paying users with retained Music API access; the reference continues to show 120 RPM | Not available as a new-user API signup from August 20, 2026. Reference-audio cover fields do not belong to this model. |
music-2.6 | Previous-generation text-to-music | Existing paying users with retained access; 120 RPM remains documented | Prefer Music 3.0 when the eligible account supports it. |
music-cover | One-step or two-step cover generation from reference audio | Existing paying users with retained Music Generation access; 120 RPM remains documented | Requires confirmed entitlement, a style prompt, and a reference-audio source or valid cover_feature_id. |
For eligible existing paying accounts, the general rate-limit table continues to list 20 concurrent connections for music generation. Treat RPM and connection limits as separate controls: a request can fit the per-minute limit and still exceed the allowed simultaneous connections. These technical limits do not establish new-account entitlement.
For capability comparisons rather than endpoint implementation, use the MiniMax Music 3.0 model page or the Music 2.6 model page. For shared authentication and API conventions, start with the MiniMax API overview. This guide is intentionally focused on music request routing, validation, output handling, and deployment.
Hosted API versus local open-weight Music 3
MiniMax now provides two distinct Music 3 access paths. They share a product-family name, but their identifiers and request contracts are not interchangeable.
| Access path | Exact identifier | Request route | Request and output shape | Main constraint |
|---|---|---|---|---|
| Hosted Open Platform | music-3.0 for existing eligible paying accounts | POST https://api.minimax.io/v1/music_generation | Uses prompt, lyrics, optional lyrics optimization or instrumental mode, and returns URL or hex audio under the hosted schema | No new-user hosted API access from August 20, 2026; confirm retained access in the account console. |
| Self-managed checkpoint | MiniMaxAI/MiniMax-Music3 | The current SGLang-Omni example serves POST http://127.0.0.1:8000/v1/audio/speech | Puts lyrics in input, the music description in instructions, and requests WAV output; the official card describes 32 kHz, 16-bit stereo WAV and non-streaming inference | Requires self-managed CUDA infrastructure and compliance with the MiniMax-Music3 Community License |
Do not send MiniMaxAI/MiniMax-Music3 to api.minimax.io/v1/music_generation, and do not send music-3.0 to the local speech-compatible route. The stable checkpoint ID is MiniMaxAI/MiniMax-Music3; verify any runtime-specific local alias against the installed serving version.
The checkpoint is downloadable under the custom MiniMax-Music3 Community License, not an unrestricted open-source grant. Review its attribution, revenue-threshold, safeguards, and Acceptable Use Policy requirements before commercial deployment.
Music 3.0 request fields that affect routing
| Field | Documented behavior | Implementation note |
|---|---|---|
model | Required; use an exact model ID from the matrix. | For an existing account with retained hosted access, use music-3.0. The discontinued free IDs are not current request options. MiniMaxAI/MiniMax-Music3 is the downloadable checkpoint ID, not a hosted Open Platform model value. |
prompt | Describes style, mood, and scenario. For an instrumental it is required at 1–2,000 characters; for a non-instrumental Music 3.0 request it is optional at 0–2,000 characters. | A cover prompt is required and must be 10–300 characters. |
lyrics | For a non-instrumental Music 3.0 request it is required at 1–3,500 characters unless automatic lyrics are enabled. For a cover it is optional at 10–1,000 characters unless cover_feature_id is used. | Separate lines with \n and use supported structure tags. |
lyrics_optimizer | Defaults to false. When true and lyrics are empty, Music 3.0 or Music 2.6 generates lyrics from the prompt. | It is not a cover-model field. |
is_instrumental | Defaults to false. When true, lyrics are not required. | Supported for Music 3.0 and Music 2.6 families, not music-cover. |
stream | Defaults to false. | When true, output_format must be hex. |
output_format | url or hex; default hex. | Download URL output within 24 hours. |
audio_setting | Controls audio output configuration. | The official examples use 44,100 Hz, 256 kbps, and MP3; this guide does not invent additional enum values. |
Supported lyric structure tags in the music-generation reference include [Intro], [Verse], [Pre Chorus], [Chorus], [Interlude], [Bridge], [Outro], [Post Chorus], [Transition], [Break], [Hook], [Build Up], [Inst], and [Solo]. The separate Lyrics Generation endpoint documents a similar but not identical tag list, so preserve the tags returned by that endpoint rather than mechanically renaming them.
Node.js: generate lyrics, create a song, and save the MP3
This server-side example first calls the optional Lyrics Generation endpoint, then sends the returned lyrics to Music 3.0. It checks HTTP errors and MiniMax’s application-level status before downloading the 24-hour URL.
import { writeFile } from "node:fs/promises";
const API_BASE = "https://api.minimax.io";
const API_KEY = process.env.MINIMAX_API_KEY;
if (!API_KEY) {
throw new Error("Set MINIMAX_API_KEY in the server environment.");
}
async function minimaxJson(path, payload) {
const response = await fetch(API_BASE + path, {
method: "POST",
headers: {
Authorization: "Bearer " + API_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify(payload)
});
const raw = await response.text();
let data;
try {
data = raw ? JSON.parse(raw) : {};
} catch {
throw new Error("MiniMax returned non-JSON data (HTTP " + response.status + ").");
}
if (!response.ok) {
throw new Error("MiniMax HTTP " + response.status + ": " + raw);
}
const code = data?.base_resp?.status_code;
if (typeof code === "number" && code !== 0) {
const message = data?.base_resp?.status_msg || "Unknown MiniMax error";
throw new Error("MiniMax error " + code + ": " + message);
}
return data;
}
const lyricResult = await minimaxJson("/v1/lyrics_generation", {
mode: "write_full_song",
prompt:
"An original hopeful indie-pop song about rebuilding a coastal garden " +
"after a storm; warm, restrained, and suitable for a brand film.",
title: "Garden After Rain"
});
if (!lyricResult.lyrics) {
throw new Error("The Lyrics Generation response did not contain lyrics.");
}
const musicResult = await minimaxJson("/v1/music_generation", {
model: "music-3.0",
prompt:
"Indie pop, hopeful and restrained, female vocal, clean electric guitar, " +
"soft drums, warm bass, gradual final chorus, polished mix",
lyrics: lyricResult.lyrics,
stream: false,
output_format: "url",
audio_setting: {
sample_rate: 44100,
bitrate: 256000,
format: "mp3"
}
});
const audioUrl = musicResult?.data?.audio;
if (typeof audioUrl !== "string" || !audioUrl.startsWith("https://")) {
throw new Error("The Music Generation response did not contain an HTTPS audio URL.");
}
const download = await fetch(audioUrl);
if (!download.ok) {
throw new Error("Audio download failed with HTTP " + download.status + ".");
}
await writeFile("garden-after-rain.mp3", Buffer.from(await download.arrayBuffer()));
console.log({
title: lyricResult.song_title,
traceId: musicResult.trace_id,
durationMs: musicResult?.extra_info?.music_duration,
savedAs: "garden-after-rain.mp3"
});Do not store only the temporary URL. Save the bytes immediately and record enough metadata to reproduce your own request: model ID, prompt, lyrics version, output settings, generation time, internal project ID, and rights approval. Do not log the Bearer token or a Base64 reference track.
Python: generate a Music 3.0 instrumental
import os
import requests
api_key = os.environ.get("MINIMAX_API_KEY")
if not api_key:
raise RuntimeError("Set MINIMAX_API_KEY in the server environment.")
response = requests.post(
"https://api.minimax.io/v1/music_generation",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json={
"model": "music-3.0",
"prompt": (
"Instrumental cinematic electronica, calm opening, muted pulse, "
"soft piano motif, subtle strings, gradual lift, no vocals"
),
"is_instrumental": True,
"stream": False,
"output_format": "url",
"audio_setting": {
"sample_rate": 44100,
"bitrate": 256000,
"format": "mp3",
},
},
timeout=600,
)
response.raise_for_status()
result = response.json()
code = result.get("base_resp", {}).get("status_code")
if code not in (None, 0):
message = result.get("base_resp", {}).get("status_msg", "Unknown error")
raise RuntimeError(f"MiniMax error {code}: {message}")
audio_url = result.get("data", {}).get("audio")
if not isinstance(audio_url, str) or not audio_url.startswith("https://"):
raise RuntimeError("The response did not contain an HTTPS audio URL.")
download = requests.get(audio_url, timeout=120)
download.raise_for_status()
with open("cinematic-instrumental.mp3", "wb") as output:
output.write(download.content)
print("Saved cinematic-instrumental.mp3")Dedicated Lyrics Generation versus lyrics_optimizer
| Method | Best fit | Control |
|---|---|---|
POST /v1/lyrics_generation | A separate editorial step before paid audio generation | write_full_song creates a song; edit revises or continues supplied lyrics. Prompt limit: 2,000 characters. Existing lyrics limit in edit mode: 3,500 characters. A supplied title is preserved. |
lyrics_optimizer: true | A one-request Music 3.0 or Music 2.6 workflow | Leave lyrics empty and let the music request derive lyrics from the prompt. It is faster to integrate but removes the separate review gate. |
| Own lyrics | Brand, campaign, narrative, or legally reviewed copy | Pass the approved text directly and keep lyrics_optimizer: false. |
For eligible existing paying accounts, the retained pay-as-you-go figures list Lyrics Generation at $0.01 per song and Music 3.0 at $0.15 per generation of up to five minutes. These are separate billing items when both endpoints are available to the account. They are not an offer of new API access.
One-step and two-step Music Cover workflows
One-step cover: keep the reference lyrics
{
"model": "music-cover",
"audio_url": "https://assets.example.com/licensed-reference.mp3",
"prompt": "Smooth jazz, late-night lounge, brushed drums, upright bass, saxophone",
"output_format": "url",
"audio_setting": {
"sample_rate": 44100,
"bitrate": 256000,
"format": "mp3"
}
}Provide exactly one of audio_url or audio_base64. The reference must be between 6 seconds and 6 minutes, no larger than 50 MB, and in a common audio format such as MP3, WAV, or FLAC. When lyrics are omitted, the cover workflow extracts them from the reference with ASR.
Two-step cover: inspect or change the lyrics
- Send
model: "music-cover"and one reference-audio source toPOST /v1/music_cover_preprocess. - Read
cover_feature_id,formatted_lyrics,structure_result, andaudio_duration. - Review the extracted text, correct ASR mistakes, and make only changes you are authorized to make.
- Within 24 hours, call
POST /v1/music_generationwithmodel: "music-cover", the feature ID, 10–1,000 characters of lyrics, and a 10–300 character style prompt. - Do not include
audio_urloraudio_base64in that second request because those fields are mutually exclusive withcover_feature_id.
The official guide describes preprocessing as free and says identical audio content returns the same feature ID through MD5-based deduplication. A feature ID is temporary, not a permanent catalog asset.
Streaming, hex, and URL output
| Configuration | Response behavior | Storage action |
|---|---|---|
stream: false, output_format: "url" | The complete request returns a temporary URL in the audio response field. | Download within 24 hours and store the bytes yourself. |
stream: false, output_format: "hex" | The complete request returns hex-encoded audio. | Decode with Buffer.from(audio, "hex") in Node.js. |
stream: true, output_format: "hex" | The endpoint streams hex output on the same HTTP request. | Process provider frames in order and finalize the file only after successful completion. |
stream: true, output_format: "url" | Not supported by the reference. | Change the output format to hex or disable streaming. |
Streaming is not the same as an asynchronous task. The music reference does not return a task_id for later polling. Run the request behind a server route with a suitable upstream timeout, connection limit, cancellation policy, and retry rule.
Pricing and limits verified for this guide
| Item | Documented value |
|---|---|
music-3.0 | Existing eligible paying accounts: the retained figure is $0.15 per generation of up to five minutes; the technical reference lists 120 RPM |
| Lyrics Generation | Existing eligible paying accounts: the retained figure is $0.01 per song; not available to new users from August 20, 2026 |
| Paid music connection limit | 20 concurrent connections in the general rate table for eligible existing paying accounts |
| Music Cover reference audio | 6 seconds–6 minutes; maximum 50 MB |
| Music Cover feature ID | Valid for 24 hours |
| Generated audio URL | Expires after 24 hours |
The retained pay-as-you-go table does not publish a separate music-cover price. Existing paying users should confirm retained cover entitlement and billing in the official console or with MiniMax before estimating a production budget; new users should not assume the documented operation can be activated. Do not copy the Music 3.0 price onto cover calls. See our MiniMax pricing explainer for a dated comparison across API families.
Rights and consent checks for lyrics, audio, and covers
An endpoint named “cover” is a technical capability, not permission to copy a song. Before uploading reference audio or distributing an output, document your rights to the recording, composition, lyrics, performance, and any identifiable voice. Obtain consent where a person’s voice or identity is involved, and check the rules of the distributor, advertiser, platform, territory, and collecting society that apply to your release.
- Prefer music, lyrics, and recordings created by your organization or supplied under a license that permits the intended transformation and distribution.
- Do not treat automatic lyric extraction as ownership or clearance of the extracted words.
- Keep the license, consent, source URL, rights holder, permitted territories, expiry date, and approver with the generation record.
- Review the Open Platform terms and any music-specific terms applicable to the service and account you use.
- Escalate commercial releases, recognizable voices, and disputed ownership to qualified counsel. This guide is technical information, not legal advice.
Production checklist
- Keep
MINIMAX_API_KEYin a server secret store and rotate it after suspected exposure. - Validate the model-specific prompt and lyric lengths before sending a billable call.
- Limit concurrency separately from request rate and add exponential backoff with jitter for retryable failures.
- Do not automatically retry an uncertain POST after a network timeout without an internal duplicate-control policy; the first call may have completed.
- Inspect both the HTTP status and
base_resp.status_code. Preservetrace_idfor support. - Download temporary URLs immediately, verify that the response is audio, and write to non-public storage before moderation.
- Run loudness, clipping, duration, language, lyric, rights, and human-review checks before publishing.
- Use the MiniMax API error guide for retry classification, and review our security guidance before handling customer media.
MiniMax Music API FAQ
Is the MiniMax Music API asynchronous?
The official reference documents one HTTP generation request with optional streaming. It does not document a music task ID, polling endpoint, or later file-retrieval step.
Can Music 3.0 generate lyrics automatically?
Yes. Set lyrics_optimizer: true, leave lyrics empty, and provide a descriptive prompt. For an editorial review step, call /v1/lyrics_generation first and pass the approved result into the music request.
Can Music 3.0 create instrumental tracks?
Yes. Set is_instrumental: true. Lyrics are then optional, while the prompt is required and must be 1–2,000 characters.
Can I run MiniMax Music 3 locally?
Yes. MiniMax publishes the MiniMaxAI/MiniMax-Music3 checkpoint with download and SGLang-Omni serving instructions. The current local example exposes a speech-compatible /v1/audio/speech route and is separate from the hosted /v1/music_generation API. Local use requires your own compute and compliance with the checkpoint’s Community License; it does not make the model unrestricted open source.
How long does a MiniMax music URL remain usable?
The generation reference says URL output expires after 24 hours. Copy the audio into your own object storage instead of embedding the temporary URL in a published page or app.
What does a MiniMax Music Cover call cost?
The operation reference still contains legacy paid and free model entries, but the August 20 availability notice ends the free APIs and limits continuing paid API service to existing paying users. The retained pricing table does not show a separate price for music-cover. Confirm retained cover access and billing in the official console before use.
Update log
August 20, 2026: added the new-user availability restriction, marked all free Music API IDs discontinued, limited hosted examples to existing eligible paying accounts, and preserved the request examples for those accounts.
Official sources followed
- Music Generation API reference
- Music Generation developer guide
- Lyrics Generation API reference
- Music Cover Preprocess API reference
- MiniMax model overview
- MiniMax pay-as-you-go pricing
- MiniMax API rate limits
- MiniMax Open Platform Terms of Service
- MiniMax music-creation terms
Open-weight sources: MiniMax Music 3 official model card; MiniMax-Music3 Community License; MiniMax Music 3 official GitHub repository.
Scope: This page explains the developer API. It does not claim that MiniMax-AI.chat generates music, and it does not replace the dedicated Music 3.0 model page, MiniMax account documentation, or legal advice.