폐음 진단 API

개요

소아 폐음 진단 API는 사용자가 업로드한 폐음(호흡음) 오디오 파일을 분석하여 정상 폐음(Normal), 수포음(Crackles), 천명음(Wheezes), 혼합음(Both) 중 하나로 분류합니다. 본 문서는 카카오 개발자 문서 스타일을 참고하여 엔드포인트, 요청, 응답, 샘플 코드, 데모를 포함합니다.

---

폐음 예시 및 다운로드

정상 폐음 (Normal)

설명: 정상적인 폐 소리는 부드럽고 깨끗하며 잡음이 없습니다.

normal.wav 다운로드

수포음 (Crackles)

설명: 머리카락 비비는 듯한 타닥거리는 소리가 특징입니다. 주로 흡기 시 들립니다.

crackle.wav 다운로드

천명음 (Wheezes)

설명: 휘파람처럼 쌕쌕거리는 소리입니다. 주로 호기 시 들립니다.

wheeze.wav 다운로드

혼합음 (Both)

설명: 수포음과 천명음이 동시에 들립니다. (샘플 없음)

---

API 엔드포인트

POST https://medisensing.kr/api/respcls/predict

인증 방식은 마이페이지에서 발급된 토큰을 사용합니다.

---

요청 (Request)

요청 헤더

Content-Type: multipart/form-data
X-API-Key: <api_key>

요청 파라미터

이름	타입	필수	설명
file	file	O	오디오 파일 (WAV 권장, 최대 10MB, 10초 이내 권장)

제약 및 권장

• 지원 형식: WAV
• 권장 길이: 10초 이내
• 권장 크기: 10MB 이하
• CORS: Access-Control-Allow-Origin: *

---

응답 (Response)

성공 응답 (200 OK)

{
  "predicted_label": "Crackles",
  "confidence": 0.92,
  "probabilities": {
    "Normal": 0.01,
    "Crackles": 0.92,
    "Wheezes": 0.05,
    "Both": 0.02
  },
  "metadata": {
    "duration": 8.3,
    "sample_rate": 44100
  }
}

오류 응답 예시

{
  "detail": "Invalid API key"
}

가능한 오류 코드 - 400 Bad Request: 파일 누락 또는 형식 오류 - 401 Unauthorized: 잘못된 API 키 - 413 Payload Too Large: 파일 크기 초과 - 500 Internal Server Error: 서버 내부 오류

---

샘플 요청

cURL

curl -X POST "https://medisensing.kr/api/respcls/predict"   -H "X-API-Key: YOUR_API_KEY"   -F "file=@normal.wav"

JavaScript (fetch)

const formData = new FormData();
formData.append("file", fileInput.files[0]);

fetch("https://medisensing.kr/api/respcls/predict", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY"
  },
  body: formData
})
  .then(res => res.json())
  .then(console.log)
  .catch(console.error);

---

직접 테스트 (Demo)

오디오 파일 선택

API Key

예측 요청

응답 미리보기

---

성능 및 지표

• 정확도(내부): 약 91–93%
• 추론 지연: GPU 환경 기준 평균 100–200ms, 파일 업로드/네트워크 포함 평균 1–3초

변경 이력

• 2025-09-23: 초기 API 문서 공개