---
name: minimax-music
description: >
  Generate music or a song from a prompt (and optional lyrics) via the MiniMax
  music API. Use when the user wants music, a beat, a soundtrack, a theme song,
  background music, or a melody. Trigger on phrases like "make a song",
  "compose music", "background music", "theme tune", "lo-fi beat".
allowed-tools: Bash(minimax-gen music *), Bash(minimax-gen --help), Bash(mkdir *), Bash(ls *), Bash(test *), Bash(file *), Read
---

# /minimax-music — Music Generation

Generate a music track via the MiniMax music API. Lyrics are optional.

## CLI

```bash
# Instrumental
minimax-gen music --prompt "epic, 120 bpm, brass, strings" --instrumental \
  --out /tmp/theme.mp3

# With lyrics (read from a file)
minimax-gen music --lyrics @lyrics.txt --prompt "indie folk, warm acoustic" \
  --out /tmp/song.mp3

# Auto-generated lyrics from the prompt
minimax-gen music --prompt "a love song with a slow build" --lyrics-optimizer \
  --out /tmp/love.mp3
```

The CLI is at `~/dev/claude/gamedev/minimax-gen/bin/minimax-gen`.

## Choose a model

| Model | Use |
|---|---|
| `music-3.0` (default) | latest, paid (may queue 5+ min during peak) |
| `music-3.0-free` | free tier, 3 RPM, ~40s typical |
| `music-2.6` / `music-2.6-free` | previous gen |
| `music-cover` | needs `--audio-url` or `--audio-base64` reference |

Tip: scripts and smoke tests should use `music-3.0-free` to avoid burning credits.

## Structure tags for lyrics

```
[Intro]
[Verse 1]
[Pre Chorus]
[Chorus]
[Interlude]
[Bridge]
[Outro]
[Inst]
```

## Timeouts

Music can take up to 5 minutes. Default `--timeout` is 600s. Bump it for longer
tracks or when the queue is busy.

## After the call

1. Show the path written and the `trace_id` from the sidecar `.meta.json`.
2. Note the duration (`duration_ms`) and size so the user knows what to expect.
3. Don't dump the meta JSON into chat — point at the file.

## Never do

- Never echo, log, or commit the contents of `~/.claude-secrets/minimax-auth-token`.
- Never pass the token on a command line.

## Reference

Full option list: `minimax-gen music --help`