ステム分離（ボーカル・伴奏分離）API

2026-09-18 更新 · Suno-API チーム

インターフェースの説明

ステム分離は、既存の楽曲をボーカル・伴奏・マルチトラックの結果に分割します。推奨する接続手順は次のとおりです。

1. ソース音声が本プラットフォームで生成した楽曲でない場合は、先にソース音声アップロード APIを呼び出します。
2. POST /api/music/separate を呼び出してステム分離タスクを送信します。
3. 楽曲照会 API でステム分離結果をポーリングします。
4. ダウンロード用エンドポイントで各ステム分離結果の音声ファイルをダウンロードします。

エンドポイント: POST /api/music/separate

課金: 有料。stem_mode=two は現在既定で 1 回 0.6 元、stem_mode=twelve はマルチトラック分割で現在既定 1 回 3.0 元。実際の請求額は現在の管理画面の価格設定に従います。

待ち時間とタイムアウト（重要）: 本エンドポイントは同期インターフェースで、レスポンスが返った時点で初めて注文が受理され生成に投入されます。実測では多くのリクエストが 1〜3 秒で返り、約 10% が 30 秒を超え、最長は約 230 秒です。クライアントのタイムアウトは 300 秒以上に設定してください。レスポンスが無いことは未生成を意味せず、タイムアウト直後の再試行は注文の重複と二重課金につながります。 接続が切れた場合は少し後に GET /api/music/songs で確認できます。詳しくは新版 API 概要の「待ち時間とタイムアウト設定」をご覧ください。

認証

リクエストパラメータ

stem_mode の説明

ステム分離の説明

ステム分離は独立した固定機能で、楽曲生成モデルを入力・選択する必要はありません。お客様はソース楽曲と stem_mode を送るだけで、サーバーがモードに従って処理します。

件数の考え方：1 回の送信で 2 バージョン（同じ素材に対する 2 通りの結果）が生成されるため、件数 = 2 × そのモードのトラック数となります。two は 4 件、twelve は 24 件です。 レスポンスの clips 配列の実際の長さを基準にしてください。固定件数でループを組まないでください（一部のトラックが失敗し、成功したトラックは通常どおり返る場合があります）。

各モードが返すトラック

twelve モードの 12 トラック（名前はプラットフォームが固定で付与し、順序は変わることがあります）：

two モードは (Vocals) と (Instrumental) の 2 トラックを、それぞれ 2 バージョン返します。 two / twelve のトラック名はどちらも固定名（ソース楽曲名は含まれません）なので、タイトルからどの曲かを判断できるとは期待しないでください。

トラック名は一意キーとして使えません。 2 バージョンの中には同名のトラックが現れ（例：2 つの (Vocals)、2 つの (Strings)）、 しかも 1 回の分離で多数のトラックが返ります。識別子には必ず 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 を持ち、個別に完了まで照会し、個別にダウンロードする必要があります。
• 課金は件数と無関係：1 回ごとの課金（two は 1 回 0.6 元、twelve は 1 回 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 が使えます。 これは本エンドポイントの 2 トラック簡易版で、現在は無料です。
• 不要になったステム分離トラックはステム削除 API で非表示にできます（ソフト削除、課金なし）。
• ステムの MIDI は MIDI 取得 API、音声・カバーなどのメディアは 楽曲メディアのダウンロードと試聴 API を参照してください。