minimax-game-audio

Version: 1.0.0 | License: MIT-0 | Runtime: Node.js ≥ 18

Generate game background music (BGM) with MiniMax Music 2.6. Designed for web games, student game jam projects, and AI game design camps. Produces loopable instrumental tracks via English text prompts.

1. 获取 MiniMax API Key

本 skill 需要 MiniMax API Key 才能生成音乐。以下是完整注册流程：

1注册 MiniMax 开放平台

访问 https://platform.minimaxi.com/，点击右上角「注册」，使用手机号或邮箱注册账号。

MiniMax 开放平台首页 — 点击右上角「注册」

2完成实名认证

注册登录后，进入「账户管理」→「实名认证」，上传身份证完成认证（个人或企业）。认证通常 2 小时内通过。未认证无法创建 API Key。

3创建 API Key

认证通过后，进入「接口密钥」页面（或「账户管理」→「API Keys」），点击「创建新密钥」。

MiniMax 控制台 — 接口密钥页面，点击「创建新密钥」

4复制并保存 API Key

创建后系统会生成以 sk- 开头的密钥。密钥仅在创建时完整显示一次，请立即复制保存，关闭后无法再次查看。

API Key 创建成功弹窗 — 密钥以 sk- 开头，仅显示一次

验证 API Key

curl -X GET "https://api.minimaxi.com/v1/health" \
  -H "Authorization: Bearer sk-api-your-key-here"

返回 "status":"ok" 表示密钥可用。

2. 配置 API Key 到 WorkBuddy（api-vault 方案）

为了让 AI agent 自动找到 API Key（而不是每次都问你），推荐使用 api-vault 方案：把所有 API Key 集中存在一个环境文件里，再装一个 skill 让 AI 养成「先查 vault」的习惯。

1安装 api-vault skill

下载并安装 api-vault skill，它会让 AI agent 在需要 API Key 时自动去 ~/.claude/api-vault.env 查找。

下载：api-vault-skill.zip (2.0 KB)

# 下载并安装 api-vault skill
curl -L -o api-vault-skill.zip https://9b2d4e3b4b0d4923b84c3f5b689a1d7c.app.codebuddy.work/api-vault-skill.zip
unzip -o api-vault-skill.zip -d api-vault

# 安装到 WorkBuddy skills 目录
cp -r api-vault ~/.workbuddy/skills/api-vault

# 验证安装
ls ~/.workbuddy/skills/api-vault/SKILL.md

2创建 api-vault.env 文件

把你的 MiniMax API Key 写入 ~/.claude/api-vault.env。这个文件集中存放所有 API Key，不会被任何项目的 git 跟踪。

# 创建 vault 文件（如果不存在）
mkdir -p ~/.claude
cat >> ~/.claude/api-vault.env << 'EOF'
# MiniMax 开放平台
MINIMAX_API_KEY=sk-api-your-key-here
EOF

# 验证
cat ~/.claude/api-vault.env

⚠ 安全提示：

不要把 api-vault.env 提交到任何 git 仓库或分享给他人
不要在聊天、代码、截图中粘贴完整的 API Key
这个文件只存在于本地 ~/.claude/ 目录

api-vault 工作原理

安装 api-vault skill 后，AI agent 在需要任何 API Key 时的查找顺序：

1. 先读 ~/.claude/api-vault.env          ← vault 文件（推荐）
2. 再查环境变量（如 $MINIMAX_API_KEY）    ← 备选
3. 最后才问用户要                         ← 兜底

也就是说，只要 API Key 存在 vault 里，AI 就会自动找到并使用，不需要你手动 export 或粘贴。

运行 minimax-game-audio 脚本时，通过 source 加载 vault：

source ~/.claude/api-vault.env
node ~/.workbuddy/skills/minimax-game-audio/scripts/generate_bgm.mjs \
  --prompt "your prompt" \
  --out ./bgm.mp3 \
  --name bgm-track

3. 下载与安装 minimax-game-audio skill

下载：minimax-game-audio-skill.zip (7.9 KB)

# 下载并解压
curl -L -o minimax-game-audio-skill.zip https://9b2d4e3b4b0d4923b84c3f5b689a1d7c.app.codebuddy.work/minimax-game-audio-skill.zip
unzip -o minimax-game-audio-skill.zip -d minimax-game-audio

# 安装到 skills 目录（选一个）
cp -r minimax-game-audio ~/.workbuddy/skills/minimax-game-audio   # WorkBuddy
# 或
cp -r minimax-game-audio ~/.claude/skills/minimax-game-audio       # Claude Code

# 验证
ls ~/.workbuddy/skills/minimax-game-audio/SKILL.md

4. 文件结构

minimax-game-audio/
├── SKILL.md                              # Skill definition & workflow
├── scripts/
│   └── generate_bgm.mjs                  # MiniMax music generation script
├── references/
│   ├── game-bgm-prompts.md               # Reusable game music prompts
│   ├── web-audio-integration.md          # HTML/React/Vite integration guide
│   └── troubleshooting.md               # Error codes & classroom safeguards
└── agents/
    └── openai.yaml                       # Agent interface config

5. 用法

生成 BGM

source ~/.claude/api-vault.env   # 加载 API Key
node ~/.workbuddy/skills/minimax-game-audio/scripts/generate_bgm.mjs \
  --prompt "Healing fantasy forest game background music, soft piano, warm strings, gentle celesta, peaceful and beautiful, slow tempo, loopable instrumental, no vocals" \
  --out ./healing-forest.mp3 \
  --name healing-forest

Dry-run（预览请求体，不消耗额度）

node scripts/generate_bgm.mjs \
  --prompt "your prompt here" \
  --out ./test.mp3 \
  --name test \
  --dry-run

参数列表

Flag	Default	Description
`--prompt`	required	English music description (mood, scene, instruments, tempo)
`--out`	required	Output file path (.mp3 / .wav / .pcm)
`--name`	required	Track identifier for logging
`--model`	music-2.6-free	`music-2.6-free` (free, rate-limited) or `music-2.6` (paid)
`--vocals`	off	Enable vocal mode (default is instrumental)
`--lyrics`	—	Lyrics text (required if `--vocals` is set)
`--format`	mp3	Output format: `mp3`, `wav`, or `pcm`
`--sample-rate`	44100	Audio sample rate in Hz
`--bitrate`	256000	Audio bitrate in bps
`--key-file`	—	Path to a file containing the API key
`--dry-run`	off	Print request body without calling MiniMax API

6. 提示词指南

用英文写提示词效果最好，包含以下要素：

Game scene: fantasy forest, boss battle, cozy village, puzzle room
Mood: healing, tense, creepy, cute, urgent, peaceful
Instruments: soft piano, warm strings, heavy drums, music box, synth bass
Tempo: slow, mid, fast
Suffix: always end with loopable instrumental, no vocals

示例提示词

# 治愈风
"Healing fantasy forest game background music, soft piano, warm strings, gentle celesta, peaceful and beautiful, slow tempo, loopable instrumental, no vocals"

# FPS 战斗
"Intense modern FPS shooter battle music, heavy electronic drums, aggressive synth bass, distorted guitar riffs, cinematic brass hits, urgent adrenaline pumping, fast tempo, loopable instrumental, no vocals"

# 诡异解密
"Creepy mysterious puzzle game background music, dark ambient drones, dissonant piano notes, eerie music box melody, unsettling whispers, distant creaks, suspenseful horror atmosphere, loopable instrumental, no vocals"

# 萌萌治愈
"Adorable cute healing game background music, music box, twinkling bells, soft ukulele, gentle harp, warm marimba, fluffy and cozy, innocent and sweet, bouncy playful melody, kawaii relaxing, loopable instrumental, no vocals"

7. AI Agent 注意事项

生成一首 BGM 需要 1-3 分钟，建议用后台执行
免费模型 music-2.6-free 限流较严，避免并行请求
默认输出 MP3, 44100 Hz, 立体声, 256 kbps
短音效（点击、命中、拾取）建议用 ZzFX/WebAudio 合成，不要调 MiniMax
浏览器禁止自动播放音频，BGM 需在用户点击后才能播放
永远不要打印或提交 API Key 到代码仓库
常见错误码见 references/troubleshooting.md（1008余额不足, 1026内容违规, 2049密钥无效, 2061套餐不支持）
需要 API Key 时，永远先查 ~/.claude/api-vault.env

MiniMax Game Audio Skill v1.0.0 — platform.minimaxi.com — MIT-0 License