Free2 다운로드 API

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

인터페이스 설명

Free2는 별도의 유료 다운로드 경로입니다. 곡 ID(또는 suno.com 곡 링크)로 MP3/WAV/가사/메타데이터 파일을 해석해 플랫폼이 호스팅하는 다운로드 주소를 반환합니다. API Key만 받으며, 브라우저 로그인 상태는 받지 않습니다. 반환값에 Suno의 암호화 재생 소스는 포함되지 않습니다.

엔드포인트: POST /api/music/free2

과금: 성공한 곡 수로 과금되며 현재 기본 곡당 0.2 위안입니다. 한 번의 요청에서 여러 파일 형식을 선택해도 추가 요금이 없습니다. 해석에 실패한 곡은 과금되지 않습니다. 요청당 최대 10곡(중복 제거 후)이며, 실제 청구 금액은 백오피스 가격 설정을 따릅니다.

권장 모델: suno-v6. suno-v6, suno-v6-wild, suno-v6-mini를 사용할 수 있습니다.

인증

파라미터	타입	필수	설명
Authorization	string	예	`Bearer YOUR_API_KEY`
Content-Type	string	예	`application/json`

요청 파라미터

파라미터	타입	필수	기본값	설명
song_id	string	아니오	-	단일 곡 ID. suno.com 곡 링크(`/s/` 단축 링크 포함)도 가능
song_ids	string[]	아니오	-	여러 곡 방식(권장). 요청당 최대 10곡
songs	string[]	아니오	-	`song_ids`의 별칭
files	string[]	예	-	필요한 파일 형식: `mp3`, `wav`, `lyrics`, `metadata`. `m4a`는 지원되지 않습니다

song_id와 song_ids 중 최소 하나를, files에는 최소 하나를 지정하세요.

요청 예시

curl -X POST https://www.suno-api.io/api/music/free2 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": ["song_id_1", "song_id_2"],
    "files": ["mp3", "wav", "lyrics"]
  }'

응답 결과

{
  "code": 200,
  "message": "success",
  "data": {
    "songs": [
      {
        "song_id": "song_id_1",
        "files": [
          {"type": "mp3", "url": "https://media.suno-api.io/assets/song_id_1-free2-v1-mp3.mp3"}
        ]
      },
      {
        "song_id": "song_id_2",
        "files": [],
        "error": {"code": "song_not_found", "message": "song not found or not owned by the current user"}
      }
    ],
    "requested_songs": 2,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

필드	타입	설명
songs	array	곡별 결과: `song_id`, `files[]`, 실패 시 `error`
requested_songs	number	정규화·중복 제거 후 곡 수
succeeded_songs	number	성공 수이며 과금은 이 숫자로 계산됩니다
price	number	이번 호출의 실제 청구 금액(위안)

곡을 하나만 요청하면 이전 단일 곡 형식과의 호환을 위해 응답에 최상위 song_id와 files도 함께 반환됩니다.

캐시 주소 재사용(과금 없음)

이미 다운로드한 적이 있는 곡은 다시 다운로드할 때 재해석도, 재과금도 필요하지 않습니다. POST /api/music/free2/cached로 해당 계정이 이전에 다운로드한 파일의 현재 주소를 받으세요.

엔드포인트: POST /api/music/free2/cached

과금: 무료. 읽기 전용 캐시로 해석·트랜스코딩·과금이 없으며, 이미 준비되어 회수되지 않은 주소만 반환합니다.

⚠️ 다운로드 주소 유효 기간은 7일입니다. 기한 내에 옮겨 저장하세요. songs[].files[].url은 플랫폼 객체 스토리지가 제공하며 기본 7일 후 만료됩니다(파일이 회수되고 이전 주소는 404를 반환합니다). 이 7일 안에 자체 저장소로 옮겨 저장하세요. 만료 후에는 POST /api/music/free2를 다시 호출해 새로 준비하면 유효한 새 주소를 받을 수 있습니다(이 재준비는 정상 과금 규칙으로 청구되며, /api/music/free2/cached는 여전히 유효한 캐시 주소만 반환합니다).

요청 파라미터: POST /api/music/free2와 완전히 같습니다(song_id / song_ids / songs 중 하나, files는 최소 하나).

curl -X POST https://www.suno-api.io/api/music/free2/cached \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "song_ids": ["98ca3f1d-…", "a185b3d9-…"], "files": ["mp3"] }'

{
  "success": true,
  "data": {
    "items": [
      { "song_id": "98ca3f1d-…", "type": "mp3", "url": "https://…/assets/98ca3f1d-…-free2-v1-mp3.mp3" }
    ],
    "songs": [
      { "song_id": "98ca3f1d-…", "files": [ { "type": "mp3", "url": "https://…" } ], "missing_files": [] },
      { "song_id": "a185b3d9-…", "files": [], "missing_files": ["mp3"] }
    ],
    "missing": ["a185b3d9-…"]
  }
}

필드	타입	설명
items	array	바로 다운로드할 수 있는 주소 목록(`song_id` + `type` + `url`)
songs	array	곡별 결과이며, `missing_files`는 이번에 캐시가 없었던 형식입니다
missing	string[]	이 곡은 쓸 수 있는 캐시가 하나도 없음(`POST /api/music/free2`로 다시 해석해야 하며, 그 단계는 곡당 과금됩니다)

주소는 이전에 다운로드한 적이 있는 곡에만 반환됩니다. 다운로드 기록이 없거나 자산이 이미 회수된 곡은 missing에만 나타나고 주소는 반환되지 않습니다.

주의 사항

POST /api/music/free2는 Suno의 모든 공개 곡(이 플랫폼에 없는 곡 포함)을 해석할 수 있습니다. 해석할 수 없는 곡은 그 곡에만 error가 반환되고 같은 배치의 다른 곡에는 영향이 없습니다. 반면 POST /api/music/free2/cached는 이 계정이 다운로드한 곡에만 주소를 반환합니다.
같은 곡의 첫 해석에서 호스팅 파일이 생성되고 이후에는 재사용됩니다. files에 중복 형식을 넣지 마세요. 서버가 자동으로 중복을 제거합니다.
곡 미디어 다운로드 및 미리듣기 API와의 차이: Free2는 유료이고 suno.com 링크를 직접 전달할 수 있으며, 가사 외의 타임라인/MIDI 같은 형식은 제공하지 않습니다.

다음곡 조회 및 기록 API

API 키 발급

가입 후 콘솔에서 API 키를 만들 수 있습니다. 1회 0.6위안으로 2곡이 생성되고, 다운로드는 횟수 제한이 없으며 휴대폰 번호는 필요하지 않습니다.

API 키 받기 개요로 돌아가기