MiniMax Music — Cloud Music Generation

This skill covers the CLOUD platform API only (api.minimax.io, Bearer auth with a platform API key). It does not cover the local Electron gateway — see minimax-local-audio for that, and do not mix their parameter shapes: this API takes real JSON types ("is_instrumental": true), the local gateway takes strings ("is_instrumental": "instrumental").

Quick start — instrumental bed

curl -s -X POST "https://api.minimax.io/v1/music_generation" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "music-3.0",
    "is_instrumental": true,
    "prompt": "Cinematic indie folk, warm, nostalgic, hopeful, felt piano, soft string swell, slow tempo, 76 BPM",
    "audio_setting": {"sample_rate": 44100, "bitrate": 256000, "format": "mp3"},
    "output_format": "url"
  }' -o resp.json

jq -r '.data.audio' resp.json | xargs curl -sL -o track.mp3

⏱ Generation takes ~3 minutes and the call blocks the whole time. Set a client timeout of at least 600s and run it in the background. A 120s shell timeout will kill it mid-flight.

✅ Verified facts that contradict older documentation

There is still no duration parameter and no way to place a climax at a chosen timestamp. Output length is emergent — but it is long, so for anything under ~2 minutes the practical approach is: generate, measure, then trim and fade to fit in ffmpeg.

Phase 0: The brief

[1. GENRE & STYLE] — musical DNA: genre, subgenre, era, reference sound, BPM, key
[2. MOOD & EMOTION] — emotional arc, energy, atmosphere, time of day
[3. LYRICS & THEME] — the story (skip entirely for instrumentals)
[4. ARRANGEMENT] — instrumentation, dynamics, section structure, production style

Decide first: song with vocals, instrumental, or cover? That choice determines which parameters are required — see the table in Phase 2.

Phase 1: Models

Paid models require a Token Plan or paid account; -free variants work on any API key.

💡 Billing is flat per generation, bucketed at "up to 5 minutes". A 30-second track costs the same $0.15 as a 5-minute one — there is no incentive to aim short. And since the peak position cannot be controlled, plan on generating several takes and selecting. Audition prompts on music-3.0-free first (3 RPM = one every 20s), then spend on the winner.

Phase 2: Parameters

What is required, by mode

⚠️ Instrumental is the one mode where prompt is mandatory. And although the docs only say lyrics is "not required" there, the schema sets minLength: 1 — so sending "lyrics": "" may be rejected. Omit the key rather than passing an empty string.

is_instrumental and lyrics_optimizer are supported on the four text-to-music models only, not on music-cover.

audio_setting

No defaults are documented — set all three explicitly.

Lyrics section tags

[Intro] [Verse] [Pre Chorus] [Chorus] [Post Chorus] [Bridge] [Interlude] [Transition] [Break] [Hook] [Build Up] [Inst] [Solo] [Outro]

⚠️ The lyrics-generation endpoint emits a slightly different set — it can return [Drop], [Instrumental], [Breakdown], [Pre-Chorus] (hyphenated) and [Build-up] (hyphenated), none of which appear in the list above. Whether the music API errors on, ignores, or interprets an unlisted tag is undocumented. Normalise tags before passing lyrics from one endpoint to the other. Official code examples use lowercase ([verse]), so case appears not to matter.

There is no BPM, key, arrangement or climax-placement parameter. Naming a BPM inside the prompt string is an accepted convention and does influence the result, but it is a hint, not a control. Section tags are not documented to affect instrumental arrangement at all.

Phase 3: Writing the prompt

The prompt is a comma-separated list of descriptors — think of it as tagging a track.

{genre}, {subgenre}, {mood ×2-3}, {scenario}, {instrumentation}, {production}, {tempo}, {BPM}

Worked examples:

Cinematic indie folk, neoclassical, warm, nostalgic, hopeful, intimate, golden hour wedding,
felt piano, fingerpicked acoustic guitar, soft string swell, cello, brushed drums,
sparse opening building to a full emotional crescendo then gentle resolve, analog warmth,
slow tempo, 76 BPM

Synthwave, retro electro, euphoric, driving, night city drive, pulsating analog synthesizers,
gated reverb drums, neon atmosphere, 80s production, medium tempo, 110 BPM

Lo-fi hip-hop, chill, laid-back, rainy coffee shop, warm vinyl crackle, jazzy piano samples,
relaxed boom bap drums, slow tempo, 78 BPM

⚠️ When is_instrumental: true, strip every vocal descriptor from the prompt. Many stock genre strings contain warm harmonies, female vocals, choir or layered vocals — these contradict the instrumental flag. choir counts as a vocal token even though it reads as orchestral.

Deeper vocabulary — genres, BPM ranges, instrumentation, mood lexicon — lives in references/genre-style-reference.md.

Phase 4: Lyrics generation (optional)

curl -s -X POST "https://api.minimax.io/v1/lyrics_generation" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" -H "Content-Type: application/json" \
  -d '{"mode": "write_full_song", "prompt": "A melancholic ballad about lost love in a rainy city", "title": "Rain on Windows"}'

Returns song_title, style_tags, lyrics, base_resp.

💡 style_tags is a comma-separated descriptor string designed to be dropped straight into a music prompt. Even for an instrumental, one lyrics call gives you model-native style vocabulary — then discard the lyrics. Costs $0.01 per song.

Craft guidance in references/lyrics-guide.md.

Phase 5: Cover generation

One-step — pass the reference directly:

curl -s -X POST "https://api.minimax.io/v1/music_generation" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "music-cover",
       "audio_url": "https://example.com/original.mp3",
       "prompt": "Lo-fi bedroom pop, dreamy, soft vocals, ukulele, intimate, warm",
       "audio_setting": {"sample_rate": 44100, "bitrate": 256000, "format": "mp3"},
       "output_format": "url"}'

Two-step — preprocess first when you want to rewrite the lyrics. Preprocessing is free.

curl -s -X POST "https://api.minimax.io/v1/music_cover_preprocess" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "music-cover", "audio_url": "https://example.com/original.mp3"}'

Returns cover_feature_id (valid 24h), formatted_lyrics (ASR-extracted with section tags), structure_result (JSON with per-section start/end timestamps in seconds) and audio_duration. Then pass cover_feature_id + your rewritten lyrics (10–1000 chars) to music_generation.

Reference audio limits: 6 seconds – 6 minutes, ≤ 50 MB, mp3/wav/flac.

⚠️ The Files API cannot host it. /v1/files/upload has no music-related purpose value, and the music endpoints accept no file_id. Your only options are a publicly reachable audio_url or inline audio_base64 (which inflates the request ~33%). A signed object-storage URL is the clean route.

music_cover_preprocess accepts music-cover only — not music-cover-free.

Phase 6: Response handling

✅ Verified live response:

{
  "data": {
    "audio": "<hex string, OR a signed download URL when output_format=url>",
    "status": 2
  },
  "trace_id": "06c11f46...",
  "extra_info": {
    "music_duration": 160992,
    "music_sample_rate": 44100,
    "music_channel": 2,
    "bitrate": 256000,
    "music_size": 5158939
  },
  "analysis_info": null,
  "base_resp": { "status_code": 0, "status_msg": "success" }
}

Key facts, all verified:

• output_format: "url" puts a signed URL in data.audio. There is no separate audio_url field. The default hex puts hex-encoded bytes in that same field. Always set output_format explicitly so you know what you are parsing.
• The URL is signed and expires in 24 hours. It must be used whole — truncating it strips the signature and the download returns an AccessDenied XML body that will masquerade as an audio file. Always verify with ffprobe after downloading.
• extra_info.music_duration is in milliseconds (160992 = 161 s). data.status: 1 = in progress, 2 = complete.
• trace_id, extra_info and analysis_info sit at the top level, siblings of data — not nested inside it.
• Always check base_resp.status_code == 0. HTTP 200 does not imply success.

# url
jq -r '.data.audio' resp.json | xargs curl -sL -o track.mp3
# hex (default)
jq -r '.data.audio' resp.json | xxd -r -p > track.mp3
# always verify
ffprobe -v error -show_entries format=duration -of default=nw=1 track.mp3

Phase 7: Post-processing

Because length is emergent and the climax cannot be placed, fitting the track to picture happens here.

# Inspect
ffprobe -v quiet -print_format json -show_format -show_streams track.mp3

# Find the loudest moment — locates the natural crescendo to cut against
ffmpeg -i track.mp3 -af astats=metadata=1:reset=1,ametadata=print:key=lavfi.astats.Overall.RMS_level -f null - 2>&1 | grep RMS

# Trim a window and fade (e.g. 48s ending at a fade-out)
ffmpeg -i track.mp3 -ss 12 -t 48 -af "afade=t=in:d=2,afade=t=out:st=43:d=5" bed_48s.mp3

# Normalise (do this on the FINAL mix, not the bed alone)
ffmpeg -i mix.wav -af "loudnorm=I=-14:LRA=11:TP=-1.5" master.wav

# Waveform graphic
ffmpeg -i track.mp3 -filter_complex "showwavespic=s=1920x400:colors=#d97757|#ededed" wave.png

Technique for hitting a specific emotional beat: generate 2–3 takes, run the RMS scan on each, and pick the take whose natural crescendo sits nearest your target — then slide the trim window so it lands exactly. Selection plus trimming replaces the control the API does not offer.

Error codes

Rate limits: paid models 120 RPM, 20 concurrent · free variants 3 RPM.

Common failures and fixes

Supporting files

• Complete API reference — every parameter, full schemas, error codes
• Genre & style reference — genre encyclopedia, BPM ranges, instrumentation
• Lyrics writing guide — meter, rhyme, storytelling, structure