mm-music-maker

MiniMax Music Maker

使用此技能通过 MiniMax 的 Music Generation API 生成音乐。除非另有说明，所有用法和输出均针对 music-2.5 设计。

快速开始

1. 设置 API key：

export MINIMAX_MUSIC_API_KEY="your_api_key"

2. 根据歌词（和可选提示词）生成音乐：

python scripts/generate_music.py \
  --lyrics "[Verse]\n...\n[Chorus]\n..." \
  --prompt "indie folk, melancholic, introspective" \
  --output ./output.mp3

脚本位置

• scripts/generate_music.py — 主生成器（歌词 + 提示词 → 音频）
• scripts/utils_audio.py — 十六进制解码 + 保存辅助函数

参考资料

阅读 references/minimax_music_api.md，了解：

• 端点、身份验证标头、载荷架构
• 必填/可选字段
• 输出格式（hex/url）和限制

核心模式

此技能支持 3 种生成模式：

1. 标准歌曲（带歌词）

• 用户提供或需要歌词 + 音乐
• 使用结构化歌词，并通过提示词指定风格

2. 纯音乐（纯器乐）

• 用户提出：“纯音乐”“纯音乐，无人声”“pure music”“instrumental”
• 无歌词，仅有器乐编曲
• 请参阅下文“纯音乐生成”部分

3. 旋律哼唱/吟唱

• 用户提出：“哼唱”“吟唱”“humming”“chanting”
• 使用人声音节而非完整歌词的音乐
• 请参阅下文“旋律哼唱生成”部分

注意事项

• API 要求提供 lyrics。
• prompt 对 music-2.5 来说是可选的。
• output_format 默认为 hex（内联音频）。如需下载 URL，请使用 url。
• URL 会过期（24 小时）。使用 url 时请立即下载。

提示词编写（重要）

核心原则：使用“描述”而非“命令”，保持结构清晰、易于解析。

必要元素（建议）

• 流派/子流派（注明时代或地区）
• 情绪/情感（2-3 个情绪描述）
• 速度/BPM（尽可能注明 BPM）
• 主要乐器（3-5 种主要乐器/音色）
• 人声（人声类型、处理方式，或纯器乐）
• 用途（目的/场景）

可选增强项

• 结构（乐段结构）
• 参考（1-2 个风格参考）
• 规避/负面要求（排除项）

提示词模板

基础模板（入门）

[Genre], [Mood], [Tempo/BPM], [Key Instruments], [Vocal Style]

标准模板（推荐）

Genre: [Specific genre + era]
Mood: [2-3 descriptors]
Tempo: [BPM or speed]
Instruments: [3-5 key instruments]
Vocals: [Type or instrumental only]
Use case: [scene/usage]
Avoid: [unwanted elements]
References: [1-2 artists/songs]

高级模板（制作简介）

Genre: … | Era: …
BPM: … | Key: …
Mood: ... (can include emotional arc, e.g., "from restrained to explosive")
Lead: …
Rhythm: …
Bass: …
Texture: …
Vocals: …
Structure: Intro / Verse / Chorus / Bridge / Outro
Avoid: …
Reference: …

结构标签（歌词中）

[Intro]
[Verse]
[Pre-Chorus]
[Chorus]
[Bridge]
[Outro]
[Instrumental]

负面提示词示例

• No vocals / Instrumental only
• Avoid autotune
• No distorted guitars
• Avoid heavy reverb
• No trap hi-hats

常见问题修复

• 风格不准确：添加“时代 + 子流派 + 乐器锚点 + 参考艺术家”
• 节奏不对：注明 BPM + 节奏描述（例如，四拍底鼓）
• 前奏太普通：在歌词中写入 [Intro] 并描述开场
• 人声不理想：将人声要求移到提示词开头，并添加负面限制

提示词质量检查清单

• 包含：流派 / 情绪 / BPM / 乐器 / 人声 / 用途
• 检查是否存在冲突（例如，“非常慢 + 高能量”）
• 添加规避项以过滤不需要的元素
• 结构清晰（避免冗长的散文段落）

---

纯音乐生成

当用户需要无歌词的器乐曲目时，使用此模式。

检测关键词

• 纯音乐、纯音乐无人声、无人声
• pure music、instrumental、no lyrics
• 背景音乐、轻音乐、器乐
• 无歌词

提示词格式

pure music, [scene/style description], no lyrics

歌词字段

使用占位标签：[intro] [outro]

重要注意事项

⚠️ 时长：纯音乐曲目通常较短（1-2 分钟），因为没有歌词来引导音乐的推进。

纯音乐提示词示例

#	提示词	场景
1	pure music, coffee shop, no lyrics	咖啡馆氛围
2	pure music, rainy night, no lyrics	雨夜
3	pure music, morning sunshine, no lyrics	晨光
4	pure music, jazz bar, no lyrics	爵士酒吧
5	pure music, city walk, no lyrics	城市漫步
6	pure music, night drive, no lyrics	夜间驾驶
7	pure music, piano solo, no lyrics	钢琴独奏
8	pure music, lofi chill, no lyrics	Lo-Fi 轻松
9	pure music, bookstore, no lyrics	书店
10	pure music, cafe closing time, no lyrics	咖啡馆打烊

CLI 示例

为咖啡馆生成纯音乐：

python scripts/generate_music.py \
  --lyrics "[intro] [outro]" \
  --prompt "pure music, coffee shop, no lyrics" \
  --output ./coffee_shop.mp3

生成雨夜氛围音乐：

python scripts/generate_music.py \
  --lyrics "[intro] [outro]" \
  --prompt "pure music, rainy night, no lyrics" \
  --output ./rainy_night.mp3

生成钢琴独奏：

python scripts/generate_music.py \
  --lyrics "[intro] [outro]" \
  --prompt "pure music, piano solo, no lyrics" \
  --output ./piano_solo.mp3

---

旋律吟唱/哼唱生成

当用户想要带有人声音节而非完整歌词的音乐（哼唱、吟唱）时，使用此模式。

检测关键词

• 哼唱、吟唱、发声
• 哼唱、吟唱
• 治愈、人声伴奏
• 旋律
• 和声、呜、啊、啦

提示词格式

pure music, [风格/场景描述], no lyrics

歌词字段（音节模式）

使用人声音节代替词语：

音节模式	氛围
ah, ah, ah, ah...	柔和吟唱
la, la, la, la...	旋律哼唱
mmm, mmm, mmm...	治愈系哼鸣
ooh, ooh, ooh...	空灵吟唱
hum, hum, hum...	持续哼唱

歌词结构模板

[intro] [verse] [chorus] [verse] [outro]

将各部分替换为选定的音节。

吟唱提示词示例

场景	提示词	歌词
治愈	纯音乐、治愈、放松、无人声	[intro] mmm, mmm, mmm... [verse] mmm, mmm, mmm... [outro]
冥想	纯音乐、冥想、平静、无人声	[intro] ooh, ooh, ooh... [verse] ooh, ooh, ooh... [outro]
欢快	纯音乐、欢快、振奋、无人声	[intro] la, la, la, la... [chorus] la, la, la, la... [outro]
神秘	纯音乐、神秘、空灵、无人声	[intro] ah, ah, ah... [verse] ah, ah, ah... [outro]

CLI 示例

生成治愈系吟唱音乐：

python scripts/generate_music.py \
  --lyrics "[intro] mmm, mmm, mmm... [verse] mmm, mmm, mmm... [chorus] mmm, mmm, mmm... [outro]" \
  --prompt "pure music, healing, relaxing, no lyrics" \
  --output ./healing_chant.mp3

生成冥想吟唱：

python scripts/generate_music.py \
  --lyrics "[intro] ooh, ooh, ooh... [verse] ooh, ooh, ooh... [outro]" \
  --prompt "pure music, meditation, calming, no lyrics" \
  --output ./meditation.mp3

生成欢快哼唱：

python scripts/generate_music.py \
  --lyrics "[intro] la, la, la... [verse] la, la, la... [chorus] la, la, la... [outro]" \
  --prompt "pure music, happy, uplifting, no lyrics" \
  --output ./happy_humming.mp3

---

模式检测逻辑

当用户请求生成音乐时，检测模式：

1. 标准歌曲 → 用户提供歌词，或要求“带歌词的歌曲”
2. 纯音乐 → 关键词：“纯音乐”、“pure music”、“instrumental”、“no lyrics”、“无人声”
3. 吟唱/哼唱 → 关键词：“哼唱”、“吟唱”、“humming”、“chanting”、“治愈系”

决策流程

User Request
    ↓
Contains "纯音乐"/"pure music"/"instrumental"?
    ├─ Yes → Is "哼唱"/"humming" also mentioned?
    │   ├─ Yes → Melodic Chanting Mode
    │   └─ No → Pure Music Mode
    └─ No → Standard Song Mode (requires lyrics)

推荐的 CLI 模式

生成 MP3（十六进制响应 → 文件）：

python scripts/generate_music.py \
  --lyrics "[Intro]\n..." \
  --prompt "cinematic, uplifting" \
  --output ./music.mp3 \
  --format mp3 \
  --bitrate 256000 \
  --sample-rate 44100

使用结构化提示词字段生成（自动构建）：

python scripts/generate_music.py \
  --lyrics "[Verse]\n..." \
  --genre "1980s synthwave" \
  --mood "nostalgic, energetic" \
  --bpm 120 \
  --instruments "analog synths, drum machine, bass guitar" \
  --vocals "female vocals" \
  --use-case "retro game trailer" \
  --avoid "no acoustic guitar" \
  --references "The Midnight, FM-84" \
  --output ./music.mp3

生成并从 URL 下载：

python scripts/generate_music.py \
  --lyrics "[Verse]\n..." \
  --prompt "lofi, rainy night" \
  --output ./music.mp3 \
  --output-format url \
  --download

---

API 参考

如需了解详细的 API 文档（端点、身份验证、请求/响应格式），请参阅：

references/minimax_music_api.md

所有模式的要点：

• 端点：POST https://api.minimaxi.com/v1/music_generation
• 身份验证：Authorization: Bearer <token>
• 模型：music-2.5
• lyrics：必填字段——纯音乐使用 [intro] [outro]，吟唱使用音节模式

API 请求示例

标准歌曲：

{
  "model": "music-2.5",
  "prompt": "indie folk, melancholic, introspective",
  "lyrics": "[verse]\n...\n[chorus]\n..."
}

纯音乐：

{
  "model": "music-2.5",
  "prompt": "pure music, coffee shop, no lyrics",
  "lyrics": "[intro] [outro]"
}

旋律吟唱：

{
  "model": "music-2.5",
  "prompt": "pure music, healing, relaxing, no lyrics",
  "lyrics": "[intro] mmm, mmm, mmm... [verse] mmm, mmm, mmm... [outro]"
}

响应格式

• data.audio：十六进制字符串（默认）或 URL（有效期为 24 小时）
• data.status：生成状态
• extra_info：时长、采样率、声道、比特率、大小
• base_resp.status_code：成功时为 0