Mixanalytic API 문서
https://mixanalytic.com의 공식 API 참조 문서입니다. 이 API로 오디오를 업로드하고, 모듈 선택과 간결한 응답/전체 응답 모드를 지원하는 AI 믹스 분석을 받을 수 있습니다.
기본 URL: https://mixanalytic.com/api
인증
모든 요청에서 X-API-Key 헤더에 API 키를 보내세요.
- 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=30 | AI 분석 사용 통계. |
업로드 요청
POST/api/upload
| 필드 | 유형 | 필수 | 참고 |
|---|---|---|---|
| file | multipart file | 예 | 허용 형식: mp3, wav, flac, m4a, aac, ogg. 최대 95MB. |
| modules | string/list | 아니요 | 생략하면 기본적으로 모든 모듈을 사용합니다. |
| detail_level | string | 아니요 | 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_balance | 7개 대역의 주파수 및 균형 점수. |
| dynamic_range | 다이내믹 레인지, 크레스트 팩터, PLR. |
| stereo_field | 폭/위상/상관관계 지표. |
| clarity | 스펙트럼 선명도 및 윤곽 지표. |
| harmonic_content | 조성과 배음 복잡도. |
| transients | 어택, 트랜지언트 밀도, 저역의 펀치감 데이터. |
| 3d_spatial | 높이/깊이/폭의 일관성. |
| surround_compatibility | 모노 호환성 + 위상 점수. |
| headphone_optimization | 헤드폰 재생 최적화 점수. |
| speaker_optimization | 스피커 재생 최적화 점수. |
| genre | 장르 분류 및 신뢰도. |
| voice | 보컬 존재감 및 음성 특성. |
| instruments | 악기 감지 및 편곡 정보. |
| mood | 에너지/정서가를 포함한 분위기 프로필. |
| keywords | 의미 기반 키워드 및 태그. |
| loudness | LUFS, 트루 피크, 클리핑, 스트리밍 목표를 측정해 왜곡, 코덱 피크, 플랫폼의 예상치 못한 변화 없이 마스터가 충분히 크게 들리게 하세요. |
| noise | 노이즈 플로어, 전원 험, 히스와 아티팩트를 측정해 마스터링에서 소리가 더 크고 밝아져 숨기기 어려워지기 전에 녹음을 정리하세요. |
| format_quality | 손실 인코딩, 스펙트럼 컷오프와 비트 뎁스를 확인해 발매 전에 손상된 MP3, AAC 또는 업스케일된 오디오 소스로 실수로 마스터링하지 않도록 하세요. |
| reference | 레퍼런스 |
| visualizations | 생성된 분석 시각 자료의 URL. |
| ai_insights | LLM이 생성한 요약 및 추천. |
응답 크기 제어
detail_level 사용:
- full(기본값): 전체 페이로드
- summary: 프런트엔드/모바일 클라이언트용 간결한 페이로드
예제
1) 업로드 + 전체 분석
2) 업로드 + 선택한 모듈
3) 업로드 + 선택한 모듈 + 요약 페이로드
4) 테스트 엔드포인트
5) 클라이언트 측 JavaScript
표준 응답 메타데이터
성공한 분석 응답에는 다음이 포함됩니다:
- 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뿐입니다.
| 필드 | 유형 | 필수 | 참고 |
|---|---|---|---|
| file | multipart file | 예 | 허용 형식: mp3, wav, flac, aiff, m4a, aac, ogg. 최대 95MB, 12분. 파일 내용이 확장자와 일치해야 합니다. |
| tone | number | 아니요 | 1 kHz 기준 톤 틸트(dB). 음수는 더 따뜻하게, 양수는 더 밝게. -2부터 2까지, 0.5 단위. 기본값 0. |
| width | number | 아니요 | 120 Hz 이상의 사이드 레벨(dB). 음수는 더 좁게, 양수는 더 넓게. 베이스는 중앙에 유지됩니다. -3부터 2까지, 0.5 단위. 기본값 0. |
| punch | number | 아니요 | 믹스 측정값 대비 글루 컴프레션 배수. 0이면 글루를 끕니다. 0부터 1.5까지, 0.25 단위. 기본값 1. |
| loudness | number | 아니요 | 4개 라우드니스 목표를 함께 움직입니다(LU 단위). 더 키우면 드럼이 뭉개질 경우 마스터는 그 전에 멈추고 변경 사항에 그 내용을 표시합니다. -3부터 1.5까지, 0.5 단위. 기본값 0. |
| mono | string | 아니요 | 120 Hz 이하 베이스를 모노로 만듭니다. auto는 믹스 측정 결과 필요할 때만 적용됩니다. auto, on, off 중 하나. 기본값 auto. |
| deharsh | string | 아니요 | 4–9 kHz가 튀어나오는 순간에만 줄입니다. auto는 믹스 측정 결과 필요할 때만 적용됩니다. auto, on, off 중 하나. 기본값 auto. |
| source | string | 아니요 | 고역 목표를 정합니다. ai는 10 kHz 이상의 에어 대역을 절대 움직이지 않고 고역을 낮게 잡습니다. recorded는 더 밝은 고역을 목표로 합니다. auto는 song_id 리포트의 AI 음악 판정을 사용하거나, 업로드한 파일을 직접 검사합니다. auto, ai, recorded 중 하나. 기본값 auto. |
| style | string | 아니요 | 저역의 무게감과 추천 마스터를 정합니다. auto는 song_id 리포트의 장르를 사용합니다. song_id가 없으면 장르가 적용되지 않습니다. 저역은 중립으로 유지되고 추천은 라우드니스 레인지에 따라 정해지므로, 장르를 고르려면 스타일을 보내세요. auto, pop, rock, hiphop, electronic, rnb, metal, acoustic 중 하나. 기본값 auto. |
| song_id | integer | 아니요 | 분석한 곡의 id입니다. 업로드한 파일을 측정하는 대신 저장된 보고서를 재사용합니다. 같은 믹스를 업로드하세요. |
| Idempotency-Key | header | 아니요 | 1–64자: 영문자, 숫자, _, -. |
범위를 벗어난 숫자는 범위 안으로 제한되고 단위에 맞게 반올림됩니다. 숫자가 아닌 값이나 알 수 없는 선택지를 보내면 400 응답과 invalid_settings 오류가 반환됩니다.
안전하게 재시도하려면 Idempotency-Key 헤더를 보내고, 믹스마다 새 키를 사용하세요. 실행이 아직 남아 있는 동안 계정에서 같은 키를 다시 보내면 다시 청구되거나 다시 시작되지 않으며, 원래 본문에 "replayed": true가 추가된 200 응답을 받습니다. 첫 요청이 아직 시작 중일 때 다시 보내면 429 busy를 받습니다. 503 failed를 받으면 새 키로 다시 시도하세요.
시작 응답
새 실행은 202 응답을 반환합니다:
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": "…"} 형식으로 반환됩니다.
| 상태 | 오류 | 의미 |
|---|---|---|
| 400 | invalid_file | 파일 누락, 지원하지 않는 형식 또는 확장자와 일치하지 않는 내용. |
| 400 | invalid_settings | 설정 값이 숫자가 아니거나 허용된 선택지가 아님. |
| 400 | invalid_idempotency_key | Idempotency-Key 헤더가 영문자, 숫자, _, -로 이루어진 1–64자가 아님. |
| 402 | insufficient_credits | 토큰 부족. 응답 본문에 cost 및 balance가 포함됩니다. |
| 403 | Forbidden | 무료 계정의 키 또는 이 엔드포인트에 필요한 범위가 없는 키. 갱신 결제에 실패한 Supporter는 결제가 완료될 때까지 무료 플랜이 적용되므로, 그동안 마스터링은 마스터링 스튜디오에서만 이용할 수 있습니다. 요금은 청구되지 않습니다. |
| 403 | supporter_only | 마스터링은 당분간 Supporter 계정만 사용할 수 있습니다. 요금은 청구되지 않습니다. |
| 413 | File too large | 파일이 95MB를 넘어 요청이 엔드포인트에 닿기 전에 거부되며, JSON 본문이 없을 수도 있습니다. 한도를 조금만 넘는 파일은 대신 invalid_file를 받습니다. |
| 429 | busy | API 또는 스튜디오에서 이 계정의 실행이 이미 진행 중이거나 시작 중입니다. 응답 본문에 해당 실행의 token가 포함되며, 실행이 시작 중일 때는 null입니다. |
| 429 | Rate Limit Exceeded | 키의 분당, 시간당 또는 일일 한도에 도달함. 어느 한도인지는 메시지에 표시됨. |
| 503 | failed | 실행을 시작할 수 없음. 청구된 토큰이나 횟수는 모두 돌려받습니다. |
마스터링 예제
1) 실행 시작
2) 완료될 때까지 상태 확인
3) 마스터 다운로드
오류 코드
| 상태 | 의미 | 일반적인 원인 |
|---|---|---|
| 400 | 잘못된 요청 | 유효하지 않은 module/detail_level, 파일 필드 누락, 빈 파일. |
| 401 | 인증되지 않음 | API 키가 누락되었거나 유효하지 않거나 만료됨. |
| 403 | 접근 금지 | 계정 등급에서 API 접근을 허용하지 않음. |
| 404 | 찾을 수 없음 | /api/analyze/<file_id> 파일을 더 이상 사용할 수 없음(개인정보 보호를 위한 삭제). |
| 413 | 페이로드가 너무 큼 | 파일이 95MB를 초과함. |
| 429 | 호출 한도 초과 | 분당/시간당/일당 요청이 너무 많음. |
| 500 | 서버 오류 | 분석/런타임 실패. |
프런트엔드 참고 사항
- 웹/모바일 클라이언트에는 detail_level=summary를 권장합니다.
- 지연과 페이로드 크기를 줄이려면 첫 렌더링에 필요한 모듈만 요청하세요.
- 429 및 500는 재시도와 백오프로 처리하세요.
- 유효 기간이 긴 운영 키를 공개 번들에 노출하지 마세요.