운영 환경

Mixanalytic API 문서

https://mixanalytic.com의 공식 API 참조 문서입니다. 이 API로 오디오를 업로드하고, 모듈 선택과 간결한 응답/전체 응답 모드를 지원하는 AI 믹스 분석을 받을 수 있습니다.

기본 URL: https://mixanalytic.com/api

인증

모든 요청에서 X-API-Key 헤더에 API 키를 보내세요.

curl -X GET "https://mixanalytic.com/api/test-data" \ -H "X-API-Key: YOUR_API_KEY"
  • 401 키 누락/유효하지 않음
  • 403 API 접근 권한이 없는 무료 플랜 키
  • 429 호출 한도 초과

범위: write는 Mixanalytic 업로드/분석용입니다. content는 민감 정보를 가린 콘텐츠 조사 데이터를 읽습니다. content_write는 비공개 콘텐츠 초안을 저장합니다. 콘텐츠 범위는 관리자 전용입니다.

엔드포인트

메서드 경로 용도
GET/api/test-data연결/인증 확인.
POST/api/upload오디오 파일 업로드 + 분석.
GET/api/analyze/<file_id>파일 ID로 재분석(원본 파일이 아직 있는 경우).
POST/api/mastering믹스 업로드 + 마스터링 1회 실행(마스터 4개).
GET/api/mastering/<token>마스터링 실행의 상태와 결과.
GET/api/mastering/<token>/<variant>.wav마스터 1개를 24비트 WAV로 다운로드.
GET/api/content/analysis-feed콘텐츠 에이전트를 위한 관리자 전용 조사 피드로, 민감 정보를 가립니다.
POST/api/content/drafts콘텐츠 에이전트를 위한 관리자 전용 초안 저장/업데이트 엔드포인트.
GET/api/ai-stats?days=30AI 분석 사용 통계.

업로드 요청

POST/api/upload

필드 유형 필수 참고
filemultipart file예허용 형식: mp3, wav, flac, m4a, aac, ogg. 최대 95MB.
modulesstring/list아니요생략하면 기본적으로 모든 모듈을 사용합니다.
detail_levelstring아니요full(기본값) 또는 summary.

유효하지 않은 detail_level는 400를 반환합니다. 크기가 초과된 파일은 413를 반환합니다.

모듈 선택

modules로 반환할 분석 모듈과 계산할 분석 모듈을 지정합니다.

지원 형식:

  • 쉼표로 구분한 문자열: modules=frequency_balance,clarity,mood
  • JSON 배열 문자열: modules=["frequency_balance","clarity","mood"]
  • 반복 키(쿼리/폼): modules=frequency_balance&modules=clarity
  • 모든 모듈: modules=all 또는 modules=*
모듈 설명
frequency_balance7개 대역의 주파수 및 균형 점수.
dynamic_range다이내믹 레인지, 크레스트 팩터, PLR.
stereo_field폭/위상/상관관계 지표.
clarity스펙트럼 선명도 및 윤곽 지표.
harmonic_content조성과 배음 복잡도.
transients어택, 트랜지언트 밀도, 저역의 펀치감 데이터.
3d_spatial높이/깊이/폭의 일관성.
surround_compatibility모노 호환성 + 위상 점수.
headphone_optimization헤드폰 재생 최적화 점수.
speaker_optimization스피커 재생 최적화 점수.
genre장르 분류 및 신뢰도.
voice보컬 존재감 및 음성 특성.
instruments악기 감지 및 편곡 정보.
mood에너지/정서가를 포함한 분위기 프로필.
keywords의미 기반 키워드 및 태그.
loudnessLUFS, 트루 피크, 클리핑, 스트리밍 목표를 측정해 왜곡, 코덱 피크, 플랫폼의 예상치 못한 변화 없이 마스터가 충분히 크게 들리게 하세요.
noise노이즈 플로어, 전원 험, 히스와 아티팩트를 측정해 마스터링에서 소리가 더 크고 밝아져 숨기기 어려워지기 전에 녹음을 정리하세요.
format_quality손실 인코딩, 스펙트럼 컷오프와 비트 뎁스를 확인해 발매 전에 손상된 MP3, AAC 또는 업스케일된 오디오 소스로 실수로 마스터링하지 않도록 하세요.
reference레퍼런스
visualizations생성된 분석 시각 자료의 URL.
ai_insightsLLM이 생성한 요약 및 추천.

응답 크기 제어

detail_level 사용:

  • full(기본값): 전체 페이로드
  • summary: 프런트엔드/모바일 클라이언트용 간결한 페이로드

예제

1) 업로드 + 전체 분석

curl -X POST "https://mixanalytic.com/api/upload" \ -H "X-API-Key: YOUR_API_KEY" \ -F "file=@/path/to/track.mp3"

2) 업로드 + 선택한 모듈

curl -X POST "https://mixanalytic.com/api/upload" \ -H "X-API-Key: YOUR_API_KEY" \ -F "file=@/path/to/track.mp3" \ -F "modules=frequency_balance,dynamic_range,genre,mood,keywords"

3) 업로드 + 선택한 모듈 + 요약 페이로드

curl -X POST "https://mixanalytic.com/api/upload" \ -H "X-API-Key: YOUR_API_KEY" \ -F "file=@/path/to/track.mp3" \ -F "modules=frequency_balance,stereo_field,clarity,ai_insights" \ -F "detail_level=summary"

4) 테스트 엔드포인트

curl -X GET "https://mixanalytic.com/api/test-data" \ -H "X-API-Key: YOUR_API_KEY"

5) 클라이언트 측 JavaScript

const formData = new FormData(); formData.append('file', fileInput.files[0]); formData.append('modules', 'frequency_balance,dynamic_range,mood,ai_insights'); formData.append('detail_level', 'summary'); const res = await fetch('https://mixanalytic.com/api/upload', { method: 'POST', headers: { 'X-API-Key': 'YOUR_API_KEY' }, body: formData }); const data = await res.json(); console.log(data.analysis, data.returned_modules);

표준 응답 메타데이터

성공한 분석 응답에는 다음이 포함됩니다:

  • requested_modules
  • returned_modules
  • detail_level
  • available_modules

마스터링

완성된 믹스를 업로드하면 한 번의 실행으로 24비트 WAV 마스터 4개를 받습니다: dynamic, balanced, loud, chart. API는 마스터링 스튜디오와 같은 엔진, 가격, 월간 한도를 사용합니다.

  • 마스터링은 Supporter 전용입니다. UTC 기준 매월 20회가 포함되며, 이후에는 실행마다 토큰이 사용됩니다.
  • 한 번 실행하면 마스터 4개가 모두 만들어집니다. 포함된 횟수를 다 쓰면 1회에 85 토큰이 사용됩니다. 실행에 실패하면 토큰이나 포함된 횟수를 돌려받습니다.
  • 계정마다 한 번에 하나의 실행만 진행할 수 있으며, 이 제한은 마스터링 스튜디오와 공유됩니다.
  • 마스터는 실행이 끝나고 24시간 후, Supporter 계정에서는 30일 후 삭제됩니다. 단, '내 마스터'에서 보관한 실행은 삭제되지 않습니다. 상태 응답의 expires_at 전에 다운로드하세요.
  • 실행을 시작하려면 write 범위가 필요합니다. 상태 확인과 다운로드에는 read 범위가 필요합니다.

마스터링 요청

POST/api/mastering

믹스를 multipart/form-data 형식으로 보내세요. 필수 항목은 file뿐입니다.

필드 유형 필수 참고
filemultipart file예허용 형식: mp3, wav, flac, aiff, m4a, aac, ogg. 최대 95MB, 12분. 파일 내용이 확장자와 일치해야 합니다.
tonenumber아니요1 kHz 기준 톤 틸트(dB). 음수는 더 따뜻하게, 양수는 더 밝게. -2부터 2까지, 0.5 단위. 기본값 0.
widthnumber아니요120 Hz 이상의 사이드 레벨(dB). 음수는 더 좁게, 양수는 더 넓게. 베이스는 중앙에 유지됩니다. -3부터 2까지, 0.5 단위. 기본값 0.
punchnumber아니요믹스 측정값 대비 글루 컴프레션 배수. 0이면 글루를 끕니다. 0부터 1.5까지, 0.25 단위. 기본값 1.
loudnessnumber아니요4개 라우드니스 목표를 함께 움직입니다(LU 단위). 더 키우면 드럼이 뭉개질 경우 마스터는 그 전에 멈추고 변경 사항에 그 내용을 표시합니다. -3부터 1.5까지, 0.5 단위. 기본값 0.
monostring아니요120 Hz 이하 베이스를 모노로 만듭니다. auto는 믹스 측정 결과 필요할 때만 적용됩니다. auto, on, off 중 하나. 기본값 auto.
deharshstring아니요4–9 kHz가 튀어나오는 순간에만 줄입니다. auto는 믹스 측정 결과 필요할 때만 적용됩니다. auto, on, off 중 하나. 기본값 auto.
sourcestring아니요고역 목표를 정합니다. ai는 10 kHz 이상의 에어 대역을 절대 움직이지 않고 고역을 낮게 잡습니다. recorded는 더 밝은 고역을 목표로 합니다. auto는 song_id 리포트의 AI 음악 판정을 사용하거나, 업로드한 파일을 직접 검사합니다. auto, ai, recorded 중 하나. 기본값 auto.
stylestring아니요저역의 무게감과 추천 마스터를 정합니다. auto는 song_id 리포트의 장르를 사용합니다. song_id가 없으면 장르가 적용되지 않습니다. 저역은 중립으로 유지되고 추천은 라우드니스 레인지에 따라 정해지므로, 장르를 고르려면 스타일을 보내세요. auto, pop, rock, hiphop, electronic, rnb, metal, acoustic 중 하나. 기본값 auto.
song_idinteger아니요분석한 곡의 id입니다. 업로드한 파일을 측정하는 대신 저장된 보고서를 재사용합니다. 같은 믹스를 업로드하세요.
Idempotency-Keyheader아니요1–64자: 영문자, 숫자, _, -.

범위를 벗어난 숫자는 범위 안으로 제한되고 단위에 맞게 반올림됩니다. 숫자가 아닌 값이나 알 수 없는 선택지를 보내면 400 응답과 invalid_settings 오류가 반환됩니다.

안전하게 재시도하려면 Idempotency-Key 헤더를 보내고, 믹스마다 새 키를 사용하세요. 실행이 아직 남아 있는 동안 계정에서 같은 키를 다시 보내면 다시 청구되거나 다시 시작되지 않으며, 원래 본문에 "replayed": true가 추가된 200 응답을 받습니다. 첫 요청이 아직 시작 중일 때 다시 보내면 429 busy를 받습니다. 503 failed를 받으면 새 키로 다시 시도하세요.

시작 응답

새 실행은 202 응답을 반환합니다:

{ "token": "3b9f0c2e7d4a41f6a8e5c1b2d3f4a5b6", "status": "pending", "status_url": "/api/mastering/3b9f0c2e7d4a41f6a8e5c1b2d3f4a5b6", "billed": "tokens", "charged": 85, "balance": 415, "expires_in_hours": 720 }

Supporter 포함 횟수로 실행하면 "billed": "included" 및 "charged": 0가 포함됩니다. Supporter에게는 used, cap, reset_date가 담긴 included 객체도 함께 반환됩니다.

마스터링 상태 및 다운로드

GET/api/mastering/<token>

상태가 done 또는 error 중 하나가 될 때까지 키의 호출 한도 내에서 3–5초마다 확인하세요.

  • pending: 마스터를 만드는 중입니다.
  • settling: 실행에 실패하여 토큰이나 포함된 횟수를 돌려주는 중입니다. 계속 확인하세요.
  • done: 마스터 4개가 준비되었습니다.
  • error: 실행에 실패했으며 청구된 토큰이나 포함된 횟수는 돌려받았습니다. error 필드에 원인이 표시됩니다: too_long, too_short, too_quiet, failed.

완료 응답에 포함되는 필드: recommended, recommended_reason, warnings, source, settings, masters, expires_at, filename. masters의 각 항목에 포함되는 필드: key, url, target_lufs, ceiling, metrics, changes, peaks.

완료 및 오류 응답에는 실행 후의 잔액과 포함된 횟수를 담은 access도 포함됩니다.

알 수 없거나 만료된 실행 토큰과 다른 계정의 실행 토큰에는 404 응답과 {"status": "expired"}가 반환됩니다.

다운로드

GET/api/mastering/<token>/<variant>.wav

업로드한 파일 이름을 딴 24비트 WAV 첨부 파일로 마스터를 반환합니다(예: My Mix - balanced.wav). variant는 dynamic, balanced, loud, chart 중 하나입니다.

알 수 없는 버전, 다른 계정의 실행 토큰, 만료되었거나 아직 완료되지 않은 실행에는 404가 반환됩니다.

모든 마스터링 응답에는 Cache-Control: private, no-store가 포함됩니다.

마스터링 오류

오류는 {"error": "invalid_file", "message": "…"} 형식으로 반환됩니다.

상태 오류 의미
400invalid_file파일 누락, 지원하지 않는 형식 또는 확장자와 일치하지 않는 내용.
400invalid_settings설정 값이 숫자가 아니거나 허용된 선택지가 아님.
400invalid_idempotency_keyIdempotency-Key 헤더가 영문자, 숫자, _, -로 이루어진 1–64자가 아님.
402insufficient_credits토큰 부족. 응답 본문에 cost 및 balance가 포함됩니다.
403Forbidden무료 계정의 키 또는 이 엔드포인트에 필요한 범위가 없는 키. 갱신 결제에 실패한 Supporter는 결제가 완료될 때까지 무료 플랜이 적용되므로, 그동안 마스터링은 마스터링 스튜디오에서만 이용할 수 있습니다. 요금은 청구되지 않습니다.
403supporter_only마스터링은 당분간 Supporter 계정만 사용할 수 있습니다. 요금은 청구되지 않습니다.
413File too large파일이 95MB를 넘어 요청이 엔드포인트에 닿기 전에 거부되며, JSON 본문이 없을 수도 있습니다. 한도를 조금만 넘는 파일은 대신 invalid_file를 받습니다.
429busyAPI 또는 스튜디오에서 이 계정의 실행이 이미 진행 중이거나 시작 중입니다. 응답 본문에 해당 실행의 token가 포함되며, 실행이 시작 중일 때는 null입니다.
429Rate Limit Exceeded키의 분당, 시간당 또는 일일 한도에 도달함. 어느 한도인지는 메시지에 표시됨.
503failed실행을 시작할 수 없음. 청구된 토큰이나 횟수는 모두 돌려받습니다.

마스터링 예제

1) 실행 시작

curl -X POST "https://mixanalytic.com/api/mastering" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_MIX" \ -F "file=@/path/to/mix.wav" \ -F "style=electronic" \ -F "loudness=0.5"

2) 완료될 때까지 상태 확인

curl "https://mixanalytic.com/api/mastering/TOKEN" \ -H "X-API-Key: YOUR_API_KEY"

3) 마스터 다운로드

curl -o "mix - balanced.wav" "https://mixanalytic.com/api/mastering/TOKEN/balanced.wav" \ -H "X-API-Key: YOUR_API_KEY"

오류 코드

상태 의미 일반적인 원인
400잘못된 요청유효하지 않은 module/detail_level, 파일 필드 누락, 빈 파일.
401인증되지 않음API 키가 누락되었거나 유효하지 않거나 만료됨.
403접근 금지계정 등급에서 API 접근을 허용하지 않음.
404찾을 수 없음/api/analyze/<file_id> 파일을 더 이상 사용할 수 없음(개인정보 보호를 위한 삭제).
413페이로드가 너무 큼파일이 95MB를 초과함.
429호출 한도 초과분당/시간당/일당 요청이 너무 많음.
500서버 오류분석/런타임 실패.

프런트엔드 참고 사항

  • 웹/모바일 클라이언트에는 detail_level=summary를 권장합니다.
  • 지연과 페이로드 크기를 줄이려면 첫 렌더링에 필요한 모듈만 요청하세요.
  • 429 및 500는 재시도와 백오프로 처리하세요.
  • 유효 기간이 긴 운영 키를 공개 번들에 노출하지 마세요.