nullab MUSIC

API 사용법

모든 요청은 X-API-Key 헤더로 인증합니다. 응답은 항상 { "success", "data", "message" } 형식의 JSON입니다.

API 키는 회원가입 시 자동 발급됩니다.

회원가입하고 API 키 받기 →

기본 정보

Base URLhttps://a.nullab.kr
인증 헤더X-API-Key: <발급받은 키>
지원 포맷mp3, wav, flac, m4a
최대 파일 크기100MB

1. 곡 업로드

POST/api/music/upload

multipart/form-data — genre, file

curl -X POST https://a.nullab.kr/api/music/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "genre=drive_edm" \
  -F "file=@song.wav"
{"success":true,"data":{"id":"a1b2...","genre":"drive_edm","status":"pending"},"message":"uploaded"}

2. 분석 실행

POST/api/music/analyze

id — 업로드 응답의 job id

curl -X POST https://a.nullab.kr/api/music/analyze \
  -H "X-API-Key: YOUR_API_KEY" \
  -d "id=a1b2..."
{"success":true,"data":{"id":"a1b2...","status":"analyzed","analysis":{"lufs":-16.2,"true_peak_db":-3.1,"dynamic_range_db":9.4,"spectral_balance":{"low":0.31,"mid":0.44,"high":0.25},"clipping_detected":false}},"message":"analyzed"}

3. 마스터링 실행

POST/api/music/master

id 외에 아래 파라미터를 선택적으로 보내면 자동계산값 대신 직접 지정한 값으로 마스터링합니다 (범위를 벗어나면 서버에서 자동으로 클램프됩니다).

파라미터범위의미
lufs-20 ~ -5목표 라우드니스
true_peak-3 ~ 0트루피크 한계(dB)
lra3 ~ 15러프니스 레인지
eq_low-6 ~ 6저음(100Hz) EQ(dB)
eq_mid-6 ~ 6중음(1kHz) EQ(dB)
eq_high-6 ~ 6고음(8kHz) EQ(dB)
compressor_enabled0 / 1컴프레서 사용 여부
compressor_ratio1 ~ 10컴프레서 비율
curl -X POST https://a.nullab.kr/api/music/master \
  -H "X-API-Key: YOUR_API_KEY" \
  -d "id=a1b2..." \
  -d "lufs=-9" -d "eq_low=2"
{"success":true,"data":{"id":"a1b2...","status":"completed","download_url":"/song/mastered/a1b2....wav","expires_at":"2026-07-14T02:00:00Z","params_used":{...},"before":{...},"after":{...}},"message":"mastered"}

완료된 job에 다시 호출하면 같은 곡을 다른 파라미터로 재마스터링합니다 (월간 무료 쿼터를 다시 차감하지 않습니다).

4. 상태 조회

GET/api/music/status/{id}
curl -H "X-API-Key: YOUR_API_KEY" \
  https://a.nullab.kr/api/music/status/a1b2...

장르 코드

drive_edmDrive / EDM
love_edmLove / EDM
korean_soul_ballad한국 소울 발라드
hiphop_rnb힙합 / R&B
lofi로파이
acoustic어쿠스틱
rock_band록 / 밴드
trot_trance트로트 / 트랜스
pop팝

쿼터 & Rate Limit

FreePro
월 성공 마스터링10곡 (매월 1일 리셋)무제한
시간당 호출30회120회
일일 호출100회1000회

모든 응답에 X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset 헤더가 포함됩니다. 실패한 업로드(잘못된 장르/파일 등)는 월간 쿼터에서 차감되지 않고, 마스터링에 성공한 곡만 차감됩니다.

에러 응답

{"success":false,"data":null,"message":"invalid API key"}
HTTP의미
401API 키 누락/오류
403월간 쿼터 초과
404job 없음 (본인 소유가 아닌 job 포함)
409분석 전에 마스터링 시도
410만료된 job (12시간 경과)
413파일 크기 초과
429rate limit 초과
a.nullab.kr Music Mastering · 문의: taekyung.insight@gmail.com
업로드 중...