곡 미디어 다운로드 및 미리듣기 API

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

인터페이스 설명

이 엔드포인트 묶음은 "미디어 주소 가져오기"와 "실제 파일 다운로드"를 분리합니다.

• 바로 재생하거나 내려받을 수 있는 주소가 필요할 때(예: 자체 플레이어에 넣거나 오브젝트 스토리지로 옮길 때): POST /api/music/download-url, 또는 응답에 이미 들어 있는 GET /api/music/download를 사용합니다.
• 브라우저가 파일을 바로 저장하게 하려면: POST /api/music/download-file(단일 파일) 또는 POST /api/music/download-all(묶음)을 사용합니다.
• 곡이 아직 생성 중인데 먼저 들어보고 싶다면: POST /api/music/generation-stream-url을 사용합니다.

과금: 모두 무료. 다운로드와 미리듣기는 플랫폼이 이미 호스팅 중인 미디어를 읽기만 하고 Suno를 호출하지 않으며, 요금도 청구되지 않습니다.

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

인증

지원하는 미디어 형식(kind)

1) 미디어 주소 가져오기

curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id", "kind": "song"}'

{
  "code": 200,
  "message": "success",
  "data": {
    "song_id": "song_id",
    "kind": "song",
    "url": "https://media.suno-api.io/assets/song_id-mp3.mp3",
    "nav_url": "https://media.suno-api.io/assets/song_id-mp3.mp3?...&response-content-disposition=attachment..."
  }
}

url은 재생이나 직접 옮겨 저장할 때 씁니다. nav_url에는 Content-Disposition: attachment가 붙어 있어 브라우저 주소창에 그대로 붙여 내려받기에 적합합니다(일부 모바일 브라우저가 blob 다운로드를 지원하지 않을 때 사용하세요).

⚠️ 주소 유효 기간: 7일, 기한 내에 옮겨 저장하세요

url / nav_url은 플랫폼 오브젝트 스토리지를 가리키며 기본 7일 후 만료됩니다(파일이 회수되고 이전 주소는 404를 반환합니다). 이 7일 안에 자체 스토리지로 옮겨 저장하세요.

만료된 뒤에도 곡을 다시 생성할 필요는 없습니다. POST /api/music/download-url을 다시 호출하거나 refresh에 true를 넘기면 해당 곡의 새로운 유효 주소를 받습니다. 이 엔드포인트 묶음 자체는 무료이고 추가 과금이 없습니다.

2) 단일 파일 직접 다운로드

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id", "kind": "song"}' \
  -o song.mp3

응답 본문은 파일 스트림(JSON이 아님)이고 Content-Disposition에 파일명이 들어 있습니다. 가사와 타임라인 가사는 이 엔드포인트로만 받을 수 있습니다(download-url은 미디어 주소만 반환하고 가사는 반환하지 않습니다). .lrc 파일은 현재 일부 곡만 지원합니다. success:false가 반환되면 다음 절의 타임라인 가사 API 방식으로 .lrc를 직접 생성하세요. 재시도는 필요 없습니다.

타임라인 가사(.lrc) 가져오는 방법

어떤 곡에나 통하는 2단계를 권장합니다.

1단계: 단어별 타임라인 가져오기(무료)

curl -X POST https://www.suno-api.io/api/lyrics/timeline \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "suno-v6", "song_id": "song_id"}'

반환값은 그대로 배열입니다(data 래퍼가 없습니다). 각 요소는 {"word": "…", "start_s": 1.117, "end_s": 8.138, "success": true, "p_align": 0.99} 형태입니다. word에는 이미 줄바꿈이 들어 있으니 줄 단위로 나눌 수 있습니다. 필드 의미와 연주 구간 제외 같은 주의점은 타임라인 가사 API의 "필드 설명"과 "사용 시 주의"를 참고하세요.

2단계: start_s로 .lrc 직접 만들기(시간 형식 [mm:ss.cc])

def to_lrc(segments):
    lines = []
    for seg in segments:
        text = seg["word"].strip()
        if not text:
            continue
        start = max(0.0, float(seg["start_s"]))
        cs = int(start * 100 + 0.5)
        lines.append(f"[{cs // 6000:02d}:{(cs % 6000) // 100:02d}.{cs % 100:02d}]{text}")
    return "\n".join(lines)

GET /api/music/download?song_id=<id>&kind=lrc로도 서버가 만든 .lrc를 바로 내려받을 수 있지만 현재 일부 곡만 지원합니다. success:false가 반환되면 위 방식으로 직접 생성하세요. 재시도는 필요 없고 과금에도 영향이 없습니다.

3) 묶음 다운로드

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_ids": ["song_id_1", "song_id_2"]}' \
  -o songs.zip

song_id(단일)와 song_ids(일괄, 최대 50개) 중 하나를 사용합니다. 응답 본문은 ZIP 파일 스트림입니다.

4) 안정적인 다운로드 주소

GET /api/music/download?song_id=<id>&kind=<kind>는 곡 응답에 바로 들어 있는 다운로드 진입점입니다. API 키와 로그인 세션을 모두 허용하고 동작은 download-file과 동일하므로, 클라이언트나 서드파티 플레이어에 고정으로 넣기에 적합합니다.

5) 생성 중 미리듣기

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

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "song_id": "song_id_1",
        "url": "https://media.suno-api.io/assets/song_id_1-mp3.mp3",
        "expires_at": 0,
        "content_type": "audio/mpeg",
        "playable_until_completed": false,
        "mode": "mp3",
        "ranges": true
      }
    ]
  }
}

playable_until_completed가 true이면 생성 중인 곡의 임시 미리듣기 주소라는 뜻입니다. 곡이 완성되면 정식 주소로 바꿔 쓰세요. 한 곡이 실패하면 그 항목에 error 필드가 붙고 나머지 곡은 평소처럼 반환됩니다.

주의 사항

• 모든 엔드포인트는 플랫폼이 호스팅하는 미디어 주소만 반환하며, Suno 측의 암호화 소스나 임시 서명 주소는 반환하지 않습니다.
• 주소는 영구적이지 않습니다. 장기 보관이 필요하면 직접 옮겨 저장하세요. 원본 파일을 디스크에 저장해야 할 때는 download-file을 사용하세요.
• 스템의 MIDI는 해당 스템의 분리가 완료되어야 하며, 그렇지 않으면 오류를 반환합니다.