보컬 추가 API
인터페이스 설명
보컬 추가는 기존 곡이나 연주 소재에 보컬을 생성·재작성·보완합니다.
엔드포인트: POST /api/music/add-vocal
과금: 유료. 요청한 모델에 따라 과금되며, 실제 청구 금액은 백오피스 가격 설정을 따릅니다.
Max Mode / Variety: 이 엔드포인트는 선택 파라미터 max_mode와 variety(0-4)를 지원합니다.
max_mode를 켜면 이번 호출은 2배 가격으로 과금되며, variety는 추가 과금이 없습니다. 두 값의 의미와
사용법은 새 API 개요의 "고급 파라미터" 절을 참고하세요.
권장 모델: suno-v6. suno-v6, suno-v6-wild, suno-v6-mini를 사용할 수 있습니다.
대기 시간과 타임아웃(중요): 이 엔드포인트는 동기 방식이며, 응답이 돌아온 시점에야 주문이 접수되어 생성에 넘겨집니다. 실측 기준 대부분의 요청은 1~3초에 반환되고, 약 10%는 30초를 넘기며, 최장 약 230초가 걸립니다. 클라이언트 타임아웃을 300초 이상으로 설정하세요. 응답이 없다고 해서 생성되지 않은 것이 아니며, 타임아웃 직후 재시도하면 주문이 중복되고 요금이 두 번 청구됩니다. 연결이 끊겼다면 잠시 후
GET /api/music/songs로 확인할 수 있습니다. 자세한 내용은 새 API 개요의 "대기 시간과 타임아웃 설정"을 참고하세요.
인증
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| 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로 접근할 수 있어야 합니다 |
| lyrics | string | 아니오 | - | 추가하거나 교체할 보컬 가사 |
| style_tags | string | 아니오 | - | 보컬 스타일, 창법 또는 화음 요구 사항 |
| song_title | string | 아니오 | - | 결과 제목 |
| negative_tags | string | 아니오 | - | 제외 스타일 태그 |
| instrumental | boolean | 아니오 | false | 순수 연주곡인지 여부. 보컬 추가에서는 보통 false로 둡니다 |
| wait_completion | boolean | 아니오 | false | 오래 기다린 뒤 반환할지 여부 |
요청 예시
curl -X POST https://www.suno-api.io/api/music/add-vocal \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "suno-v6",
"source_clip_id": "source_song_id",
"lyrics": "[Verse]\n창밖에 밤이 내리고\n[Chorus]\n우리는 빛을 향해 걷는다",
"style_tags": "warm male vocal, mandopop, intimate",
"song_title": "보컬 강화 버전",
"instrumental": false,
"wait_completion": false
}'
응답 결과
{
"code": 200,
"message": "success",
"data": {
"clips": [
{
"song_id": "result_song_id",
"song_title": "보컬 강화 버전",
"status": "pending"
},
{
"song_id": "result_song_id_2",
"song_title": "보컬 강화 버전",
"status": "pending"
}
]
}
}
한 번 호출에 2건이 반환됩니다(2곡으로 과금). 예시도 2건으로 표시했습니다. clips 배열 길이를 기준으로 하고 고정 개수로 루프를 짜지 마세요. clips[].song_id를 저장하고 곡 조회 API로 completed가 될 때까지 폴링하세요.
주의 사항
- 보컬 추가는 "소스 곡 위에 보컬을 생성하거나 다시 쓰는 것"이며,
vocal_gender성별 지정과는 다릅니다. - 클론한 목소리를 지정하려면 【권장】 음색 클론 API를 사용하세요. 보이스 클론 및 지정 음색 생성 API(구 경로)는 새 연동에 권장하지 않습니다.