直接答案：已有伴奏、需要补人声，用
POST /api/music/add-vocal；已有歌曲、想重新补乐器或生成新的伴奏结构，用POST /api/music/add-instrumental。两者都以真实source_clip_id为来源，通常一次返回 2 条新结果。
先分清两个方向
| 目标 | 接口 | 重点参数 |
|---|---|---|
| 给伴奏加人声、重写人声 | /api/music/add-vocal | lyrics、style_tags |
| 给歌曲补乐器、重做伴奏 | /api/music/add-instrumental | style_tags、audio_weight、duration |
加人声示例
curl -X POST "https://www.suno-api.io/api/music/add-vocal" -H "Authorization: Bearer $SUNO_API_KEY" -H "Content-Type: application/json" -d '{
"model": "suno-v6",
"source_clip_id": "source_song_id",
"lyrics": "[Verse]\n夜色落在窗前\n[Chorus]\n我们向光而行",
"style_tags": "warm male vocal, mandopop, intimate",
"song_title": "人声增强版本",
"instrumental": false
}'加伴奏示例
curl -X POST "https://www.suno-api.io/api/music/add-instrumental" -H "Authorization: Bearer $SUNO_API_KEY" -H "Content-Type: application/json" -d '{
"model": "suno-v6",
"source_clip_id": "source_song_id",
"style_tags": "cinematic, strings, acoustic guitar",
"song_title": "伴奏增强版本",
"audio_weight": 1,
"duration": 60
}'audio_weight 和 duration
audio_weight 控制生成结果对参考音频的依赖程度，范围 0–1；越接近 1 通常越强调保留来源特征。加伴奏的 duration 范围 1–480 秒，但平台实际最短约 30 秒。
完整流程
- 确认来源歌曲已经完成，并保存真实 song_id；
- 选择 add-vocal 或 add-instrumental；
- 提交后保存返回的两条 clip ID；
- 轮询歌曲查询接口直到 completed；
- 下载 MP3/WAV，或继续进入分轨与 MIDI。
什么时候不要用这两个接口
- 要换整首歌的演唱声音：优先看翻唱或克隆音色；
- 要把现有歌拆成人声/伴奏：使用 separate；
- 要单独增加某条乐器轨：使用 add-stem；
- 只改一个短段落：使用 replace-section。
常见错误
| 错误 | 原因 | 处理 |
|---|---|---|
| source_clip_id 无效 | 用了占位 ID 或无权访问 | 使用当前 Key 可读的真实 song_id |
| 生成结果偏离原曲 | audio_weight 低或风格标签冲突 | 提高参考权重，减少冲突标签 |
| 重复扣费 | 超时后立即重提 | 先查歌曲历史再决定 |
常见问题
add-vocal 和翻唱有什么区别？
add-vocal 重点是给已有来源补人声；翻唱更强调生成新的演唱版本，具体看是否保留原编曲。
add-instrumental 会增加一条单独轨道吗？
不会。它生成新的伴奏版本；要独立轨道请用 add-stem 或分轨。
source_clip_id 能用 pending ID 吗？
不能，必须是已完成且可访问的真实歌曲 ID。
接口文档：增加人声 API、增加伴奏 API；继续阅读 十二轨分离、Max Mode 与 Variety。
