운영 환경
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는 Mix Analyzer 업로드/분석용입니다. content는 민감 정보를 가린 콘텐츠 조사 데이터를 읽습니다. content_write는 비공개 콘텐츠 초안을 저장합니다. 콘텐츠 범위는 관리자 전용입니다.
엔드포인트
| 메서드 | 경로 | 용도 |
|---|---|---|
| GET | /api/test-data | 연결/인증 확인. |
| POST | /api/upload | 오디오 파일 업로드 + 분석. |
| GET | /api/analyze/<file_id> | 파일 ID로 재분석(원본 파일이 아직 있는 경우). |
| 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. 최대 100MB. |
| 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) 업로드 + 전체 분석
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
오류 코드
| 상태 | 의미 | 일반적인 원인 |
|---|---|---|
| 400 | 잘못된 요청 | 유효하지 않은 module/detail_level, 파일 필드 누락, 빈 파일. |
| 401 | 인증되지 않음 | API 키가 누락되었거나 유효하지 않거나 만료됨. |
| 403 | 접근 금지 | 계정 등급에서 API 접근을 허용하지 않음. |
| 404 | 찾을 수 없음 | /api/analyze/<file_id> 파일을 더 이상 사용할 수 없음(개인정보 보호를 위한 삭제). |
| 413 | 페이로드가 너무 큼 | 파일이 100MB를 초과함. |
| 429 | 호출 한도 초과 | 분당/시간당/일당 요청이 너무 많음. |
| 500 | 서버 오류 | 분석/런타임 실패. |
프런트엔드 참고 사항
- 웹/모바일 클라이언트에는 detail_level=summary를 권장합니다.
- 지연과 페이로드 크기를 줄이려면 첫 렌더링에 필요한 모듈만 요청하세요.
- 429 및 500는 재시도와 백오프로 처리하세요.
- 유효 기간이 긴 운영 키를 공개 번들에 노출하지 마세요.