소스 clip 기반 커버 API

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

인터페이스 설명

소스 clip 기반 커버는 이미 업로드했거나 이미 존재하는 소스 clip을 재사용해, 그것을 바탕으로 새 커버 버전을 생성합니다.

엔드포인트: POST /api/music/generate-from-source

과금: 유료, 현재 기본 1회 0.6위안. 소스 오디오 업로드 자체는 무료이며, 소스 clip으로 커버를 생성할 때 과금됩니다. 실제 청구 금액은 현재 백오피스 가격 설정을 따릅니다.

Max Mode / Variety: 이 엔드포인트는 선택 파라미터 max_mode와 variety(0-4)를 지원합니다. max_mode를 켜면 이번 호출은 2배 가격으로 과금되며(0.6 → 1.2위안/회), variety는 추가 과금이 없습니다. 두 값의 의미와 사용법은 새 API 개요의 "고급 파라미터" 절을 참고하세요.

대기 시간과 타임아웃(중요): 이 엔드포인트는 동기 방식이며, 응답이 돌아온 시점에야 주문이 접수되어 생성에 넘겨집니다. 실측 기준 대부분의 요청은 1~3초에 반환되고, 약 10%는 30초를 넘기며, 최장 약 230초가 걸립니다. 클라이언트 타임아웃을 300초 이상으로 설정하세요. 응답이 없다고 해서 생성되지 않은 것이 아니며, 타임아웃 직후 재시도하면 주문이 중복되고 요금이 두 번 청구됩니다. 연결이 끊겼다면 잠시 후 GET /api/music/songs로 확인할 수 있습니다. 자세한 내용은 새 API 개요의 "대기 시간과 타임아웃 설정"을 참고하세요.

권장 사용법: '2단계 커버'의 2단계입니다. 1단계에서 소스 오디오 업로드 API로 업로드하고(무료) clip_id를 받습니다. 2단계에서 이 엔드포인트를 호출해 커버를 시작합니다. 이렇게 하면 오디오는 무료 단계에만 등장합니다. 업로드가 잘못돼도 그냥 다시 시도하면 되고 요금은 청구되지 않으며, 과금되는 단계의 요청 본문은 수백 바이트뿐이라 전송이 끊겨 실패할 일이 거의 없습니다. 한 번에 끝내는 업로드 후 커버 API는 오디오 전체를 요청 본문에 넣기 때문에, 오디오가 약 8MB를 넘으면 전송 중 잘려 unexpected end of JSON input을 반환하기 쉽습니다(해당 페이지의 "대용량 파일과 요청 잘림" 참고).

또한 같은 clip_id는 이어쓰기, 구간 교체, 스템 분리 등 후속 작업에도 재사용할 수 있어 오디오를 다시 올릴 필요가 없습니다.

요청 파라미터

Headers

Body 파라미터

weirdnessConstraint, styleWeight, audio_weight는 모두 0.0~`1.0의 비율 소수이며 백분율 정수가 아닙니다. 예를 들어 50%는 0.5로 씁니다. 0도 유효한 값이고, 필드를 생략했을 때만 "지정하지 않음"을 뜻합니다. audio_weight는 Suno의 metadata.control_sliders.audio_weight에 매핑되어 생성 결과가 참조 오디오에 얼마나 기대는지를 제어합니다. 요청에 유효한 sourceClipId나 참조 오디오가 있을 때만 실을 수 있으므로, 일반적인 텍스트만의 생성에는 보내지 마세요. customMode=true일 때는 prompt에 새 가사를 쓰고 style과 title을 함께 지정합니다. customMode=false일 때는 prompt에 창작 설명을 씁니다. instrumental과 waitAudio는 JSON 불리언 true/false`를 사용해야 합니다.

이 엔드포인트는 기본적으로 비동기로 반환합니다. 반환된 status가 pending일 때 audio_url이 비어 있는 것은 정상입니다. 완료를 기다린 뒤 오디오 주소를 사용하세요. sourceClipId는 실제 소스 곡/clip ID여야 하며, task_id, client_request_id, pending: 자리표시자 ID는 쓸 수 없습니다.

sourceClipId는 어떤 ID인가

sourceClipId는 이번 커버의 소스가 되는 실제 Suno clip 식별자입니다. 플랫폼의 대고객 곡 객체는 보통 이 식별자를 song_id라고 부르고, 커버 요청 파라미터는 sourceClipId라는 이름을 그대로 씁니다. 여기서 둘은 같은 실제 곡 ID를 가리킵니다.

소스가 강화 업로드라면 먼저 강화 업로드 작업을 조회해 status가 completed가 될 때까지 기다린 뒤, 반환된 실제 song_id를 sourceClipId에 넣으세요. 그 결과의 audio_url과 title을 각각 sourceAudioUrl, sourceTitle에 함께 넣는 것을 권장합니다.

강화 업로드의 task_id, client_request_id, pending:enhanced-upload:* 자리표시자 ID를 sourceClipId에 넣지 마세요.

요청 예시

curl -X POST https://www.suno-api.io/api/music/generate-from-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "sourceClipId": "uploaded_or_existing_clip_id",
    "sourceAudioUrl": "https://example.com/source.mp3",
    "sourceTitle": "원본 오디오 제목",
    "prompt": "새 가사 또는 창작 방향",
    "customMode": true,
    "style": "Mandopop, warm vocal",
    "title": "커버 제목",
    "negativeTags": "noise",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false
  }'

응답 결과

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "new_clip_id",
        "song_title": "커버 제목",
        "status": "pending"
      }
    ],
    "source_update": {}
  }
}

설명

이 엔드포인트는 소스 clip의 소유 계정 문제를 최대한 처리합니다. 소스 clip을 그대로 쓸 수 없으면 서버가 소스 오디오 정보를 바탕으로 다시 업로드한 뒤 생성할 수 있습니다.