곡 조회 및 기록 API

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

이 페이지는 무료 조회 엔드포인트 세 가지를 다룹니다:

생성 엔드포인트의 접수 영수증 모드(accept_mode=async)를 사용했다면, 손에 있는 것은 곡 ID가 아니라 접수 번호입니다. 진행 상황은 GET /api/music/requests/{request_id}로 조회하고, 실제 song_id를 받은 뒤 이 페이지의 엔드포인트로 돌아오세요. 자세한 내용은 영감 모드 생성 API의 "접수 영수증 모드"를 참고하세요.

인증과 데이터 범위

세 엔드포인트 모두 같은 API Key로 인증합니다:

Authorization: Bearer YOUR_API_KEY

곡 기록은 API Key가 속한 user_id 단위로 분리됩니다. 같은 메인 계정에서 만든 여러 API Key는 그 메인 계정의 곡 기록을 조회할 수 있지만, 다른 사용자나 하위 사이트 계정의 곡은 조회할 수 없습니다.

기록 계열 엔드포인트는 실제로 생성된 곡만 반환하며, 다음은 포함하지 않습니다:

• pending:으로 시작하는 생성 자리표시자 기록;
• 소스 오디오 업로드와 강화 업로드 기록;
• 보컬/반주 분리, 스템 같은 부속 결과;
• 다른 사용자나 하위 사이트 계정의 곡.

1. 생성 상태 조회

하나 또는 여러 곡 ID로 현재 생성 상태와 최종 결과를 조회합니다.

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

과금: 무료.

Headers

Body 파라미터

요청 예시

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "song_ids": "clip_id_1,clip_id_2"
  }'

응답 예시

[
  {
    "song_id": "clip_id_1",
    "song_title": "곡 제목",
    "status": "completed",
    "audio_url": "https://example.com/audio.mp3",
    "video_url": "https://example.com/video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "lyrics": "가사 본문",
    "style_tags": "Mandopop, acoustic",
    "duration": 180.5,
    "model_version": "suno-v6",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

호환성 안내

구버전 문서에서는 song_ids를 배열로 표기할 수 있습니다. 현재는 쉼표로 구분한 문자열을 권장하며, 실제 호출 방식과 일치합니다.

song_ids는 실재하는 곡 ID여야 합니다. pending:으로 시작하는 자리표시자 ID는 최종 song_id가 아니며 이 엔드포인트에 쓸 수 없습니다. 자리표시자 ID만 조회하면 빈 배열 []이 반환될 수 있습니다.

응답의 model, model_version, 플랫폼의 model_name은 과거 값이 남아 있을 수 있습니다. 새 작업에는 suno-v6, suno-v6-wild, suno-v6-mini를 사용하세요. suno-v2부터 suno-v5-5까지는 종료되었고, 기록에 이런 이름이 보인다고 해서 해당 모델을 계속 제출할 수 있는 것은 아닙니다.

생성 작업이 pending, submitted, processing 상태일 때는 audio_url, video_url, cover_url이 비어 있을 수 있으며, 이는 작업이 아직 끝나지 않은 정상 상태입니다. 주소가 비었다는 이유만으로 실패라고 판단하지 말고 status와 함께 판단하고, 상태가 완료된 뒤 다시 조회하세요. 상태가 완료되었는데도 주소가 계속 비어 있을 때만 song_id를 첨부해 기술 지원에 문의하세요.

⚠️ 오디오 주소 유효 기간은 7일입니다. 제때 옮겨 두세요

이 엔드포인트가 반환하는 audio_url, video_url(그리고 WAV 등 다른 미디어 주소)은 플랫폼 오브젝트 스토리지에서 제공되며 기본 7일 후 만료됩니다. 만료되면 파일이 회수되고 기존 주소는 404를 반환합니다.

• 7일 안에 파일을 직접 보관하는 스토리지로 옮기세요. 장기 링크로 취급하지 마세요.
• 주소 만료는 곡을 다시 생성할 필요도 없고 추가 요금도 없습니다. 이 엔드포인트(POST /api/music/query)를 다시 호출하면 해당 곡의 새로운 유효 주소를 받을 수 있습니다.

2. 계정 곡 기록 조회

현재 API Key가 속한 메인 계정이 생성한 곡을 조회합니다. 자체 곡 목록, 선택기, 기록 페이지를 만드는 데 적합합니다.

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

과금: 무료.

Query 파라미터

결과는 created_at과 내부 레코드 ID 내림차순으로 정렬되어 페이지 순서가 안정적으로 유지됩니다.

제출이 타임아웃된 건을 찾는 방법: 생성 계열 엔드포인트는 접수 전에 중간 응답을 주지 않습니다. 제출할 때 클라이언트가 타임아웃되거나 연결이 끊겼다면 그 주문은 이미 접수되어 생성 중일 수 있습니다. 이 엔드포인트를 최신순으로 한 번 확인하세요. 접수된 곡은 정상적으로 목록에 나타납니다. 정말 없는 것을 확인한 뒤 다시 제출해 이중 과금을 피하세요. 자세한 내용은 새 API 개요의 "대기 시간과 타임아웃 설정"을 참고하세요.

요청 예시

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

응답 예시

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "8e31b3c0-example-song-id",
        "title": "밤의 도시",
        "status": "completed",
        "generation_type": "custom_generate",
        "model": "suno-v6",
        "duration": 187.42,
        "audio_url": "https://example.com/audio.mp3",
        "image_url": "https://example.com/cover.jpg",
        "created_at": 1784000000,
        "completed_at": 1784000120
      }
    ]
  }
}

반환 필드

목록 엔드포인트는 프롬프트, 과금 필드, 계정 정보, 원본 응답을 반환하지 않습니다. 프롬프트와 생성 파라미터가 필요하면 곡 상세 엔드포인트를 호출하세요.

3. 생성 파라미터 조회

곡 ID로 그 곡이 생성될 때 플랫폼이 보관한 프롬프트, 스타일, 모델, 소스 곡 등의 파라미터를 조회합니다.

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

과금: 무료.

현재 API Key가 속한 메인 계정의 곡만 조회할 수 있습니다. 다른 사용자나 하위 사이트 계정의 곡은 일괄적으로 "곡을 찾을 수 없음"으로 처리됩니다.

경로 파라미터

요청 예시

curl "https://www.suno-api.io/api/music/songs/8e31b3c0-example-song-id" \
  -H "Authorization: Bearer YOUR_API_KEY"

응답 예시

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "밤의 도시",
    "status": "completed",
    "generation_type": "custom_generate",
    "model": "suno-v6",
    "duration": 187.42,
    "audio_url": "https://example.com/audio.mp3",
    "image_url": "https://example.com/cover.jpg",
    "video_url": "",
    "wav_url": "",
    "created_at": 1784000000,
    "completed_at": 1784000120,
    "client_request_id": "example-request-id",
    "client_request_index": 0,
    "parameters": {
      "prompt": "비 갠 뒤의 도시 거리, 재회에 관한 가사",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "밤의 도시",
      "model": "suno-v6",
      "generation_type": "custom_generate",
      "source_song_id": "",
      "source_audio_url": "",
      "custom_mode": null,
      "instrumental": null,
      "negative_tags": null,
      "vocal_gender": null,
      "lyrics_mode": null,
      "wait_audio": null,
      "style_weight": null,
      "weirdness_constraint": null
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": [
        "suno_tasks"
      ],
      "unavailable_fields": [
        "custom_mode",
        "instrumental",
        "negative_tags",
        "vocal_gender",
        "lyrics_mode",
        "wait_audio",
        "style_weight",
        "weirdness_constraint"
      ]
    }
  }
}

parameters 필드

prompt_view 필드(프롬프트 보기, 2026-09-28 추가)

prompt_view는 "프롬프트 보기" 전용 정규화 구조입니다. 생성 유형별로 데이터를 고정 구역으로 정리하므로 클라이언트가 어떤 필드를 표시할지 스스로 판단할 필요가 없습니다. 순수 추가 필드이며, 기존 필드 (parameters, parameter_retention)의 이름과 의미는 그대로이고, 새 필드를 해석하지 않는 클라이언트는 전혀 영향을 받지 않습니다.

"prompt_view": {
  "type": "custom_generate",
  "type_label": "프로 모드",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "새벽 네 시#701f37", "title_base": "새벽 네 시", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "……", "user_text_kind": "lyrics",
    "user_style": "궈차오 일렉트로닉, 딥 서브 베이스, 레트로 신스",
    "style_tags": "궈차오 일렉트로닉, 딥 서브 베이스, 레트로 신스",
    "style_source": "user", "lyrics": "……",
    "negative_tags": "", "is_instrumental": false
  },
  "extended": {
    "vocal_gender": "m", "style_weight": 0.5, "audio_weight": 0.85,
    "weirdness_constraint": 0.5, "variety": 2, "lyrics_mode": "manual",
    "custom_mode": true
  },
  "reference": { "voice_name": "sv_40_34", "source_song_id": "", "source_title": "" },
  "retention": {
    "recorded_since": "2026-09-28", "missing_reason": "",
    "not_applicable_fields": ["audio_weight"]
  }
}

extended에 나타날 수 있는 필드: vocal_gender, style_weight, audio_weight, weirdness_constraint, variety, lyrics_mode, custom_mode, 그리고 사운드 이펙트 계열의 sound_type / sound_bpm / sound_key / sound_loop. 빈 값은 일괄적으로 반환하지 않습니다.

표시 규칙 세 가지(추측하지 말고 이대로 구현하세요):

1. 스타일 출처를 구분하세요: style_source=suno_derived이면 "스타일(Suno가 설명에서 정리함)"으로 표시하고 "내가 입력한 스타일"로 쓰지 마세요;
2. 내부 프롬프트는 나타나지 않습니다: 음색 커버 계열은 사용자가 입력한 【스타일 요구 사항】/【커버 요구 사항】만 반환하며, 모델에 넣기 위해 조립한 고정 구조는 어떤 필드에도 나타나지 않습니다(기록 데이터도 동일하게 마스킹됨);
3. 보관되지 않은 파라미터를 추측하지 마세요: extended에 없으면 당시 기록되지 않은 것이므로 retention으로 이유를 설명하세요.

파라미터 보관 설명

parameter_retention은 "명시적으로 빈 값을 전달한 경우"와 "역사적으로 그 필드를 저장하지 않은 경우"를 구분하기 위한 것입니다:

• core_parameters_available: 주 곡 작업 기록이 존재하는지. 정상 상세에서는 항상 true;
• extended_parameters_available: 관련 확장 음악 작업 기록을 찾았는지;
• sources: 이번 파라미터가 어느 데이터 테이블에서 왔는지;
• unavailable_fields: 기록 데이터에서 안정적으로 복원할 수 없는 필드. 이 필드들은 parameters 안에서 null을 반환합니다.

일반 기록 곡은 보통 프롬프트, 스타일, 현재 제목, 모델, 생성 유형, 소스 곡을 저장했지만, 모든 고급 파라미터를 따로 저장하지는 않았습니다. 플랫폼은 generation_type으로 빠진 값을 추측하지 않습니다.

일부 확장 음악 작업은 원래 프롬프트, 스타일, 제목, 모델과 함께 custom_mode, negative_tags, vocal_gender, style_weight, weirdness_constraint도 저장했습니다. 확장 레코드가 있어도 instrumental, lyrics_mode, wait_audio는 복원되지 않을 수 있습니다.

곡 제목은 나중에 사용자가 바꿀 수 있습니다. 일반 기록 작업이 원래 제목을 따로 저장하지 않았다면 parameters.title이 현재 제목일 수 있습니다. 확장 작업 기록이 있으면 거기에 저장된 원래 생성 제목을 우선 반환합니다.

존재하지 않거나 권한이 없는 경우

비즈니스 오류는 통일된 응답 봉투를 사용합니다. 곡이 존재하지 않거나 현재 계정에 속하지 않으면 다음을 반환합니다:

{
  "success": false,
  "message": "song not found"
}

이 비즈니스 오류는 현재 HTTP 200으로 반환되므로 결과는 success 필드로 판단하세요. API Key가 없거나, 유효하지 않거나, 만료되었거나, 사용 중지된 경우에는 HTTP 401을 반환합니다.

보안 안내

곡 기록과 상세 엔드포인트는 다음을 반환하지 않습니다:

• API Key, Token ID;
• 쿼터, 과금, 환불 필드;
• 계정 정보와 원본 응답;
• 오브젝트 스토리지 내부 키;
• 관리자 오류와 내부 리소스 오류.