Generate music using MiniMax Music Generation API. Default model: music-2.5+ (recommended). This skill is designed to help music novices create professional-quality music through guided interaction.
Environment Setup
export MINIMAX_MUSIC_API_KEY="your_api_key"
Agent Workflow (MUST FOLLOW)
When a user requests music creation, always follow this 4-step interactive workflow. Do NOT skip steps or jump directly to generation.
Step 1: Understand & Clarify Requirements
Analyze the user's input and identify which dimensions are already covered vs. missing. Then ask targeted follow-up questions to fill the gaps.
Dimension checklist — check which are provided, ask about the rest. Each question MUST provide lettered options (A/B/C/...) for the user to choose from:
| Dimension | Question with options |
|---|---|
| Type | "What type of song is this? A. A song with vocals B. Instrumental/background music (no vocals) C. Humming/chanting (melodic vocals without lyrics)" |
| Genre/Style | "What music style do you like? A. Pop B. Rock C. Folk D. Electronic/EDM E. Hip-hop/Rap F. Jazz G. Ancient style/Chinese style H. R&B I. Other (please describe)" |
| Mood/Emotion | "What emotion do you want to convey? A. Cheerful and lively B. Gentle and lyrical C. Sorrowful and reflective D. Passionate and fiery E. Healing and relaxing F. Grand/epic G. Romantic and sweet H. Other (please describe)" |
| Scene/Use case | "What scenario is this song intended for? A. Short video/Vlog BGM B. Personal collection/gift C. Game/animation D. Cafe/restaurant E. Wedding/celebration F. Sports/fitness G. Other (please describe)" |
| Tempo/Rhythm | "Rhythm preference? A. Slow and lyrical (60-80 BPM) B. Medium and soothing (80-110 BPM) C. Medium-fast and light (110-130 BPM) D. Fast and dynamic (130-160 BPM) E. Not sure, leave it to you" |
| Instruments | "Any instruments you want? A. Piano-led B. Guitar (acoustic/electric guitar) C. Chinese traditional instruments (dizi/pipa/guzheng/erhu) D. Strings (violin/cello) E. Electronic synthesizer F. Wind instruments (saxophone/trumpet) G. Not sure, match according to the style H. Other (please describe)" |
| Vocal | "Vocals? (skip for instrumental) A. Gentle female voice B. Powerful female voice C. Gentle male voice D. Powerful male voice E. Husky/hoarse voice F. Not sure, leave it to you" |
| Lyrics | "Lyrics? (skip for instrumental) A. I already have lyrics B. I'll give a theme/keywords, you write them C. Let AI generate everything automatically" |
| Dynamic Arc | "Emotional progression of the song? A. From shallow to deep, gradually building to a climax B. Explosive from the start, high energy throughout C. Restrained first, then rising (quiet intro -> explosive chorus) D. Alternating ups and downs (quiet -> explosive -> quiet -> bigger explosion) E. Steady and soothing throughout F. Not sure, leave the arrangement to you" |
| Reference | "Any references you like? (optional) A. Yes, similar to a certain singer/song (please specify) B. No particular reference" |
Rules:
- Don't throw out all the questions at once. Based on the information the user has already provided, only ask aboutmissing key dimensions(usually 2-4 questions)
- Each questionmust include letter options(A/B/C/...), to reduce the user's decision cost
- Provide a fallback option like "Other" or "You decide" at the end of the options, so users are not constrained by the choices
- If the user's needs are already very clear (covering Type + Genre + Mood + at least one other dimension), you can proceed directly to Step 2
Example interaction:
User: "Help me make a song about Hangzhou" Agent: "Sure! About this song of Hangzhou, I'd like to confirm a few more aspects. You can just reply with the option letters:
- 🎵 Style：A. Chinese-style folk B. Pop C. Ancient style D. R&B E. Other
- 🎤 Mood：A. Gentle and lyrical B. Grand and majestic C. Cheerful and bright D. Sorrowful and nostalgic
- 🎶 Vocals：A. Gentle female voice B. Powerful female voice C. Gentle male voice D. Powerful male voice
- 🎭 Emotional progression：A. Gradually build from subtle to climax B. Suppress first then rise C. Soothing throughout D. Alternating ups and downs
- ✍️ Lyrics：A. I already have lyrics B. I'll give the theme, you write them C. AI auto-generate
Just reply with something like
1A 2B 3A 4A 5Band that's it!"
Step 2: Design Song Blueprint & Present Draft
This is the most important step. Do NOT write a flat prompt. First design a Song Blueprint (section blueprint) that plans each section's musical characteristics, then derive the prompt and lyrics from it.
Step 2a: Create Song Blueprint
Based on gathered requirements, plan the section-by-section musical journey. Each section should have distinct characteristics.
Blueprint format:
🎼 **歌曲蓝图**
| 段落 | 情绪/能量 | 乐器/编曲 | 人声表现 | 制作特点 |
|------|-----------|-----------|----------|----------|
| [Intro] | ... | ... | ... | ... |
| [Verse 1] | ... | ... | ... | ... |
| [Pre Chorus] | ... | ... | ... | ... |
| [Chorus] | ... | ... | ... | ... |
| ... | ... | ... | ... | ... |
Blueprint example (user request: "a Chinese-style folk song about Hangzhou, gentle opening, grand chorus"):
🎼 **歌曲蓝图**
| 段落 | 情绪/能量 | 乐器/编曲 | 人声表现 | 制作特点 |
|------|-----------|-----------|----------|----------|
| [Intro] | 宁静悠远 ⚡① | 古筝独奏琶音 | — | 空间感大，远处水声质感 |
| [Verse 1] | 细腻叙述 ⚡② | +笛子旋律，轻拨琵琶 | 温柔低吟，呼吸感 | 亲密感，少混响 |
| [Verse 2] | 情感渐浓 ⚡③ | +二胡加入，节奏轻启 | 声线渐开，带感情 | 开始加宽声场 |
| [Pre Chorus] | 蓄势待发 ⚡⑤ | 弦乐铺底渐强，鼓点加入 | 力度上升，情绪推动 | 渐强(crescendo) |
| [Chorus] | 大气磅礴 ⚡⑧ | 全编制爆发：弦乐+鼓+笛+琵琶 | 高亢嘹亮，饱满和声 | "音墙"，宽广声场 |
| [Bridge] | 回归内省 ⚡③ | 仅钢琴+古筝 | 轻声吟唱 | 突然安静，对比反差 |
| [Chorus] | 最终爆发 ⚡⑨ | 全编制+合唱层叠 | 全力释放，高音 | 最高能量 |
| [Outro] | 渐归平静 ⚡② | 古筝回归独奏 | — | 渐弱收尾 |
⚡① ~ ⚡⑩ = energy level, used to visualize the energy change curve between sections.
Blueprint design principles:
- There must be contrast between sections: adjacent sections must differ noticeably in at least one of energy/instruments/vocals
- The energy curve must have rises and falls: avoid the same energy level throughout. Typical curve: low→medium→high→low→highest→low
- Chorus must be the energy peak: ensure a significant arrangement difference between the chorus and the verse
- Bridge is usually a "breathing space": provide contrast between two Choruses
Step 2b: Derive Prompt from Blueprint
Transform the information in the blueprint into a prompt. A good prompt needs todescribe both the overall tone and the dynamic changes between sections。
Prompt construction formula:
[整体风格/BPM] + [人声描述 + 段落间变化] + [核心乐器] + [动态弧线描述] + [声场/制作特点]
Example (based on the 杭州 blueprint above):
A poetic and cinematic Chinese folk pop at 78 BPM, featuring a tender female vocal that transitions from intimate whispering in the verses to powerful soaring belting in the choruses with layered harmonies. The arrangement builds from a solo guzheng intro, gradually adding dizi (bamboo flute), pipa, and erhu through the verses, swelling to a full orchestral "wall of sound" with strings and percussion in the choruses, before retreating to a quiet guzheng outro. The production shifts from a dry, intimate space in the verses to a wide, reverberant arena soundscape in the choruses.
Key: The prompt explicitly describes what changes between sections — not just a flat list of attributes.
Step 2c: Write Lyrics with Section Directions
Write lyrics using annotated structure tags and parenthetical directions to reinforce the blueprint:
[Intro]
（古筝琶音，空灵悠远）
[Verse 1: 温柔低吟]
西湖 烟雨 朦胧了 谁的眼
断桥 残雪 化作 心头的暖
[Verse 2: 情感渐浓]
（笛声加入，轻柔的鼓点）
三潭 映月 点亮了 千年夜
灵隐 钟声 唤醒 梦中的蝶
[Pre Chorus: 情绪递进]
（弦乐渐强 / Rising strings）
这片土地 承载了 多少故事
每一寸 都是 我的根
[Chorus: 大气爆发]
（Full band kicks in / 全编制爆发）
杭州 我的杭州
你是 我心中 永远的歌
...
[Bridge: 回归平静]
（Music drops to piano and guzheng only / 仅剩钢琴与古筝）
闭上眼 你还在那里
...
[Chorus: 最终高潮]
（Maximum energy / 最高能量，加入合唱层）
杭州 我的杭州
...
[Outro: 渐弱收尾]
（古筝独奏，渐弱 / Guzheng solo, fading out）
Step 2d: Present Complete Draft
Combine all above into the final presentation:
📋 **生成方案**
**模式**：Standard Song
🎼 **歌曲蓝图**：
[the blueprint table]
**Prompt**：
[the full prompt — with dynamic arc description]
**歌词**：
[the full lyrics — with annotated tags and parenthetical directions]
**说明**：[1-2 sentences on creative choices]
---
请确认是否满意，或告诉我需要调整的地方（如某段落的情绪、乐器、歌词等）。
Rules:
- Always create the blueprint first, then derive prompt and lyrics from it
- Prompt must describe section transitions, not just a flat style
- Lyrics must use annotated structure tags (e.g.,
[Chorus: 大气爆发]) and parenthetical directions (e.g.,（Full band kicks in）) to control each section's sound - Show the complete blueprint, prompt, and lyrics — never hide details
- Wait for explicit user confirmation before proceeding to Step 3
Step 3: Generate Music
After user confirms (or after applying their revisions and getting re-confirmation):
- Determine the output file name from context (e.g.,
./audio/杭州之歌.mp3) - Run the generation command:
python scripts/generate_music.py \
--lyrics "<final_lyrics>" \
--prompt "<final_prompt>" \
--output ./audio/<filename>.mp3
For instrumental mode, add --is-instrumental true and omit --lyrics.
For auto-lyrics mode, add --lyrics-optimizer true and omit --lyrics.
- Inform user that generation is in progress (API call may take 30-120 seconds)
Step 4: Post-Generation Feedback
After the audio file is generated:
- Tell the user the file location and invite them to listen
- Ask for feedback:
🎵 音乐已生成！文件保存在：`./audio/<filename>.mp3`
请试听后告诉我你的感受：
- ✅ 满意，完成
- 🔄 需要调整（请告诉我具体想改什么，比如节奏太快、想换个风格、歌词某处要改等）
- If user requests changes:
- Analyze what needs modification (prompt, lyrics, or both)
- Return to Step 2 with the revised draft
- Repeat until user is satisfied
Common revision patterns:
| User feedback | Action |
|---|---|
| "The rhythm is too fast/too slow" | Adjust BPM in prompt |
| "The style is wrong" | Revise genre/style keywords in prompt |
| "I don't like the vocals" | Adjust vocal description in prompt |
| "A certain section of the lyrics needs to be changed" | Modify specific lyrics section |
| "I want to add some rap" | Add [Verse: Rap] section in lyrics, update prompt |
| "The instruments are wrong" | Revise instrument list in prompt |
| "It feels too monotonous" | Add dynamic arc description, enrich structure tags with annotations |
| "I want more layering" | Add parenthetical production directions in lyrics, describe section transitions in prompt |
Model & Mode Reference
Model Differences
| Feature | music-2.5 | music-2.5+ (recommended) |
|---|---|---|
| Standard song (with lyrics) | ✅ lyrics required | ✅ lyrics required |
Pure music (is_instrumental) |
❌ not supported | ✅ prompt required, lyrics optional |
Auto-generate lyrics (lyrics_optimizer) |
✅ | ✅ |
prompt field |
Optional [0, 2000] chars | Optional for songs; Required [1, 2000] for instrumental |
lyrics field |
Required [1, 3500] chars | Required for songs; optional for instrumental |
Generation Modes
| Mode | When to use | Key Args |
|---|---|---|
| Standard Song | User has/wants lyrics + singing | --lyrics + --prompt |
| Pure Music | "pure music" / "instrumental" / "background music" / "no vocals" | --is-instrumental true + --prompt |
| Chanting | "humming" / "chanting" / "humming" | --lyrics (syllables) + --prompt |
| Auto Lyrics | User wants AI to write lyrics | --lyrics-optimizer true + --prompt |
Prompt Crafting (Best Practices)
The prompt controls the overall style, mood, and production direction of the music.A good prompt is not a flat list of attributes, but a description of how the music changes between sections.
Core dimensions (must be covered)
| Dimension | Description | Example |
|---|---|---|
| Genre + Era/Region | Specific style + era or region | 1980s J-Rock, Chinese folk R&B, 昭和年代Disco |
| BPM | Clear tempo/BPM | 92 BPM, 136 BPM, 140 BPM |
| Vocal + Transition | Gender, timbre + how it changes between sections | soft airy female vocal that transitions from intimate whispering in verses to powerful soaring belting in choruses |
| Instruments + Layering | Core instruments + How each section layers in/exits | builds from solo guzheng, adding dizi and pipa through verses, swelling to full orchestral in choruses |
| Mood | 2-3 emotion descriptor words | passionate, nostalgic, hopeful |
| Dynamic Arc | Energy evolution curve between sections | from intimate dry verse into wide reverberant chorus, retreating to quiet bridge before final explosive chorus |
Advanced dimensions (improving precision)
| Dimension | Description | Example |
|---|---|---|
| Production/Mix | Mix style,spatial changes between sections | dry intimate space in verses, wide reverberant arena soundscape in choruses |
| Sound Design | Acoustic characteristics of a specific style | rock saturation, 80s Minneapolis sound, modern electronic wide transients |
| Scene/Use case | Use case | anime theme, club/party, coffee shop BGM |
| Avoid | Excluded elements | no autotune, avoid heavy reverb, no trap hi-hats |
Prompt construction formula (recommended)
[整体风格 + BPM] + [人声描述 + 段落间变化] + [乐器编排 + 段落间叠加/退出] + [动态弧线] + [声场/制作变化]
English template (highest precision):
A [mood] [BPM] [genre] track featuring a [vocal] that [transitions from X in verses to Y in choruses], with arrangement building from [sparse intro instruments] through [verse additions] to [full chorus instrumentation], [bridge contrast], before [final chorus climax]. Production shifts from [verse sound] to [chorus sound].
Example:
A poetic and cinematic Chinese folk pop at 78 BPM, featuring a tender female vocal that transitions from intimate whispering in the verses to powerful soaring belting in the choruses with layered harmonies. The arrangement builds from a solo guzheng intro, gradually adding dizi, pipa, and erhu through the verses, swelling to a full orchestral "wall of sound" with strings and percussion in the choruses, retreating to quiet guzheng in the bridge, before a final explosive chorus with choir layers. Production shifts from dry intimate space in verses to wide reverberant arena soundscape in choruses.
Chinese description template:
78 BPM 的诗意中国风民谣，温柔女声演唱。主歌低吟浅唱、气息感十足，到副歌转为高亢嘹亮的全力释放。编曲从古筝独奏开头，主歌逐渐加入笛子、琵琶，到副歌时弦乐、鼓点全编制爆发形成"音墙"，Bridge回归古筝独奏的宁静，尾声再次爆发后古筝收尾渐弱。
Simple tag template (for straightforward requests):
[风格], [情绪], [BPM], [乐器], [人声类型]
Example: Pop,中国风R&B / Afro House,Tropical House / 流行，女生，舒缓
Common user needs → Prompt conversion
| User need | Prompt direction |
|---|---|
| "The main melody is grand and majestic" | prompt describes the dynamic arc: arrangement builds from gentle opening to massive orchestral chorus with powerful brass, strings and timpani, creating an epic arena soundscape |
| "Add a rap section to the chorus" | prompt: with melodic rap in verses transitioning to anthemic singing in choruses; lyrics: [Verse 1: Rap] + [Chorus: Singing] |
| "Praising my hometown · Hangzhou" | The theme is in the lyrics; the prompt describes style + dynamics: Chinese folk pop, building from intimate solo guzheng verse to full ensemble chorus |
| "Use folk instruments such as dizi and pipa" | prompt describes how the instruments are distributed: featuring dizi (bamboo flute) as verse melody, pipa as rhythmic texture, erhu joining in bridge, full silk-bamboo ensemble in chorus |
| "Retro disco" | 复古迪斯科风格，主歌以放克吉他切分律动为主，副歌管弦与合成器全面加入，庆典般的能量爆发 |
| "Healing-style light music" | healing ambient, starting with solo piano, gradually layering soft strings and gentle pads, building warmth + --is-instrumental true |
| "The beginning should be explosive" | explosive intro with heavy bass and drum impact, settling into groove for verses, building back to maximum energy chorus |
| "I want it to have a sense of layering" | prompt explicitly describes the instrument additions and removals in each section: verse: acoustic guitar + light drums → pre-chorus: add synth pads + bass → chorus: full band with layered vocals → bridge: strip to piano only |
Lyrics Writing (Best Practices)
Structure tags
The 14 officially supported tags:
[Intro] [Verse] [Pre Chorus] [Chorus] [Post Chorus]
[Bridge] [Interlude] [Outro] [Transition] [Break]
[Hook] [Build Up] [Inst] [Solo]
Advanced usage of structure tags
Numbering for distinction: Use numbering to distinguish different sections so that each section has a different performance:
[Verse 1]
街边红灯 摇曳 破了 暮色
[Verse 2]
玉米 粒粒 颗颗 都是 地道
Annotation tags: Add an annotation after the tag with a colon to guide how that section is performed:
[Intro Hook: Heavy Hanmai Style & 808 Drop]
[Verse 1: Aggressive Rap]
[Pre-Chorus: Build Up]
[Chorus: Maximum Energy]
[Bridge: Comical Trombone Solo]
[Outro: Speed Up]
[Drop / Chorus]
Section contrast arrangement (key: avoid making the song monotonous)
Core principle: In the lyrics of each section, use annotation tags + parenthetical instructions to clearly tell the model the musical characteristics of that section, ensuring contrast between adjacent sections.
Complete example(Note how the parenthetical instructions in each section control changes in instruments and energy):
[Intro]
（古筝独奏琶音，空旷悠远）
[Verse 1: 温柔叙述]
（轻柔的笛子旋律加入，亲密的混音空间）
西湖 烟雨 朦胧了 谁的眼
断桥 残雪 化作 心头的暖
[Pre Chorus: 情绪递进]
（弦乐渐强，鼓点轻启 / Strings building, drums entering）
这片土地 承载了 多少故事
[Chorus: 全力爆发]
（Full band kicks in / 全编制爆发，宽广音场）
杭州 我的杭州
你是我心中 永远的歌
[Bridge: 突然安静]
（Music drops to piano only / 仅剩钢琴，安静的呼吸空间）
闭上眼 你还在那里
[Chorus: 最终高潮]
（Maximum energy, choir layers added / 最高能量，加入合唱）
杭州 我的杭州
Contrast dimension checklist(change at least 1-2 items):
| Dimension | Verse (low energy) | Chorus (high energy) |
|---|---|---|
| Number of instruments | 1-2 | Full arrangement |
| Soundstage width | Intimate/dry | Wide/reverberant |
| Vocal intensity | Humming/soft singing | High-pitched/resonant |
| Rhythmic density | Sparse/no drums | Dense/strong drumbeats |
| Dynamic level | Soft (p/mp) | Strong (f/ff) |
Parenthetical instructions (key technique)
In the lyrics, use () or （） to insert performance/sound effect/vocal instructions, and the model will try to execute them:
Instrument control:
[Intro]
（琵琶琶音）
[Outro]
（二胡拉出一个帅气的尾音）
（鼓声重击收尾）
Sound effects/sound design:
(Sound of glass breaking / 玻璃破碎声)
(Phone ringing sound / 电话铃声)
(Sudden change to 8-bit game sound / 突然变成红白机音效)
(Abrupt silence / 突然安静)
(Sound of a chicken / 一声鸡叫): 咯咯哒？
Vocal techniques:
(Robotic Voice / 机械音)
(Super fast flow / 极快语速)
(Pitch rising higher and higher / 音调越来越高)
(Deep Voice / 深沉男声)
(Gang Vocals, Everyone shouting)
(Manic laughter)
Arrangement/dynamics:
(Heavy Bass kicks in / 重低音爆发)
(Rising synth / 情绪递进)
(Music stops briefly, only Trombone playing funny melody)
(BPM increases significantly to Happy Hardcore speed)
(Fading out with beat / 渐弱)
(Maximum Volume / 最大音量)
(Beat returns - Manyao Style)
Onomatopoeia/imitatives
Writing onomatopoeia directly in the lyrics can produce special sound effects:
Boom Boom Boom!
A-Ba A-Ba A-Ba A-Ba!
Bi-bu Bi-bu Bi-bu Bi-bu (救护车音效)
Womp Womp Womp
嗡——啪!
Chinese space-based word segmentation (rhythm control)
Adding spaces in Chinese lyrics controls the singing rhythm and phrasing of words:
街边红灯 摇曳 破了 暮色 ← 空格控制断句节奏
半城 烟火 尽是 诱人 醇香
Compare the no-space version:
街边红灯摇曳破了暮色 ← 模型自行断句，节奏不可控
Bilingual lyrics
Mixed Chinese-English lyrics can create a cross-cultural effect:
霓虹灯在闪烁 (Flash, Flash)
别管现在几点钟 (Tik, Tok)
Zuo! You! Shang! Xia! (左! 右! 上! 下!)
Typical song structure template
Standard pop song:
[Intro]
[Verse 1]
[Pre Chorus]
[Chorus]
[Verse 2]
[Bridge]
[Chorus]
[Outro]
EDM/dance music:
[Intro]
[Verse 1]
[Pre-Chorus: Build Up]
[Drop / Chorus]
[Verse 2]
[Build Up]
[Drop / Chorus: Maximum Energy]
[Outro]
Songs with Rap:
[Intro]
[Verse 1: Rap]
[Pre Chorus]
[Chorus]
[Verse 2: Melodic Rap]
[Bridge]
[Chorus]
[Outro]
Script Reference
| File | Purpose |
|---|---|
scripts/generate_music.py |
Main CLI: lyrics + prompt → audio file |
scripts/utils_audio.py |
Hex decoding, file saving, URL download |
Key CLI Arguments
| Arg | Default | Description |
|---|---|---|
--lyrics |
— | Song lyrics (required unless instrumental or lyrics-optimizer) |
--prompt |
— | Style/scene description (required for instrumental) |
--model |
music-2.5+ |
Model name |
--is-instrumental |
false | Pure music mode (music-2.5+ only) |
--lyrics-optimizer |
false | Auto-generate lyrics from prompt |
--output |
— | Output file path (required) |
--output-format |
url |
Response format: hex or url |
--format |
— | Audio codec: mp3, wav, pcm |
--sample-rate |
— | 16000 / 24000 / 32000 / 44100 |
--bitrate |
— | 32000 / 64000 / 128000 / 256000 |
--stream |
false | Streaming mode (hex only) |
--aigc-watermark |
false | Append watermark (non-stream only) |
--download |
false | Download when output-format=url |
API Payload Quick Reference
Standard Song:
{
"model": "music-2.5+",
"prompt": "indie folk, melancholic",
"lyrics": "[Verse]\n街灯微亮晚风轻抚\n影子拉长独自漫步\n[Chorus]\n推开木门香气弥漫",
"audio_setting": { "sample_rate": 44100, "bitrate": 256000, "format": "mp3" }
}
Pure Music (music-2.5+ only):
{
"model": "music-2.5+",
"prompt": "coffee shop, ambient, relaxing, piano",
"is_instrumental": true
}
Auto Lyrics:
{
"model": "music-2.5+",
"prompt": "upbeat pop, summer vibes",
"lyrics_optimizer": true
}
For full API details, see references/minimax_music_api.md.