Replace Section(구간 교체) API

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

인터페이스 설명

구간 교체는 기존 곡의 지정한 시간 구간을 부분적으로 다시 생성합니다. 한 줄 가사를 고치거나 특정 구간을 바꾸는 데 적합합니다.

엔드포인트: POST /api/music/replace-section

과금: 유료, 현재 기본 1회 0.6위안. 실제 청구 금액은 현재 백오피스 가격 설정을 따릅니다.

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

요청 파라미터

Headers

Body 파라미터

startSeconds, endSeconds의 단위는 초이며 소수점을 쓸 수 있습니다. startSeconds는 endSeconds보다 작아야 하고 구간은 원곡 길이 안에 있어야 합니다. requestedAt은 요청 시각을 전달해야 할 때만 쓰며, 단위는 Unix 초 단위 타임스탬프(밀리초 아님)이고 보통 생략할 수 있습니다.

교체도 비동기 작업입니다. 반환된 clip의 초기 상태는 pending일 수 있고, 그때 오디오 주소가 비어 있는 것은 정상입니다. 반환된 실제 song_id로 최종 결과를 조회하세요.

구간 길이: 최소 2초(중요)

교체할 구간은 2초보다 짧을 수 없습니다. 실측: 1.0 / 1.2 / 1.5초 구간은 모두 실패했고 2.0초 이상은 정상이었습니다.

구간이 너무 짧으면 플랫폼은 "파라미터 오류"가 아니라 오해하기 쉬운 메시지를 돌려줍니다:

{"error":{"message":"You don't have access to this model. Upgrade your plan to use it.",
          "type":"bad_response_status_code","code":"bad_response_status_code"}}

이 문장은 계정이나 요금제 문제가 아닙니다. 구간이 너무 짧은 것입니다. 구간을 2초 이상으로 늘려 다시 보내세요.

요청 예시

curl -X POST https://www.suno-api.io/api/music/replace-section \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "audioId": "clip_id",
    "startSeconds": 30,
    "endSeconds": 45,
    "contextLyrics": "전체 컨텍스트 가사",
    "contextWindowLyrics": "주변 컨텍스트 가사",
    "infillLyrics": "교체 후 가사",
    "style": "Mandopop, acoustic",
    "title": "교체 버전",
    "negativeTags": "noise"
  }'

응답 결과

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "replace_clip_id",
        "song_title": "교체 버전",
        "status": "pending"
      }
    ],
    "replaceTask": "infill",
    "clipId": "clip_id",
    "source_update": {}
  }
}

호환 필드

• audioId / audio_id / clipId / clip_id
• startSeconds / start_seconds / infillStartS / infill_start_s
• endSeconds / end_seconds / infillEndS / infill_end_s
• infillLyrics / infill_lyrics / replacementLyrics / replacement_lyrics
• style / tags
• negativeTags / negative_tags