MiniMax Music Expert

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:

Rules:

• 不要一次抛出所有问题。根据用户已提供的信息，只问缺失的关键维度（通常 2-4 个问题）
• 每个问题必须带字母选项(A/B/C/...)，降低用户决策成本
• 选项末尾提供"其他"或"交给你来定"的兜底选项，避免用户被选项限制
• 如果用户的需求已经很明确（覆盖了 Type + Genre + Mood + 至少一个其他维度），可以直接进入 Step 2

示例交互：

用户: "帮我做一首关于杭州的歌" Agent: "好的！关于这首杭州之歌，我还想确认几个方面，你可以直接回复选项字母：

1. 🎵 风格：A. 中国风民谣 B. 流行 C. 古风 D. R&B E. 其他
2. 🎤 情绪：A. 温柔抒情 B. 大气磅礴 C. 欢快明朗 D. 忧伤怀旧
3. 🎶 人声：A. 温柔女声 B. 有力女声 C. 温柔男声 D. 有力男声
4. 🎭 情绪走向：A. 由浅入深慢慢推向高潮 B. 先抑后扬 C. 全程舒缓 D. 起伏交替
5. ✍️ 歌词：A. 我已有歌词 B. 我给主题你来写 C. AI自动生成

直接回复如

1A 2B 3A 4A 5B

即可！"

Step 2: Design Song Blueprint & Present Draft

This is the most important step. Do NOT write a flat prompt. First design a Song 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 (用户需求: "一首关于杭州的中国风民谣，温柔开头，副歌大气"):

🎼 **歌曲蓝图**

| 段落 | 情绪/能量 | 乐器/编曲 | 人声表现 | 制作特点 |
|------|-----------|-----------|----------|----------|
| [Intro] | 宁静悠远 ⚡① | 古筝独奏琶音 | — | 空间感大，远处水声质感 |
| [Verse 1] | 细腻叙述 ⚡② | +笛子旋律，轻拨琵琶 | 温柔低吟，呼吸感 | 亲密感，少混响 |
| [Verse 2] | 情感渐浓 ⚡③ | +二胡加入，节奏轻启 | 声线渐开，带感情 | 开始加宽声场 |
| [Pre Chorus] | 蓄势待发 ⚡⑤ | 弦乐铺底渐强，鼓点加入 | 力度上升，情绪推动 | 渐强(crescendo) |
| [Chorus] | 大气磅礴 ⚡⑧ | 全编制爆发：弦乐+鼓+笛+琵琶 | 高亢嘹亮，饱满和声 | "音墙"，宽广声场 |
| [Bridge] | 回归内省 ⚡③ | 仅钢琴+古筝 | 轻声吟唱 | 突然安静，对比反差 |
| [Chorus] | 最终爆发 ⚡⑨ | 全编制+合唱层叠 | 全力释放，高音 | 最高能量 |
| [Outro] | 渐归平静 ⚡② | 古筝回归独奏 | — | 渐弱收尾 |

⚡① ~ ⚡⑩ = energy level, 用于可视化段落间的能量变化曲线。

Blueprint design principles:

• 段落间必须有对比：相邻段落的能量/乐器/人声至少有一项明显不同
• 能量曲线要有起伏：避免全程同一能量级。典型曲线：低→中→高→低→最高→低
• Chorus 必须是能量峰值：确保副歌和主歌之间有显著的编曲差异
• Bridge 通常是"呼吸空间"：在两次 Chorus 之间提供反差

Step 2b: Derive Prompt from Blueprint

将蓝图中的信息转化为 prompt。好的 prompt 需要同时描述整体基调和段落间的动态变化。

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):

1. Determine the output file name from context (e.g.,

   ./audio/杭州之歌.mp3

   )
2. 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

--lyrics

--lyrics-optimizer true

--lyrics

3. 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:

1. Tell the user the file location and invite them to listen
2. Ask for feedback:

🎵 音乐已生成！文件保存在：`./audio/<filename>.mp3`

请试听后告诉我你的感受：
- ✅ 满意，完成
- 🔄 需要调整（请告诉我具体想改什么，比如节奏太快、想换个风格、歌词某处要改等）

3. 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:

[Verse: Rap]

Model & Mode Reference

Model Differences

is_instrumental

lyrics_optimizer

prompt

lyrics

Generation Modes

--lyrics

--prompt

--is-instrumental true

--prompt

--lyrics

--prompt

--lyrics-optimizer true

--prompt

Prompt Crafting (Best Practices)

Prompt 控制音乐的整体风格、情绪和制作方向。好的 prompt 不是扁平的属性罗列，而是描述音乐如何在段落间变化。

核心维度（必须覆盖）

1980s J-Rock

Chinese folk R&B

昭和年代Disco

92 BPM

136 BPM

140 BPM

soft airy female vocal that transitions from intimate whispering in verses to powerful soaring belting in choruses

builds from solo guzheng, adding dizi and pipa through verses, swelling to full orchestral in choruses

passionate, nostalgic, hopeful

from intimate dry verse into wide reverberant chorus, retreating to quiet bridge before final explosive chorus

进阶维度（提升精度）

dry intimate space in verses, wide reverberant arena soundscape in choruses

rock saturation

80s Minneapolis sound

modern electronic wide transients

anime theme

club/party

coffee shop BGM

no autotune

avoid heavy reverb

no trap hi-hats

Prompt 构建公式（推荐）

[整体风格 + 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], [乐器], [人声类型]

示例:

Pop,中国风R&B

Afro House,Tropical House

流行，女生，舒缓

常见用户需求 → Prompt 转换

arrangement builds from gentle opening to massive orchestral chorus with powerful brass, strings and timpani, creating an epic arena soundscape

with melodic rap in verses transitioning to anthemic singing in choruses

[Verse 1: Rap]

[Chorus: Singing]

Chinese folk pop, building from intimate solo guzheng verse to full ensemble chorus

featuring dizi (bamboo flute) as verse melody, pipa as rhythmic texture, erhu joining in bridge, full silk-bamboo ensemble in chorus

复古迪斯科风格，主歌以放克吉他切分律动为主，副歌管弦与合成器全面加入，庆典般的能量爆发

healing ambient, starting with solo piano, gradually layering soft strings and gentle pads, building warmth

--is-instrumental true

explosive intro with heavy bass and drum impact, settling into groove for verses, building back to maximum energy chorus

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)

结构标签

官方支持的 14 种标签：

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

结构标签高级用法

编号区分：用编号区分不同段落，使每段有不同表现：

[Verse 1]
街边红灯 摇曳 破了 暮色
[Verse 2]
玉米 粒粒 颗颗 都是 地道

注释标签：在标签后用冒号加注释，指导该段落的演绎方式：

[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]

段落对比编排（关键：避免歌曲单调）

核心原则：每个段落的歌词中应通过注释标签 + 括号指令明确告诉模型这一段的音乐特征，确保相邻段落之间产生对比。

完整示例（注意每个段落的括号指令如何控制乐器和能量的变化）：

[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 / 最高能量，加入合唱）
杭州 我的杭州

对比维度清单（至少变化 1-2 项）：

括号指令（关键技巧）

在歌词中使用

()

（）

乐器控制：

[Intro]
（琵琶琶音）
[Outro]
（二胡拉出一个帅气的尾音）
（鼓声重击收尾）

音效/声音设计：

(Sound of glass breaking / 玻璃破碎声)
(Phone ringing sound / 电话铃声)
(Sudden change to 8-bit game sound / 突然变成红白机音效)
(Abrupt silence / 突然安静)
(Sound of a chicken / 一声鸡叫): 咯咯哒？

人声技巧：

(Robotic Voice / 机械音)
(Super fast flow / 极快语速)
(Pitch rising higher and higher / 音调越来越高)
(Deep Voice / 深沉男声)
(Gang Vocals, Everyone shouting)
(Manic laughter)

编曲/动态：

(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)

拟声词/象声词

在歌词中直接写拟声词可产生特殊音效效果：

Boom Boom Boom!
A-Ba A-Ba A-Ba A-Ba!
Bi-bu Bi-bu Bi-bu Bi-bu (救护车音效)
Womp Womp Womp
嗡——啪!

中文空格分词（节奏控制）

中文歌词中加空格控制字词的演唱节奏和断句：

街边红灯 摇曳 破了 暮色          ← 空格控制断句节奏
半城 烟火 尽是 诱人 醇香

对比无空格版本：

街边红灯摇曳破了暮色              ← 模型自行断句，节奏不可控

双语歌词

中英混合歌词可产生跨文化效果：

霓虹灯在闪烁 (Flash, Flash)
别管现在几点钟 (Tik, Tok)
Zuo! You! Shang! Xia! (左! 右! 上! 下!)

典型歌曲结构模板

标准流行曲：

[Intro]
[Verse 1]
[Pre Chorus]
[Chorus]
[Verse 2]
[Bridge]
[Chorus]
[Outro]

EDM/舞曲：

[Intro]
[Verse 1]
[Pre-Chorus: Build Up]
[Drop / Chorus]
[Verse 2]
[Build Up]
[Drop / Chorus: Maximum Energy]
[Outro]

带 Rap 的歌曲：

[Intro]
[Verse 1: Rap]
[Pre Chorus]
[Chorus]
[Verse 2: Melodic Rap]
[Bridge]
[Chorus]
[Outro]

Script Reference

scripts/generate_music.py

scripts/utils_audio.py

Key CLI Arguments

--lyrics

--prompt

--model

music-2.5+

--is-instrumental

--lyrics-optimizer

--output

--output-format

url

hex

url

--format

mp3

wav

pcm

--sample-rate

--bitrate

--stream

--aigc-watermark

--download

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