보컬 제거 API
인터페이스 설명
보컬 제거는 기존 곡을 보컬과 반주 두 트랙으로 분리합니다. '스템 분리(보컬·반주 분리)'의 단축형으로, 호출 측은 소스 곡 ID 하나만 넘기면 되고 분리 모드를 고를 필요가 없습니다. 서버는 항상 2트랙(two)으로 처리합니다.
엔드포인트: POST /api/music/vocal-removal
과금: 무료. 이 엔드포인트는 트랙 분리만 수행하며 생성 비용이 발생하지 않고 과금 기록도 남기지 않습니다.
권장 모델: suno-v6. suno-v6, suno-v6-wild, suno-v6-mini를 사용할 수 있습니다.
인증
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| 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로 접근할 수 있어야 합니다 |
| source_audio_url | string | 아니오 | - | 소스 오디오 주소(소스가 다른 계정에 속한 경우 서버가 중계하므로 클라이언트가 보낼 필요는 없습니다) |
| source_file_name | string | 아니오 | - | 소스 파일 이름. 로그와 표시에만 사용됩니다 |
| song_title | string | 아니오 | - | 결과 제목 접두사. 기본값은 소스 곡 제목을 그대로 사용합니다 |
호환 별칭: sourceClipId, audio_id, audioId, song_id를 모두 source_clip_id 대신 사용할 수 있습니다.
요청 예시
curl -X POST https://www.suno-api.io/api/music/vocal-removal \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "suno-v6",
"source_clip_id": "source_song_id",
"song_title": "보컬 제거"
}'
응답 결과
{
"code": 200,
"message": "success",
"data": {
"clips": [
{
"song_id": "vocals_clip_id",
"song_title": "보컬 제거 (Vocals)",
"status": "pending",
"stem_from_id": "source_song_id",
"stem_mode": "two"
},
{
"song_id": "instrumental_clip_id",
"song_title": "보컬 제거 (Instrumental)",
"status": "pending",
"stem_from_id": "source_song_id",
"stem_mode": "two"
}
]
}
}
한 번 제출하면 **2개 버전 × {Vocals, Instrumental}**이 반환되므로 clips는 보통 4건입니다. stem_from_id로 그룹화하고 song_title 접미사로 보컬과 반주를 구분하세요.
주의 사항
- 결과 트랙은 곡 조회 API(
POST /api/music/query)로completed가 될 때까지 폴링한 뒤 사용하세요.GET /api/music/songs/:song_id와 곡 기록 목록은 현재 보컬 제거가 만든 트랙을 포함하지 않습니다. 이는 알려진 차이입니다. - 2트랙/멀티트랙 모드를 선택하거나 트랙 이름으로 직접 분리하려면 스템 분리(보컬·반주 분리) API를 사용하세요.
- 불필요한 트랙은 스템 삭제 API로 숨길 수 있습니다. 삭제 요청을 반복해서 보내지 마세요.