MiniMax Music Generation Skill

Prerequisites

• Credentials: Set the following environment variables:

  • MINIMAX_API_KEY

    — your MiniMax API key

  • MINIMAX_GROUP_ID

    — your MiniMax Group ID
  The scripts also support reading from

  ~/.minimax_api_key

  and

  ~/.minimax_group_id

  files as a fallback.
  To 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:

  • echo $MINIMAX_API_KEY

    — prints the key to terminal

  • cat ~/.minimax_api_key

    — exposes the full API key
  • Any command that outputs credential values to stdout/stderr
• Python 3.8+ (scripts use only stdlib — no pip install needed).

• ffplay

  or

  mpv

  or

  afplay

  (macOS) for local playback. The script auto-detects.

APIs Used

1. Lyrics Generation —

   POST /v1/lyrics_generation

   • Base URL:

     https://api.minimax.io

     (overseas) or

     https://api.minimaxi.com

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

2. Music Generation —

   POST /v1/music_generation

   • Base URL:

     https://api.minimax.io

     (overseas) or

     https://api.minimaxi.com

     (domestic)
   • Scripts auto-detect the correct domain based on the user's API key
   • Generates the actual audio (MP3) from a prompt + optional lyrics
   • Model:

     music-2.6-free

     (fallback:

     music-2.6

     ), cover:

     music-cover-free

     (fallback:

     music-cover

     )
   • Supports:

     is_instrumental

     (true/false),

     bedrock_lane: cover

     header
   • Script:

     scripts/generate_music.py

User description → [Lyrics API] → lyrics → [Music API + prompt] → MP3

Storage

~/Music/minimax-gen/

YYYYMMDD_HHMMSS_<slug>.mp3

Workflow

Language Detection

• Chinese (中文) → Set

  LANG=zh

  — all interactions in Chinese, generate Chinese lyrics
• English → Set

  LANG=en

  — all interactions in English, generate English lyrics

• 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

  --prompt

  passed to

  generate_lyrics.py

  must 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.

--lang $LANG

Step 0: Detect Language & Intent

1. Song category: vocal (人声音乐), instrumental (纯音乐), or cover
2. Creation mode preference: did they provide detailed requirements (→ Advanced) or a casual one-liner (→ Basic)?

Q1: 你想要哪种类型？
  - 🎤 人声音乐（有歌词演唱）
  - 🎵 纯音乐（无人声）
  - 🎧 Cover（翻唱风格）

Q2: 创作模式？
  - ⚡ 基础版 — 一句话描述，自动搞定
  - 🎛️ 强控制版 — 自己调歌词、prompt、风格

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. Expand the description into a prompt: Take the user's one-liner and expand it into a rich music prompt. Read

   references/prompt_guide.md

   for the style vocabulary and prompt structure. The music generation prompt must match the user's language (LANG):
   • 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].

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

   The API endpoint is

   /v1/lyrics_generation

   (domain auto-detected) with mode

   write_full_song

   . The prompt should be a vivid description of the song's theme, mood, and story — written in the target lyrics language.
   Chinese 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]

   ,

   [chorus]

   , etc. If the returned lyrics lack section markers, add them automatically following this structure:

   [verse]    — 4 lines
   [chorus]   — 4 lines
   [verse]    — 4 lines
   [chorus]   — 4 lines
   [outro]    — 2 lines

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

4. Call the API: Run

   scripts/generate_music.py

   with the constructed parameters.

Step 2: Advanced Control Mode

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

     Present the generated lyrics to the user for review and editing.
   • Support iterative editing: "第二段副歌改一下" → only rewrite that section.
   • User can choose to regenerate lyrics with a different prompt if unsatisfied.
2. 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

     references/prompt_guide.md

     for the full vocabulary.
3. 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
4. Final confirmation: Show complete parameter summary, then generate.

Step 3: Call the API

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.

• API call with proper headers
• Polling for completion (the API may return a task ID)
• Downloading the result MP3
• Error handling with clear messages

Step 4: Playback

python3 ~/.claude/skills/minimax-music-gen/scripts/play_music.py \
  --lang $LANG \
  ~/Music/minimax-gen/<filename>.mp3

mpv

ffplay

afplay

aplay

🎵 正在播放：<filename>.mp3
📁 文件已保存到：~/Music/minimax-gen/<filename>.mp3
⏸️  按 q 或 Ctrl+C 可暂停/停止播放

🎵 Now playing: <filename>.mp3
📁 Saved to: ~/Music/minimax-gen/<filename>.mp3
⏸️  Press q or Ctrl+C to pause/stop playback

Step 5: Feedback & Iteration

这首歌怎么样？
  1. 🎉 很满意，保留！
  2. 🔄 不太行，调整后重新生成
  3. 🎨 歌词/风格微调后重新生成
  4. 🗑️ 不要了，删掉重来

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

• 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

  _v1

  suffix for comparison.
• Fine-tune: Enter Advanced Control Mode with the current parameters pre-filled.
• Delete & restart: Remove the file, go back to Step 0.

Error Handling

MINIMAX_API_KEY

Cover Mode

1. Ask for the song they want to cover (name + artist)
2. Set the

   bedrock_lane: cover

   header
3. Generate a prompt that describes the cover style (e.g., "acoustic cover of pop song, stripped-down arrangement, intimate vocal")
4. Lyrics: user provides or we look up a rough theme (never reproduce copyrighted lyrics — write original lyrics inspired by the theme)
5. Proceed with normal generation flow

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]

  ,

  [intro]

  . Always include them.
• File management: If

  ~/Music/minimax-gen/

  has more than 50 files, suggest cleanup when starting a new session.