minimax-music-gen
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseMiniMax Music Generation Skill
MiniMax 音乐生成技能
Generate songs (vocal or instrumental) using the MiniMax Music API. Supports two creation
modes: Basic (one-sentence-in, song-out) and Advanced Control (edit lyrics, refine
prompt, plan before generating).
使用 MiniMax Music API 生成歌曲(带人声或器乐版)。支持两种创作模式:基础版(输入一句话即可生成歌曲)和强控制版(生成前可编辑歌词、优化提示词、调整创作规划)。
Prerequisites
前置条件
-
Credentials: Set the following environment variables:
- — your MiniMax API key
MINIMAX_API_KEY - — your MiniMax Group ID
MINIMAX_GROUP_ID
The scripts also support reading fromand~/.minimax_api_keyfiles as a fallback.~/.minimax_group_idTo check if credentials are configured:bash[ -n "$MINIMAX_API_KEY" ] && echo "✅ Credentials OK" || echo "❌ MINIMAX_API_KEY not set"⚠️ SECURITY: NEVER do any of the following:- — prints the key to terminal
echo $MINIMAX_API_KEY - — exposes the full API key
cat ~/.minimax_api_key - Any command that outputs credential values to stdout/stderr
-
Python 3.8+ (scripts use only stdlib — no pip install needed).
-
or
ffplayormpv(macOS) for local playback. The script auto-detects.afplay
-
凭证配置:设置以下环境变量:
- — 你的 MiniMax API 密钥
MINIMAX_API_KEY - — 你的 MiniMax 分组ID
MINIMAX_GROUP_ID
脚本也支持 fallback 从和~/.minimax_api_key文件读取配置。~/.minimax_group_id检查凭证是否配置成功的命令:bash[ -n "$MINIMAX_API_KEY" ] && echo "✅ 凭证配置正常" || echo "❌ 未设置 MINIMAX_API_KEY"⚠️ 安全提示:绝对不要执行以下操作:- — 会将密钥打印到终端
echo $MINIMAX_API_KEY - — 会暴露完整的API密钥
cat ~/.minimax_api_key - 任何会将凭证值输出到标准输出/标准错误的命令
-
Python 3.8+(脚本仅使用标准库,无需pip安装依赖)。
-
本地播放需要安装、
ffplay或 macOS 自带的mpv,脚本会自动检测可用播放器。afplay
APIs Used
使用的API
This skill uses two MiniMax API endpoints in a pipeline:
-
Lyrics Generation —
POST /v1/lyrics_generation- Base URL: (overseas) or
https://api.minimax.io(domestic)https://api.minimaxi.com - Scripts auto-detect the correct domain based on the user's API key
- Generates song lyrics from a natural language description
- Mode:
write_full_song - Used automatically for vocal tracks when the user hasn't provided lyrics
- Script:
scripts/generate_lyrics.py
- Base URL:
-
Music Generation —
POST /v1/music_generation- Base URL: (overseas) or
https://api.minimax.io(domestic)https://api.minimaxi.com - Scripts auto-detect the correct domain based on the user's API key
- Generates the actual audio (MP3) from a prompt + optional lyrics
- Model: (fallback:
music-2.6-free), cover:music-2.6(fallback:music-cover-free)music-cover - Supports: (true/false),
is_instrumentalheaderbedrock_lane: cover - Script:
scripts/generate_music.py
- Base URL:
Pipeline: For vocal tracks, the typical flow is:
User description → [Lyrics API] → lyrics → [Music API + prompt] → MP3For instrumental tracks, the lyrics step is skipped entirely.
该技能按流水线调用两个MiniMax API接口:
-
歌词生成 —
POST /v1/lyrics_generation- 基础地址:(海外)或
https://api.minimax.io(国内)https://api.minimaxi.com - 脚本会根据用户的API密钥自动检测正确的域名
- 根据自然语言描述生成歌曲歌词
- 模式:
write_full_song - 用户未提供歌词时,会自动调用该接口生成人声歌曲的歌词
- 对应脚本:
scripts/generate_lyrics.py
- 基础地址:
-
音乐生成 —
POST /v1/music_generation- 基础地址:(海外)或
https://api.minimax.io(国内)https://api.minimaxi.com - 脚本会根据用户的API密钥自动检测正确的域名
- 根据提示词+可选歌词生成实际音频(MP3格式)
- 模型:( fallback 为
music-2.6-free),翻唱模式使用music-2.6( fallback 为music-cover-free)music-cover - 支持参数:(true/false)、
is_instrumental请求头bedrock_lane: cover - 对应脚本:
scripts/generate_music.py
- 基础地址:
流水线逻辑:人声歌曲的典型生成流程为:
用户描述 → [歌词生成API] → 歌词 → [音乐生成API + 提示词] → MP3文件纯音乐生成会完全跳过歌词生成步骤。
Storage
存储规则
All generated music is saved to . Create the directory if it doesn't
exist. Files are named with a timestamp and a short slug derived from the prompt:
~/Music/minimax-gen/YYYYMMDD_HHMMSS_<slug>.mp3所有生成的音乐都会保存到 目录下,目录不存在时会自动创建。文件命名格式为时间戳+提示词衍生的短标识:
~/Music/minimax-gen/YYYYMMDD_HHMMSS_<短标识>.mp3Workflow
工作流程
Language Detection
语言检测
Detect the user's language from their message at the start of the session:
- Chinese (中文) → Set — all interactions in Chinese, generate Chinese lyrics
LANG=zh - English → Set — all interactions in English, generate English lyrics
LANG=en
IMPORTANT — Lyrics language rule:
- Default lyrics language = user's language. 用户说中文 → 生成中文歌词。User speaks English → English lyrics.
- Only generate a different language if the user explicitly asks (e.g., "给我写首英文歌", "write Chinese lyrics").
- The passed to
--promptmust be written in the target lyrics language — if generating Chinese lyrics, write the prompt in Chinese. The API uses prompt language to determine output language.generate_lyrics.py
Pass to ALL script invocations throughout the workflow.
Respond to the user in their detected language. Use the matching template below.
--lang $LANG会话开始时先从用户消息中检测用户使用的语言:
- 中文 → 设置 — 所有交互使用中文,生成中文歌词
LANG=zh - 英文 → 设置 — 所有交互使用英文,生成英文歌词
LANG=en
重要提示——歌词语言规则:
- 默认歌词语言 = 用户使用的语言。用户说中文 → 生成中文歌词。用户说英文 → 生成英文歌词。
- 仅当用户明确要求时才生成其他语言的歌词(例如:"给我写首英文歌"、"write Chinese lyrics")。
- 传递给 的
generate_lyrics.py参数必须使用目标歌词语言编写——如果要生成中文歌词,提示词就用中文。API会根据提示词的语言判断输出语言。--prompt
整个工作流中所有脚本调用都需要传递 参数。使用检测到的语言回复用户,匹配使用下方对应的模板。
--lang $LANGStep 0: Detect Language & Intent
步骤0:检测语言与意图
Detect the user's language and respond in the same language throughout. Parse their message
to determine:
- Song category: vocal (人声音乐), instrumental (纯音乐), or cover
- Creation mode preference: did they provide detailed requirements (→ Advanced) or a casual one-liner (→ Basic)?
If ambiguous, ask using this decision tree:
If LANG=zh:
Q1: 你想要哪种类型?
- 🎤 人声音乐(有歌词演唱)
- 🎵 纯音乐(无人声)
- 🎧 Cover(翻唱风格)
Q2: 创作模式?
- ⚡ 基础版 — 一句话描述,自动搞定
- 🎛️ 强控制版 — 自己调歌词、prompt、风格If LANG=en:
Q1: What type of music?
- 🎤 Vocal (with lyrics)
- 🎵 Instrumental (no vocals)
- 🎧 Cover
Q2: Creation mode?
- ⚡ Basic — one-line description, auto-generate
- 🎛️ Advanced — edit lyrics, refine prompt, planIf the user gives a clear one-liner like "帮我生成一首悲伤的钢琴曲", skip the questions —
infer instrumental + basic mode and proceed.
检测用户使用的语言,全程使用同一种语言回复。解析用户消息判断以下信息:
- 歌曲类型:人声音乐、纯音乐(器乐)、翻唱
- 创作模式偏好:用户是否提供了详细要求(→ 强控制版)还是随意的一句话需求(→ 基础版)?
如果信息不明确,使用以下决策树询问用户:
当LANG=zh时:
Q1: 你想要哪种类型?
- 🎤 人声音乐(有歌词演唱)
- 🎵 纯音乐(无人声)
- 🎧 Cover(翻唱风格)
Q2: 创作模式?
- ⚡ 基础版 — 一句话描述,自动搞定
- 🎛️ 强控制版 — 自己调歌词、prompt、风格当LANG=en时:
Q1: What type of music?
- 🎤 Vocal (with lyrics)
- 🎵 Instrumental (no vocals)
- 🎧 Cover
Q2: Creation mode?
- ⚡ Basic — one-line description, auto-generate
- 🎛️ Advanced — edit lyrics, refine prompt, plan如果用户给出了清晰的一句话需求,比如"帮我生成一首悲伤的钢琴曲",则跳过询问,直接推断为纯音乐+基础模式继续流程。
Step 1: Basic Mode
步骤1:基础模式
Goal: User provides a short description → skill auto-generates everything → call API.
-
Expand the description into a prompt: Take the user's one-liner and expand it into a rich music prompt. Readfor the style vocabulary and prompt structure. The music generation prompt must match the user's language (LANG):
references/prompt_guide.md- When LANG=zh, write the prompt in Chinese
- When LANG=en, write the prompt in English
Follow this pattern:# LANG=zh example: 一首 [情绪] [BPM 可选] 的 [曲风] 歌曲,[人声描述],关于 [主题/叙事], [氛围/场景],[乐器和编曲元素]。 # LANG=en example: A [mood] [BPM optional] [genre] song, featuring [vocal description], about [narrative/theme], [atmosphere], [key instruments and production]. -
Generate lyrics (if vocal): Call the MiniMax Lyrics API to auto-generate lyrics. Run the lyrics script:bash
python3 ~/.claude/skills/minimax-music-gen/scripts/generate_lyrics.py \ --prompt "<lyrics prompt in TARGET LANGUAGE>" \ --lang $LANG \ --output /tmp/lyrics_draft.txtThe API endpoint is(domain auto-detected) with mode/v1/lyrics_generation. The prompt should be a vivid description of the song's theme, mood, and story — written in the target lyrics language.write_full_songChinese lyrics example (LANG=zh):- User says "写首关于夏天海边的情歌"
- Lyrics prompt: "一首关于夏天海边的甜蜜情歌,阳光沙滩,海浪声中牵手漫步,初恋般的心动与美好"
English lyrics example (LANG=en):- User says "write a love song about the beach"
- Lyrics prompt: "A cheerful love song about a summer day at the beach, with warm sunshine, ocean waves, and the joy of being with someone special"
The API returns lyrics with section markers like,[verse], etc. If the returned lyrics lack section markers, add them automatically following this structure:[chorus][verse] — 4 lines [chorus] — 4 lines [verse] — 4 lines [chorus] — 4 lines [outro] — 2 linesFallback: If the lyrics API fails or returns low-quality results, generate lyrics directly using your own capabilities. Keep lines rhythmically consistent (similar syllable count per line within a section). Avoid clichés. -
Show the user a preview before generating:If LANG=zh:
🎵 即将为你生成: 类型:人声音乐 Prompt:独立民谣, 忧郁, 内省, 原声吉他, 温柔女声, 深夜独处 歌词: [verse] ... 确认生成?(直接回车确认,或告诉我要改什么)If LANG=en:🎵 About to generate: Type: Vocal Prompt: indie folk, melancholy, acoustic guitar, gentle female voice Lyrics: [verse] ... Confirm? (press enter to confirm, or tell me what to change) -
Call the API: Runwith the constructed parameters.
scripts/generate_music.py
目标:用户提供简短描述 → 技能自动完成所有配置 → 调用API生成。
-
将描述扩展为提示词:将用户的一句话需求扩展为丰富的音乐提示词。可参考中的风格词汇和提示词结构。音乐生成提示词必须和用户使用的语言(LANG)匹配:
references/prompt_guide.md- LANG=zh时,提示词用中文编写
- LANG=en时,提示词用英文编写
遵循以下模板:# LANG=zh示例: 一首 [情绪] [可选BPM] 的 [曲风] 歌曲,[人声描述],关于 [主题/叙事], [氛围/场景],[乐器和编曲元素]。 # LANG=en示例: A [mood] [BPM optional] [genre] song, featuring [vocal description], about [narrative/theme], [atmosphere], [key instruments and production]. -
生成歌词(人声歌曲需要):调用MiniMax歌词API自动生成歌词。执行歌词生成脚本:bash
python3 ~/.claude/skills/minimax-music-gen/scripts/generate_lyrics.py \ --prompt "<目标语言的歌词提示词>" \ --lang $LANG \ --output /tmp/lyrics_draft.txtAPI接口为(域名自动检测),模式为/v1/lyrics_generation。提示词需要是对歌曲主题、情绪、故事的生动描述,使用目标歌词语言编写。write_full_song中文歌词示例(LANG=zh):- 用户需求:"写首关于夏天海边的情歌"
- 歌词提示词:"一首关于夏天海边的甜蜜情歌,阳光沙滩,海浪声中牵手漫步,初恋般的心动与美好"
英文歌词示例(LANG=en):- 用户需求:"write a love song about the beach"
- 歌词提示词:"A cheerful love song about a summer day at the beach, with warm sunshine, ocean waves, and the joy of being with someone special"
API返回的歌词会带有、[verse]等段落标记。如果返回的歌词缺少段落标记,自动按照以下结构添加:[chorus][verse] — 4行 [chorus] — 4行 [verse] — 4行 [chorus] — 4行 [outro] — 2行降级方案:如果歌词API调用失败或返回结果质量过低,直接使用自身能力生成歌词。保持每行节奏一致(同一段落内每行音节数相近),避免陈词滥调。 -
生成前向用户展示预览:当LANG=zh时:
🎵 即将为你生成: 类型:人声音乐 Prompt:独立民谣, 忧郁, 内省, 原声吉他, 温柔女声, 深夜独处 歌词: [verse] ... 确认生成?(直接回车确认,或告诉我要改什么)当LANG=en时:🎵 About to generate: Type: Vocal Prompt: indie folk, melancholy, acoustic guitar, gentle female voice Lyrics: [verse] ... Confirm? (press enter to confirm, or tell me what to change) -
调用API:使用构造好的参数执行脚本。
scripts/generate_music.py
Step 2: Advanced Control Mode
步骤2:强控制模式
Goal: User has full control over every parameter before generation.
-
Lyrics phase:
- If user provided lyrics: display them formatted with section markers, ask for edits.
- If user has a theme but no lyrics: call the lyrics API to generate a draft:
Present the generated lyrics to the user for review and editing.bash
python3 ~/.claude/skills/minimax-music-gen/scripts/generate_lyrics.py \ --prompt "<vivid description of the song's theme and story>" \ --lang $LANG \ --output /tmp/lyrics_draft.txt - Support iterative editing: "第二段副歌改一下" → only rewrite that section.
- User can choose to regenerate lyrics with a different prompt if unsatisfied.
-
Prompt phase:
- Generate a recommended prompt based on the lyrics' mood and content.
- Present it as editable tags the user can add/remove/modify.
- Read for the full vocabulary.
references/prompt_guide.md
-
Advanced planning (optional, offer but don't force):
- Song structure: verse-chorus-verse-chorus-bridge-chorus or custom
- BPM suggestion (encode in prompt as tempo descriptor)
- Reference style: "类似某种风格" → map to prompt tags
- Vocal character description
-
Final confirmation: Show complete parameter summary, then generate.
目标:生成前用户可以完全控制所有参数。
-
歌词阶段:
- 如果用户已经提供了歌词:格式化显示并添加段落标记,询问用户是否需要修改。
- 如果用户只有主题没有歌词:调用歌词API生成草稿:
将生成的歌词展示给用户供其审核和编辑。bash
python3 ~/.claude/skills/minimax-music-gen/scripts/generate_lyrics.py \ --prompt "<歌曲主题和故事的生动描述>" \ --lang $LANG \ --output /tmp/lyrics_draft.txt - 支持迭代修改:用户说"第二段副歌改一下" → 仅重写对应段落。
- 用户不满意时可以选择使用不同的提示词重新生成歌词。
-
提示词阶段:
- 根据歌词的情绪和内容生成推荐的提示词。
- 以可编辑标签的形式展示给用户,用户可增删修改。
- 完整词汇表可参考 。
references/prompt_guide.md
-
高级规划(可选,可主动提供但不要强制用户使用):
- 歌曲结构:主歌-副歌-主歌-副歌-桥段-副歌或自定义结构
- BPM建议(作为速度描述词编码到提示词中)
- 参考风格:"类似某种风格" → 映射为提示词标签
- 人声特点描述
-
最终确认:展示完整的参数汇总,确认后开始生成。
Step 3: Call the API
步骤3:调用API
Run the generation script:
bash
python3 ~/.claude/skills/minimax-music-gen/scripts/generate_music.py \
--prompt "<prompt>" \
--lyrics "<lyrics or empty>" \
--lang $LANG \
--output ~/Music/minimax-gen/<filename>.mp3
# Add --instrumental for instrumental (no vocal). Omit for vocal tracks.
# Add --cover for cover mode. Omit for original tracks.
# Add --no-play to skip auto-playback after generation.The script handles:
- API call with proper headers
- Polling for completion (the API may return a task ID)
- Downloading the result MP3
- Error handling with clear messages
Display a progress indicator while waiting. Typical generation takes 30-120 seconds.
执行生成脚本:
bash
python3 ~/.claude/skills/minimax-music-gen/scripts/generate_music.py \
--prompt "<提示词>" \
--lyrics "<歌词内容,无则留空>" \
--lang $LANG \
--output ~/Music/minimax-gen/<文件名>.mp3
# 纯音乐请添加 --instrumental 参数,人声歌曲省略该参数
# 翻唱模式请添加 --cover 参数,原创歌曲省略该参数
# 添加 --no-play 参数可跳过生成后的自动播放脚本会自动处理:
- 携带正确的请求头调用API
- 轮询等待生成完成(API可能会先返回任务ID)
- 下载生成的MP3结果
- 错误处理并返回清晰的提示信息
等待过程中显示进度指示器,通常生成需要30-120秒。
Step 4: Playback
步骤4:播放
After generation, play the song:
bash
python3 ~/.claude/skills/minimax-music-gen/scripts/play_music.py \
--lang $LANG \
~/Music/minimax-gen/<filename>.mp3The script auto-detects the best available player ( > > > ).
Tell the user:
mpvffplayafplayaplayIf LANG=zh:
🎵 正在播放:<filename>.mp3
📁 文件已保存到:~/Music/minimax-gen/<filename>.mp3
⏸️ 按 q 或 Ctrl+C 可暂停/停止播放If LANG=en:
🎵 Now playing: <filename>.mp3
📁 Saved to: ~/Music/minimax-gen/<filename>.mp3
⏸️ Press q or Ctrl+C to pause/stop playback生成完成后播放歌曲:
bash
python3 ~/.claude/skills/minimax-music-gen/scripts/play_music.py \
--lang $LANG \
~/Music/minimax-gen/<文件名>.mp3脚本会自动检测最优的可用播放器(优先级: > > > )。告知用户以下信息:
mpvffplayafplayaplay当LANG=zh时:
🎵 正在播放:<文件名>.mp3
📁 文件已保存到:~/Music/minimax-gen/<文件名>.mp3
⏸️ 按 q 或 Ctrl+C 可暂停/停止播放当LANG=en时:
🎵 Now playing: <文件名>.mp3
📁 Saved to: ~/Music/minimax-gen/<文件名>.mp3
⏸️ Press q or Ctrl+C to pause/stop playbackStep 5: Feedback & Iteration
步骤5:反馈与迭代
After playback, ask for feedback:
If LANG=zh:
这首歌怎么样?
1. 🎉 很满意,保留!
2. 🔄 不太行,调整后重新生成
3. 🎨 歌词/风格微调后重新生成
4. 🗑️ 不要了,删掉重来If LANG=en:
How was this song?
1. 🎉 Love it, keep it!
2. 🔄 Not quite, adjust and regenerate
3. 🎨 Fine-tune lyrics/style then regenerate
4. 🗑️ Don't want it, start overBased on feedback:
- Satisfied: Done. Mention the file path again.
- Adjust & regenerate: Ask what to change (prompt? lyrics? style?), apply edits,
re-run generation. Keep the old file with a suffix for comparison.
_v1 - Fine-tune: Enter Advanced Control Mode with the current parameters pre-filled.
- Delete & restart: Remove the file, go back to Step 0.
播放结束后询问用户反馈:
当LANG=zh时:
这首歌怎么样?
1. 🎉 很满意,保留!
2. 🔄 不太行,调整后重新生成
3. 🎨 歌词/风格微调后重新生成
4. 🗑️ 不要了,删掉重来当LANG=en时:
How was this song?
1. 🎉 Love it, keep it!
2. 🔄 Not quite, adjust and regenerate
3. 🎨 Fine-tune lyrics/style then regenerate
4. 🗑️ Don't want it, start over根据反馈处理:
- 满意:流程结束,再次告知用户文件保存路径。
- 调整后重新生成:询问修改方向(提示词?歌词?风格?),应用修改后重新执行生成流程。旧文件添加 后缀保留供对比。
_v1 - 微调:进入强控制模式,预填充当前参数。
- 删除并重启:删除当前文件,回到步骤0。
Error Handling
错误处理
| Error | Action |
|---|---|
| Missing API key | Print setup instructions for |
| Missing Group ID | Ask user for their GroupId |
| API timeout (>3min) | Retry once, then report failure with request ID |
| Invalid lyrics format | Auto-fix section markers, warn user |
| Download URL expired | Re-request from API |
| No audio player found | Save file and tell user the path, suggest installing mpv |
| Network error | Show error detail, suggest checking connection |
| 错误 | 处理方式 |
|---|---|
| 缺少API密钥 | 输出 |
| 缺少分组ID | 询问用户的分组ID |
| API超时(>3分钟) | 重试一次,失败则返回请求ID告知用户生成失败 |
| 歌词格式无效 | 自动修复段落标记,告知用户 |
| 下载链接过期 | 重新向API请求资源 |
| 未找到音频播放器 | 保存文件并告知用户路径,建议安装mpv |
| 网络错误 | 展示错误详情,建议检查网络连接 |
Cover Mode
翻唱模式
When the user selects Cover mode:
- Ask for the song they want to cover (name + artist)
- Set the header
bedrock_lane: cover - Generate a prompt that describes the cover style (e.g., "acoustic cover of pop song, stripped-down arrangement, intimate vocal")
- Lyrics: user provides or we look up a rough theme (never reproduce copyrighted lyrics — write original lyrics inspired by the theme)
- Proceed with normal generation flow
用户选择翻唱模式时:
- 询问用户想要翻唱的歌曲(名称+歌手)
- 设置 请求头
bedrock_lane: cover - 生成描述翻唱风格的提示词(例如:"acoustic cover of pop song, stripped-down arrangement, intimate vocal")
- 歌词:用户提供或根据歌曲主题生成原创歌词(绝对不要复制受版权保护的歌词,仅根据主题创作原创歌词)
- 按照正常生成流程继续
Important Notes
重要注意事项
- Never reproduce copyrighted lyrics. When doing covers, always write original lyrics inspired by the song's theme. Explain this to the user.
- Prompt language: The API prompt works best with Chinese tags or English tags. Mix is OK.
- Section markers in lyrics: The API recognizes ,
[verse],[chorus],[bridge],[outro]. Always include them.[intro] - File management: If has more than 50 files, suggest cleanup when starting a new session.
~/Music/minimax-gen/
- 绝对不要复制受版权保护的歌词。做翻唱时,永远根据歌曲主题创作原创歌词,并向用户说明该规则。
- 提示词语言:API提示词使用中文标签或英文标签效果最佳,混合使用也可。
- 歌词中的段落标记:API可识别 、
[verse]、[chorus]、[bridge]、[outro]标记,请务必添加。[intro] - 文件管理:如果 目录下文件超过50个,新会话开始时建议用户清理旧文件。
~/Music/minimax-gen/