스템 분리(보컬·반주 분리) 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만 제출하면 되고, 서버가 모드에 따라 처리합니다.

개수가 나오는 방식: 한 번 제출하면 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 모드의 4개 중 2개만 보여줍니다. 실제로는 4개가 반환됩니다(2개 버전 × {(Vocals), (Instrumental)}). twelve 모드는 24개가 반환됩니다. 실제 개수는 clips 배열 길이를 기준으로 하세요.

고객은 보통 clips[].song_id만 저장하면 되고, 이후 조회와 다운로드가 이 ID들을 중심으로 이루어집니다.

주의 사항

• 스템 분리 결과는 GET /api/music/songs 곡 이력에 나타나지 않습니다(그 목록은 일반 생성 곡만 반환합니다). 제출에 성공하면 즉시 clips[].song_id를 저장하세요. 그렇지 않으면 나중에 찾을 방법이 없습니다.
• 트랙은 독립된 작품입니다: 각 트랙이 자체 song_id를 가지며, 각각 완료까지 조회하고 각각 내려받아야 합니다.
• 과금은 개수와 무관합니다: 호출당 과금(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를 참고하세요.