WAV 생성/조회 API

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

인터페이스 설명

WAV 인터페이스는 기존 곡의 무손실 WAV 오디오 주소를 생성하거나 조회하는 데 사용합니다.

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

과금: 무료. 이 엔드포인트는 기존 곡의 WAV 주소를 생성·조회하는 데 쓰이며 크레딧을 차감하지 않습니다.

대기 시간과 타임아웃(중요): 이 엔드포인트는 동기 방식이며, 응답이 돌아온 시점에야 주문이 접수됩니다. 실측 기준 대부분의 요청은 1~3초에 반환되고, 약 10%는 30초를 넘기며, 최장 약 230초가 걸립니다. 클라이언트 타임아웃을 300초 이상으로 설정하세요. 응답이 없다고 해서 생성되지 않은 것이 아니며, 타임아웃 직후 재시도하지 마세요. 연결이 끊겼다면 잠시 후 GET /api/music/songs로 확인할 수 있습니다. 자세한 내용은 새 API 개요의 "대기 시간과 타임아웃 설정"을 참고하세요.

요청 파라미터

Headers

바디 파라미터

maxAttempts와 intervalSeconds는 모두 JSON 숫자이며, intervalSeconds의 단위는 초이지 밀리초가 아닙니다. 보통은 기본값 그대로 두면 됩니다. 이 값들은 이 엔드포인트가 내부에서 WAV 준비 완료를 기다리는 횟수와 간격만 제어하며, 곡 생성 작업 자체의 상태를 바꾸지 않습니다.

요청 예시

curl -X POST https://www.suno-api.io/api/music/wav \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "audioId": "clip_id",
    "maxAttempts": 24,
    "intervalSeconds": 5
  }'

응답 결과

{
  "code": 200,
  "message": "success",
  "data": {
    "audioId": "clip_id",
    "status": "complete",
    "wavUrl": "https://media.code-go.com/assets/example.wav"
  }
}

주의 사항

WAV 생성과 조회는 서버가 곡 레코드를 기준으로 사용 가능한 리소스를 자동으로 선택하므로, 고객이 계정 정보를 제공할 필요가 없습니다.

일반 곡과 분리 트랙은 동일한 통제된 미디어 전달 경로를 사용합니다. WAV는 먼저 CN2가 내려받아 디스크에 저장하고, 성공 응답의 data.wavUrl은 통제된 CDN 주소만 반환하며 Suno나 S3의 임시 원본 주소는 반환하지 않습니다.

ready 상태의 WAV 자산이 이미 있으면 그대로 재사용하고 Suno에 다시 요청하거나 파일을 다시 옮기지 않습니다. 아직 준비되지 않은 WAV는 /api/music/query를 통해 Suno/S3 주소로 노출되지 않으며, 이 엔드포인트나 통합 다운로드 엔드포인트를 호출한 뒤에만 필요할 때 준비됩니다.

⚠️ WAV 주소 유효 기간은 7일입니다. 기한 내에 옮겨 저장하세요. 반환되는 data.wavUrl은 플랫폼 객체 스토리지가 제공하며 기본 7일 후 만료됩니다(파일이 회수되고 이전 주소는 404를 반환합니다). 유효 기간 안에 자체 저장소로 WAV를 옮겨 저장하세요. 만료 후에는 이 엔드포인트를 다시 호출하면 새로운 유효 주소를 받을 수 있습니다.

곡 리소스를 일시적으로 사용할 수 없으면 인터페이스는 409를 반환합니다. 잠시 후 다시 시도하세요. 서버는 불안정한 임시 주소를 반환하지 않습니다.