Separation (vocal & backing split) API

Updated 2026-09-18 · Suno-API team

Endpoint description

Separation splits an existing song into vocals, backing or multi-track results. The recommended integration flow is:

1. If the source audio is not a song generated on this platform, call the upload source audio API first.
2. Call POST /api/music/separate to submit the separation task.
3. Poll the separation result with the song query API.
4. Use the download endpoints to download the audio file of each separation result.

Endpoint: POST /api/music/separate

Billing: Paid. stem_mode=two currently defaults to 0.6 ¥ per call; stem_mode=twelve is a multi-track split and currently defaults to 3.0 ¥ per call. The amount actually charged follows the back-office price configuration.

Wait times and timeouts (important): this is a synchronous endpoint — the order is only accepted and handed to generation when the response arrives. Measured, most requests return in 1-3 seconds, about 10% take longer than 30 seconds, and the longest is about 230 seconds. Set your client timeout to 300 seconds or more; no response does not mean nothing was generated, and do not retry immediately after a timeout (that duplicates the order and charges again). If the connection dropped, confirm later with GET /api/music/songs. See "Wait times and timeout settings" in the New API overview.

Authentication

Request parameters

About stem_mode

About separation

Separation is an independent fixed capability; there is no need to fill in or choose a song generation model. The customer simply submits the source song and stem_mode; the server handles the rest according to the mode.

Where the counts come from: one submission produces 2 versions (two results from the same batch of material), so the count is 2 × the track count of that mode: 4 for two, 24 for twelve. Always go by the actual length of the clips array in the response; do not hard-code a loop over a fixed count (individual tracks may fail while the successful ones are returned as usual).

Which tracks each mode returns

The 12 tracks of twelve mode (the names are fixed by the platform; the order may vary):

two mode returns two tracks, (Vocals) and (Instrumental), each in 2 versions. The track titles for both two and twelve are fixed names (they do not carry the source song name), so do not expect to see which song it was from the title.

Track titles cannot be used as unique keys. The two versions contain tracks with the same name (for example two (Vocals), two (Strings)), and one separation returns many tracks. Always use song_id as the identifier and song_title for display only; do not use array indexes either (the order may change).

Request examples

Vocal / backing separation (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"
  }'

Multi-track split (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"
  }'

Response

On success an array of separation results is usually returned. Each separation result is an independent song clip and must keep being queried until status becomes a completed state.

{
  "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"
      }
    ]
  }
}

The above shows only 2 of the 4 entries for two mode; in practice 4 are returned (2 versions × {(Vocals), (Instrumental)}); twelve mode returns 24. The real count is the length of the clips array.

Customers usually only need to save clips[].song_id; later queries and downloads revolve around those IDs.

Notes

• Separation results do not appear in the GET /api/music/songs song history (that list returns ordinary generated songs only). After a successful submission, save clips[].song_id immediately, otherwise you will have no way to find them later.
• Each track is an independent work: every track has its own song_id and must be polled to completion and downloaded separately.
• Billing is unrelated to the number of entries: it is charged per call (two 0.6 ¥ per call, twelve 3.0 ¥ per call), and 4 entries or 24 entries cost the same.
• Download: use that track's song_id with POST /api/music/download-url / download-file (free), or use the audio_url from the query result directly; for MIDI see the MIDI retrieval API.
• Do not submit twice: separation is a synchronous endpoint, so after a timeout confirm with the song query first instead of retrying directly (that duplicates the order and charges again).
• Hide tracks you no longer need with the stem delete API.

Querying separation results

After a successful submission, query the results with clips[].song_id via 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"
  }'

Example of a completed query:

[
  {
    "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"
  }
]

Downloading stem files

Once a separation result is complete, you can download a single stem file with the download endpoint.

Endpoint: 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 supports:

To package the related assets of one separation result, call:

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

Status values

Common errors

Compatibility notes

Older documentation used single-object examples such as success/task_id/vocals_url/instrumental_url. The current separation API works with the clips[] song array: every separation result has its own song_id, and later queries and downloads revolve around those song_id values.

Related pages

• If you only want to split vocals and backing without choosing a mode, use the vocal removal API; it is the two-track shortcut form of this endpoint and is currently free.
• Hide separation tracks you no longer need with the stem delete API (a soft delete, not charged).
• For the MIDI of a stem see the MIDI retrieval API; for audio, cover and other media see the song media download and preview API.