음악 상업적 이용 허가서 API

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

인터페이스 설명

음악 상업적 이용 허가서 엔드포인트는 현재 API Key가 속한 사용자가 허가할 수 있는 곡을 조회하고, PDF 허가서를 생성하고, 허가서 이력을 조회하고, 발급된 파일을 내려받는 데 사용합니다.

모든 엔드포인트는 New API Key를 공통으로 사용합니다.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

기본 주소:

https://www.suno-api.io

사용 전제

• API Key가 유효하고, 허가서를 발급받아야 하는 사용자에게 속해 있어야 합니다.
• 사용자는 먼저 허가 신원을 연결해야 합니다(아래 "0. 허가 자격과 신원" 참고). 한 번 확정되면 제품 규칙에 따라 잠깁니다.
• 개인 또는 기업 누적 충전 자격 요건을 충족해야 합니다.
• 일반 엔드포인트는 마스킹된 신원 정보만 반환하며, 주민등록번호·전화번호·통일사회신용코드 같은 평문은 반환하지 않습니다.
• 곡 한 곡당 성공적으로 발급되는 허가서는 한 부뿐입니다. 생성에 실패한 허가서는 곡의 자격을 소모하지 않습니다.
• 현재 지원되는 것은 완료되었고 오디오가 있으며 실제 Suno Song ID가 있는 지정 생성 유형입니다. 선택 가능 여부는 곡 목록의 authorization.selectable을 기준으로 합니다.

0. 허가 자격과 신원

허가서를 발급하기 전에 자격을 조회하고 신원을 연결해야 합니다. 두 엔드포인트 모두 무료입니다.

0.1 허가 자격과 신원 상태 조회

엔드포인트: GET /api/music/authorization/context

{
  "code": 200,
  "message": "success",
  "data": {
    "identity": {
      "exists": false
    },
    "eligibility": {
      "current_amount": 216.3,
      "personal_required_amount": 200,
      "company_required_amount": 500,
      "personal_eligible": true,
      "company_eligible": false
    },
    "stats": {
      "authorized_song_count": 0,
      "certificate_count": 0
    }
  }
}

0.2 허가 신원 연결

엔드포인트: POST /api/music/authorization/identity

{
  "identity_type": "personal",
  "legal_name": "김민준",
  "id_number": "110101199001010000",
  "contact_name": "김민준",
  "phone": "13800000000",
  "email": "user@example.com",
  "address": "서울특별시 강남구",
  "confirm_locked": true
}

응답은 마스킹된 신원 정보({"identity": {...}})를 반환합니다. 연결에 성공하면 context 엔드포인트로 identity.exists가 true가 되었는지 확인한 뒤 곡 목록과 발급 엔드포인트를 호출하세요. 신원 정보를 변경해야 하면 고객센터에 문의하세요.

1. 허가 가능한 곡 조회

엔드포인트: GET /api/music/authorization/songs

Query 파라미터

요청 예시

curl "https://www.suno-api.io/api/music/authorization/songs?p=1&page_size=20&status=selectable" \
  -H "Authorization: Bearer YOUR_API_KEY"

응답 예시

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "items": [
      {
        "task_id": 10001,
        "suno_song_id": "suno-song-id-1",
        "title": "예시 곡",
        "generation_type": "generate",
        "completed_at": 1784000000,
        "created_at": 1783999000,
        "audio_url": "https://example.com/audio.mp3",
        "model_name": "suno-v6",
        "authorization": {
          "selectable": true
        }
      }
    ]
  }
}

authorization.selectable=false이면 응답은 reason_code와 reason으로 허가할 수 없는 이유를 설명합니다. 이미 허가서를 발급한 곡은 certificate_id와 certificate_no도 반환합니다.

2. 허가서 생성

엔드포인트: POST /api/music/authorization/certificates

Body 파라미터

요청 예시

curl -X POST https://www.suno-api.io/api/music/authorization/certificates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": ["suno-song-id-1", "suno-song-id-2"],
    "confirm_risk_terms": true
  }'

응답 예시

{
  "success": true,
  "message": "",
  "data": {
    "certificate": {
      "id": 101,
      "certificate_no": "CERTIFICATE-NO",
      "verification_code": "VERIFY-CODE",
      "status": "issued",
      "song_count": 2,
      "identity_type_snapshot": "personal",
      "licensee_name_masked": "김*",
      "document_no_masked_snapshot": "11**************34",
      "phone_masked_snapshot": "138****0000",
      "pdf_sha256": "PDF_SHA256",
      "issued_at": 1784000100,
      "created_at": 1784000000,
      "updated_at": 1784000100,
      "download_url": "/api/music/authorization/certificates/101/download",
      "songs": []
    }
  }
}

성공 응답의 status는 issued입니다. PDF 렌더링이 실패하면 허가서는 failed로 표시되며, 해당 곡은 문제를 해결한 뒤 다시 제출할 수 있습니다.

3. 허가서 이력 조회

엔드포인트: GET /api/music/authorization/certificates

Query 파라미터

요청 예시

curl "https://www.suno-api.io/api/music/authorization/certificates?p=1&page_size=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

응답 구조

응답의 data는 page, page_size, total, items를 포함하는 페이지 객체입니다. items의 각 항목은 허가서 요약이며 해당 허가서의 곡 스냅숏을 포함합니다.

4. 허가서 상세 조회

엔드포인트: GET /api/music/authorization/certificates/:id

경로 파라미터 id는 허가서의 숫자 ID입니다. 이 엔드포인트는 현재 API Key가 속한 사용자 자신의 허가서에만 접근할 수 있습니다.

요청 예시

curl https://www.suno-api.io/api/music/authorization/certificates/101 \
  -H "Authorization: Bearer YOUR_API_KEY"

응답 구조

성공 시 data.certificate를 반환하며, 필드에는 허가서 번호, 상태, 마스킹된 허가자 정보, 발급 시각, PDF 검증값, 다운로드 주소, 허가 곡 스냅숏이 포함됩니다.

5. 허가서 PDF 다운로드

엔드포인트: GET /api/music/authorization/certificates/:id/download

상태가 issued인 허가서만 내려받을 수 있습니다. 다운로드 요청에도 유효한 API Key가 필요하며, 현재 사용자 자신의 허가서만 내려받을 수 있습니다.

요청 예시

curl https://www.suno-api.io/api/music/authorization/certificates/101/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output authorization-certificate.pdf

성공 응답은 application/pdf 파일 스트림이며, 파일 이름은 백엔드의 Content-Disposition을 따릅니다.

자주 발생하는 실패 원인

주의 사항

• 곡 목록이 반환하는 suno_song_id를 사용하고, pending:* 자리표시자 ID나 작업 테이블 ID는 쓰지 마세요.
• 다운로드 주소는 공개 링크가 아니므로 API Key 인증을 제거하지 마세요.
• 허가서 기록은 API Key에 대응하는 사용자에게 속하며, 사용자 간 조회·다운로드는 불가능합니다.
• 허가 범위, 제한 조항 및 최종 PDF 내용은 실제 발급된 허가서를 기준으로 합니다.