增加伴奏 API
介面說明
增加伴奏用於在既有歌曲上重新編曲、補充樂器或生成新的伴奏結構。
介面位址：POST /api/music/add-instrumental
計費：收費，依請求模型計費，實際扣費以後台價格設定為準。
Max Mode / Variety：本介面支援選用參數 max_mode 與 variety（0-4）。開啟 max_mode
時本次依 2 倍價格計費，variety 不額外計費；兩者含義與寫法見
Suno API 介面文件總覽 的「進階參數」一節。
推薦模型：suno-v6。可用 suno-v6、suno-v6-wild 或 suno-v6-mini。
等待時間與逾時（重要）：本介面是同步介面，回應返回時才代表訂單已被受理並提交生成。實測多數請求 1–3 秒返回，約 10% 超過 30 秒，最長約 230 秒。請把用戶端逾時設為 300 秒以上；未收到回應不等於沒有生成，逾時後請勿立即重試（會重複下單、重複扣費）。 連線中斷可稍後用
GET /api/music/songs確認。詳見 Suno API 介面文件總覽的「等待時間與逾時設定」。
驗證
| 參數名 | 型別 | 必填 | 說明 |
|---|---|---|---|
| Authorization | string | 是 | Bearer YOUR_API_KEY |
| Content-Type | string | 是 | application/json |
請求參數
| 參數名 | 型別 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
| model | string | 是 | - | 對客模型名：suno-v6、suno-v6-wild 或 suno-v6-mini |
| source_clip_id | string | 是 | - | 來源歌曲的真實 song_id，必須已完成且目前 API Key 可存取 |
| lyrics | string | 否 | - | 新歌詞或創作方向 |
| style_tags | string | 否 | - | 風格標籤 |
| song_title | string | 否 | - | 結果標題 |
| negative_tags | string | 否 | - | 負向風格標籤 |
| audio_weight | number | 否 | 1 | 參考音訊影響權重，範圍 0.0-1.0；預設 1 表示盡量保持原歌曲參考 |
| duration | integer | 否 | - | 期望生成時長，單位秒，範圍 1-480。平台實際最短約 30 秒：填 10 秒實測出來仍是 29.96 / 29.76 秒 |
| wait_completion | boolean | 否 | false | 是否等待較長時間再返回；建議保持非同步使用 |
請求範例
curl -X POST https://www.suno-api.io/api/music/add-instrumental \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "suno-v6",
"source_clip_id": "source_song_id",
"lyrics": "",
"style_tags": "cinematic, strings, acoustic guitar",
"song_title": "伴奏增強版本",
"audio_weight": 1,
"wait_completion": false
}'
回應結果
{
"code": 200,
"message": "success",
"data": {
"clips": [
{
"song_id": "result_song_id",
"song_title": "伴奏增強版本",
"status": "pending"
},
{
"song_id": "result_song_id_2",
"song_title": "伴奏增強版本",
"status": "pending"
}
]
}
}
一次回傳 2 條結果（按 2 首計費）；範例已按 2 條展示。請以 clips 陣列長度為準，不要按固定條數寫死迴圈。保存 clips[].song_id 後，用歌曲查詢 API輪詢到 completed。完成後可使用 audio_url 播放或下載，詳見 WAV 生成/取得 API和各下載介面。
注意事項
source_clip_id必須是真實、已完成且目前 API Key 可存取的歌曲 ID，不能使用pending:佔位 ID。- 增加伴奏不是翻唱；需要翻唱時請使用基於來源 clip 翻唱 API。
- 需要給既有歌曲增加指定樂器或音軌時，請使用加軌 API。