skywork-music-maker

Skywork Music Maker（Mureka API）

使用 https://api.mureka.ai 上的 Mureka API 生成专业品质的音乐。此技能涵盖完整的音乐制作工作流：创作歌词 → 生成歌曲／纯音乐。

首次设置

运行任何 API 命令前，请先检查是否已设置 MUREKA_API_KEY。如果没有，请指导用户前往 https://platform.mureka.ai/ 获取 API 密钥（注册 → API Keys → 生成密钥 → export MUREKA_API_KEY="..."），然后停止操作——配置密钥之前不要尝试调用任何 API。

---

智能提示词转换（关键工作流）

默认行为：用户未指定歌曲类型时，始终生成带歌词的歌曲（使用 mureka.py song）。只有用户明确要求纯音乐、BGM、背景音乐或“无人声”时，才使用 mureka.py instrumental。

默认输出：除非用户另有要求，否则使用 mp3 格式。--output 标志用于指定目录——脚本会创建该目录并将所有结果保存在其中（音频文件，以及歌曲对应的 lyrics.txt）。用户未指定保存位置时，请选择一个便于用户使用的路径，并根据歌曲主题设置描述性文件夹名称（例如：summer_pop_song/）。

用户使用自然语言（任何语言）描述音乐时，你必须按照以下工作流，将其转换为结构化的 Mureka API 提示词：

转换流程

用户输入示例：

• “欢快的流行歌曲，女声演唱，配吉他，适合夏天”
• “一首关于逝去爱情的悲伤钢琴叙事曲”
• “适合奇幻游戏的史诗管弦乐”
• “带有竹笛和古筝、氛围朦胧的中国传统音乐”

你的任务：

1. 使用下方的提取规则提取结构化参数
2. 验证提示词是否符合质量标准（见质量检查清单）
3. 生成前先提交给用户确认
4. 使用结构化提示词运行生成命令

参数提取规则

用户以自然语言描述音乐时，直接提取并整理以下参数：

必需参数：

• genres：音乐流派，包括融合风格（例如：Pop、Rock、Jazz、Pop Rap Fusion、Alternative Rock、Guofeng）
• moods：情绪基调（例如：Happy、Melancholic、Energetic、Nostalgic、Bright）
• instruments：具体乐器（例如：Piano、Guitar、Drums、Erhu、Guzheng、Synth Pads、Dizi）
• rhythms：节奏特征（例如：4/4、Slow、Syncopated、Driving、Flowing）
• vocals：人声特征（例如：Female、Husky、Whispered、Male、Soft、Clear），或“纯器乐”
• key：指定时填写调性（例如：C Major、A Minor、C# Major）
• bpm：每分钟节拍数（例如：120），或速度描述（例如：“slow groove”“uptempo”）
• description：简洁概述（少于 50 个单词），涵盖情绪变化、旋律、和声、音色、织体和力度

提取说明：

1. 翻译非英语术语：将所有非英语音乐术语转换为英语，同时保留其文化和音乐含义
2. 保留具体细节：保留详细信息，包括具体风格、子流派和文化背景（例如：“Chinese traditional guofeng”，而不只是“Chinese music”）
3. 设计动态弧线：适当描述情绪变化过程（例如：“稀疏的开场 → 张力逐渐增强 → 宣泄式副歌”）
4. 合理推断：未明确说明参数时，根据流派惯例做出合理推断
5. 使用英语输出：最终提示词必须完全使用英语

生成结构化提示词： 将所有提取的参数组合成全面、流畅自然的描述，准确呈现用户设想的核心。

质量检查清单（生成前验证）

运行生成命令前，请确认提示词符合以下标准：

必须包含：

• 明确的流派（不是“流行歌曲”，而是“2020 年代的合成器流行乐”）
• BPM 或速度描述（例如“120 BPM”或“舒缓的律动”）
• 明确列出 3-5 种乐器
• 情绪描述（2-3 个词）
• 人声风格（或“纯器乐”）
• 歌词中包含结构标签：[Verse]、[Chorus]、[Bridge]、[Outro]

注意：

• 含糊的词语：“不错”“好”“美丽” → 替换为具体描述
• 相互矛盾的描述：“缓慢” + “充满活力”、“悲伤” + “振奋人心” → 选择一个方向
• 太短：<50 个字符 → 补充更多细节
• 歌词行过长：每行 >10 个词 → 拆分成较短的行
• 缺少动态变化：添加情绪递进（例如“稀疏 → 逐渐增强 → 饱满”）

避免：

• 命令式动词：“创作一首歌曲” → 使用描述性表达，如“轻快的流行歌曲”
• 知名艺人姓名：“听起来像 Taylor Swift” → 改为描述具体特质
• 不切实际的组合：melody_id 不能与其他控制选项组合使用

验证后，请先将生成的提示词呈现给用户确认，再继续操作。

---

核心工作流：制作流程

1. Conceptualize → User describes in natural language → YOU convert to structured prompt
2. Validate → Check prompt quality against Quality Checklist (see above)
3. Write Lyrics → Use lyrics/generate or write manually
4. Upload References → Optional: reference track, vocal sample, melody
5. Generate → Submit song/instrumental task (async) with validated prompt
6. Evaluate → Listen to all N choices, pick best
7. Iterate → Refine prompt based on what you heard

关键步骤：

• 当用户提供自然语言输入时（尤其是非英语输入），步骤 1 为必选
• 步骤 2 的验证可避免 80% 的常见生成失败
• 步骤 3：阅读 references/prompt_guide.md，了解提示词编写示例、歌词结构规则（行长、音节数、押韵模式、钩子写法）和迭代最佳实践
• 不要跳过构思阶段——没有明确概念就直接开始生成，是产生结果千篇一律的首要原因

你作为 AI 助手的职责：

1. 将用户的自然语言转换为结构化的 Mureka 提示词（使用智能提示词转换）
2. 验证提示词质量 → 标记问题 → 提出修改建议
3. 按照正确结构撰写或生成歌词
4. 将提示词呈现给用户确认
5. 使用通过验证的提示词执行生成命令
6. 根据生成结果帮助迭代和润色

---

CLI 工具

所有操作均通过单个脚本完成：scripts/mureka.py

mureka.py song           Generate a song with lyrics and vocals
mureka.py instrumental   Generate an instrumental track
mureka.py lyrics         Generate or extend lyrics
mureka.py upload         Upload reference audio, vocals, melodies

运行 python scripts/mureka.py --help 查看完整用法。注意：使用 -n 2（单连字符）生成多个选项，不要使用 --n。

---

常见场景

“我只想为视频配背景音乐”

python scripts/mureka.py instrumental \
  --prompt "ambient electronic, calm, 80 BPM, soft pads, no percussion, background music for tech product video" \
  --output ./bg_music

“我想要一首歌，但没有歌词”

# Step 1: Generate lyrics with proper structure
python scripts/mureka.py lyrics generate "a nostalgic summer love song, bittersweet, looking back at memories"

# Step 2: Copy/refine the output, then generate the song
python scripts/mureka.py song \
  --lyrics "[Verse]\n(paste lyrics here)\n[Chorus]\n(paste chorus here)" \
  --prompt "indie pop, warm, 110 BPM, acoustic guitar, soft drums, male vocal" \
  --output ./summer_song

---

高级功能

基于参考曲目生成

上传参考曲目（必须恰好 30s，格式为 mp3/m4a），用于引导风格：

python scripts/mureka.py upload my_reference.mp3 --purpose reference
# → File ID: 542321
python scripts/mureka.py song --lyrics "[Verse]\n..." --reference-id 542321 --output ./song

人声克隆

上传人声样本（15-30s，格式为 mp3/m4a），以使用特定音色：

python scripts/mureka.py upload my_voice.mp3 --purpose vocal
# → File ID: 789012
python scripts/mureka.py song --lyrics "[Verse]\n..." --vocal-id 789012 --prompt "R&B, smooth, 90 BPM" --output ./song

---

控制选项与规则

歌曲生成控制组合

生成歌曲时，以下控制选项可以组合使用：

组合	prompt	reference_id	vocal_id	melody_id
仅风格	✅
仅参考曲目		✅
仅人声			✅
仅旋律				✅
风格 + 人声	✅		✅
参考曲目 + 人声		✅	✅

重要：

• melody_id 不支持任何组合——请单独使用
• prompt 和 reference_id 互斥——二选一

器乐生成规则

对于器乐，prompt 和 instrumental_id 互斥——二选一。

文件上传要求

用途	格式	时长	备注
reference	mp3/m4a	恰好 30s	超出部分将被裁剪
vocal	mp3/m4a	15-30s	超出部分将被裁剪
melody	mp3/m4a/mid	5-60s	建议使用 MIDI
instrumental	mp3/m4a	恰好 30s	用作器乐参考

模型选择

始终使用 mureka-8——这是最新、质量最高的模型。

---

错误处理

脚本失败时会抛出 RuntimeError 或 requests.HTTPError。请处理常见错误：

错误	原因	操作
401 Unauthorized	API 密钥无效或已过期	请用户检查 MUREKA_API_KEY
429 Too Many Requests	超出速率限制	等待 30-60 秒后重试
402 / Insufficient balance	账户余额不足	引导用户前往 https://platform.mureka.ai 充值
Task ended with status: failed	生成失败（提示词不佳、服务端错误）	根据质量检查清单检查提示词，然后重试
Task ended with status: timeouted	生成耗时过长	重试；如果问题持续，请简化提示词或尝试其他模型
ConnectionError / Timeout	网络问题	几秒后重试

一般策略：仔细阅读错误消息。如果是客户端错误（4xx），请修正输入。如果是服务端错误（5xx）或超时，请先重试一次，再告知用户。

---

常见问题排查

问题	解决方案
任务失败或超时	• 检查提示词是否符合质量检查清单 • 确认歌词包含结构标签 • 重试生成
人声听起来很急促	• 缩短歌词行（≤10 个单词） • 减少每行的音节数
列出的乐器听不清	• 确认提示词中明确写出了每种乐器 • 添加更具体的描述（例如，“原声吉他扫弦”）
提示词与输出不符	• 提高具体程度（明确流派、BPM、乐器） • 添加情绪变化（“稀疏 → 饱满”） • 生成 n=3 个选项
melody_id 错误	• melody_id 必须单独使用 • 移除 --prompt、--reference-id、--vocal-id
file_id 无效	• 文件 ID 仅对上传该文件的账户有效 • 如果文件来自其他会话，请重新上传

参数帮助：

python scripts/mureka.py --help
python scripts/mureka.py song --help

---

环境

• API 密钥：MUREKA_API_KEY 环境变量（必需）
• 基础 URL：https://api.mureka.ai
• 依赖项：Python 3、requests 库
• 计费：使用 curl -H "Authorization: Bearer $MUREKA_API_KEY" https://api.mureka.ai/v1/account/billing 查看余额