分軌（人聲伴奏分離）API

2026-09-18 更新 · Suno-API 團隊

介面說明

分軌用於把已有歌曲拆分為人聲、伴奏或多軌結果。建議按以下流程接入：

1. 如果來源音訊不是本平台生成的歌曲，可先呼叫上傳來源音訊 API。
2. 呼叫 POST /api/music/separate 提交分軌任務。
3. 使用歌曲查詢與歷史 API 輪詢分軌結果。
4. 使用下載介面下載每條分軌結果的音訊檔案。

介面位址：POST /api/music/separate

計費：收費。stem_mode=two 目前預設 0.6 元/次；stem_mode=twelve 為多軌拆分，目前預設 3.0 元/次。實際扣費以後台價格設定為準。

等待時間與逾時（重要）：本介面是同步介面，回應返回時才代表訂單已被受理並提交生成。實測多數請求 1–3 秒返回，約 10% 超過 30 秒，最長約 230 秒。請把用戶端逾時設為 300 秒以上；未收到回應不等於沒有生成，逾時後請勿立即重試（會重複下單、重複扣費）。 連線中斷可稍後用 GET /api/music/songs 確認。詳見 Suno API 介面文件總覽的「等待時間與逾時設定」。

驗證

請求參數

stem_mode 說明

分軌說明

分軌是獨立的固定能力，不需要填寫或選擇歌曲生成模型。客戶只需提交來源歌曲和 stem_mode；伺服器會按分軌模式處理。

條數怎麼來的：一次提交會產出 2 個版本（同一批素材的兩種結果），所以條數 = 2 × 該模式的軌道數：two 是 4 條，twelve 是 24 條。 請以回應裡 clips 陣列的實際長度為準，不要按固定條數寫死迴圈（個別軌道可能失敗，成功的軌道照常回傳）。

各模式回傳哪些軌道

twelve 模式的 12 條軌道（名稱由平台固定給出，順序可能變化）：

two 模式回傳 (Vocals) 與 (Instrumental) 兩條軌道，各 2 個版本。 two／twelve 的軌道標題都是固定名（不帶來源歌曲名），別指望從標題裡看出是哪首歌。

軌道標題不能當唯一鍵。 兩個版本裡會出現同名軌道（例如兩條 (Vocals)、兩條 (Strings)）， 而且一次分軌會回傳多條軌道。請一律用 song_id 作為識別，song_title 只用於顯示； 也不要用陣列索引（順序可能變化）。

請求範例

人聲／伴奏分離（stem_mode: "two"）

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "two",
    "source_audio_url": "https://example.com/source.mp3",
    "source_file_name": "source.mp3",
    "source_title": "Source Song"
  }'

多軌拆分（stem_mode: "twelve"）

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "twelve",
    "source_audio_url": "https://example.com/source.mp3"
  }'

回應結果

成功後通常會回傳分軌結果陣列。每個分軌結果都是一個獨立歌曲 clip，需要繼續查詢直到 status 變為完成狀態。

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "stem_clip_id_1",
        "song_title": "(Vocals)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      },
      {
        "song_id": "stem_clip_id_2",
        "song_title": "(Instrumental)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      }
    ]
  }
}

上面只展示了 two 模式其中 2 條，實際會回傳 4 條（2 個版本 × {(Vocals)、(Instrumental)}）； twelve 模式會回傳 24 條。真實條數以 clips 陣列長度為準。

客戶一般只需要保存 clips[].song_id，後續查詢與下載都圍繞這些 ID 進行。

注意事項

• 分軌結果不會出現在 GET /api/music/songs 歌曲歷史裡（該列表只回傳一般生成歌曲）。提交成功後請立刻保存 clips[].song_id，否則後續無從查找。
• 軌道是獨立作品：每條軌道都有自己的 song_id，需要各自輪詢到完成、各自下載。
• 計費與條數無關：按次計費（two 0.6 元/次、twelve 3.0 元/次），回傳 4 條還是 24 條都是同一價格。
• 下載：用該軌道的 song_id 走 POST /api/music/download-url / download-file（免費），或直接用查詢結果裡的 audio_url；取 MIDI 見MIDI 取得 API。
• 不要重複提交：分軌是同步介面，逾時後請先用歌曲查詢確認，不要直接重試（會重複下單、重複扣費）。
• 不再需要的軌道用分軌刪除 API 隱藏。

查詢分軌結果

提交成功後，使用 clips[].song_id 呼叫 POST /api/music/query 查詢結果。

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": "stem_clip_id_1,stem_clip_id_2"
  }'

查詢完成範例：

[
  {
    "song_id": "stem_clip_id_1",
    "song_title": "(Vocals)",
    "status": "complete",
    "audio_url": "https://...",
    "cover_url": "https://...",
    "duration": 180.5,
    "generation_type": "separate",
    "stem_from_id": "source_clip_id"
  }
]

下載分軌檔案

分軌結果完成後，可用下載介面下載單個分軌檔案。

介面位址：POST /api/music/download-file

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "stem_clip_id_1",
    "kind": "audio"
  }' \
  --output stem.mp3

kind 支援：

如需打包下載某條分軌結果的相關資源，可呼叫：

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "stem_clip_id_1"
  }' \
  --output stem-resources.zip

狀態說明

常見錯誤

相容說明

舊版文件曾使用 success/task_id/vocals_url/instrumental_url 這類單物件範例。目前新版分軌以 clips[] 歌曲陣列為準，每條分軌結果都擁有獨立 song_id，後續查詢與下載都圍繞這些 song_id 進行。

相關頁面

• 只想把人聲和伴奏分開、不需要選擇模式時，可用人聲去除 API， 它是本介面的兩軌快捷形式且目前免費。
• 不再需要的分軌軌道用分軌刪除 API 隱藏（軟刪除，不扣費）。
• 取分軌的 MIDI 見MIDI 取得 API，取音訊／封面等媒體見 歌曲媒體下載與試聽 API。