반주 추가 API

2026-09-18 업데이트 · Suno-API 팀

인터페이스 설명

반주 추가는 기존 곡을 다시 편곡하거나 악기를 보강하거나 새로운 반주 구조를 생성합니다.

엔드포인트: POST /api/music/add-instrumental

과금: 유료. 요청한 모델에 따라 과금되며, 실제 청구 금액은 백오피스 가격 설정을 따릅니다.

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 개요의 "대기 시간과 타임아웃 설정"을 참고하세요.

인증

요청 파라미터

요청 예시

curl -X POST https://www.suno-api.io/api/music/add-instrumental \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "source_clip_id": "source_song_id",
    "lyrics": "",
    "style_tags": "cinematic, strings, acoustic guitar",
    "song_title": "반주 강화 버전",
    "audio_weight": 1,
    "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가 될 때까지 폴링하세요. 완료 후에는 audio_url로 재생하거나 다운로드할 수 있습니다. 자세한 내용은 WAV 생성/가져오기 API와 각 다운로드 엔드포인트를 참고하세요.

주의 사항

• source_clip_id는 실제로 존재하고 완료된, 현재 API Key로 접근 가능한 곡 ID여야 합니다. pending: 자리표시자 ID는 사용할 수 없습니다.
• 반주 추가는 커버가 아닙니다. 커버가 필요하면 소스 클립 기반 커버 API를 사용하세요.
• 기존 곡에 특정 악기나 트랙을 추가하려면 트랙 추가 API를 사용하세요.