API Documentation

가정 내 소리 감지 API(테스트용)

개요

가정 내 소리 감지 API는 사용자가 업로드한 오디오 파일에서 가정 내에서 발생하는 다양한 소리를 감지하고 분류하는 딥러닝 기반 서비스입니다.
고성능 CNN 모델을 사용하여 개 짖는 소리, 아기 울음소리, 코골이 소리를 정확하게 감지하고 시간대별로 분석합니다.

소리 감지 예시

API 엔드포인트

POST https://medisensing.kr/api/homesound/detect
GET  https://medisensing.kr/api/homesound/results/{job_id}

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

요청 (Request)

요청 헤더

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

요청 파라미터

이름	타입	필수	설명
file	file	O	오디오 파일 (WAV, FLAC, MP3 지원, 최대 500MB)

응답 (Response)

1단계: 소리 감지 요청 (202 Accepted)

{
  "job_id": "xyz123abc"
}

2단계: 결과 조회 (200 OK)

{
  "status": "completed",
  "result": {
    "file": "test_sample_0000.mp3",
    "total_duration": 35.4,
    "summary": {
      "dominant_class": "dog",
      "total_segments": 35,
      "sound_segments": 12,
      "silence_time": 10.5
    },
    "class_statistics": {
      "dog": {
        "total_time": 8.2,
        "percentage": 23.1,
        "avg_confidence": 0.92,
        "segment_count": 5
      },
      "crying": {
        "total_time": 6.5,
        "percentage": 18.3,
        "avg_confidence": 0.88,
        "segment_count": 4
      },
      "snoring": {
        "total_time": 10.2,
        "percentage": 28.8,
        "avg_confidence": 0.90,
        "segment_count": 3
      }
    },
    "segments": [
      {
        "timestamp": "00:00-00:10",
        "label": "Dog",
        "confidence": 0.95
      },
      {
        "timestamp": "00:10-00:20",
        "label": "Crying",
        "confidence": 0.91
      }
    ]
  }
}

오류 응답 예시

{
  "detail": "Invalid API key"
}

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

샘플 요청

1단계: 소리 감지 요청 (파일 업로드)

curl -X POST "https://medisensing.kr/api/homesound/detect" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@barking.wav"

응답 예시

{
  "job_id": "xyz123abc"
}

2단계: 결과 조회 (job_id 사용)

curl -X GET "https://medisensing.kr/api/homesound/results/xyz123abc" \
  -H "X-API-Key: YOUR_API_KEY"

응답 예시

{
  "status": "completed",
  "result": {
    "file": "barking.wav",
    "summary": {
      "dominant_class": "dog",
      "total_segments": 10,
      "sound_segments": 6,
      "silence_time": 2.1
    }
  }
}

JavaScript (fetch) 예시

// 1단계: 소리 감지 요청
const formData = new FormData();
formData.append("file", fileInput.files[0]);

const res = await fetch("https://medisensing.kr/api/homesound/detect", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
  body: formData
});
const { job_id } = await res.json();

// 2단계: 결과 조회
const resultRes = await fetch(`https://medisensing.kr/api/homesound/results/${job_id}`, {
  method: "GET",
  headers: { "X-API-Key": "YOUR_API_KEY" }
});
const resultJson = await resultRes.json();
console.log(resultJson);

소리 감지 결과 해석

지원 소리 클래스

Dog: 개 짖는 소리 (강아지 짖음, 개 울음 등)
Crying: 아기 울음소리 (신생아 울음, 아기 보채는 소리 등)
Snoring: 코골이 소리 (수면 중 코골이, 잠꼬대 등)
Silence: 조용한 구간 (소음 없음, 배경 소음만 존재)

신뢰도 점수

90% 이상: 매우 높은 신뢰도
80-90%: 높은 신뢰도
70-80%: 중간 신뢰도
70% 미만: 낮은 신뢰도 (추가 검증 권장)

세그먼트 분석

10초 윈도우: 오디오를 10초 단위로 분석
1초 스텝: 1초마다 새로운 분석 수행
시간대별 라벨링: 각 구간별로 감지된 소리 분류
통계 정보: 각 소리별 총 시간, 비율, 평균 신뢰도 제공

모델 정보

모델: CNN 기반 소리 분류 모델
입력: 16kHz 샘플링, 10초 윈도우
출력: 3개 소리 클래스 + 침묵 구간

참고

지원 형식: WAV, FLAC, MP3
권장 크기: 최대 500MB
오디오 길이: 제한 없음 (긴 파일은 세그먼트 단위로 처리)
처리 시간: 10초 오디오당 약 0.1초
정확도: 평균 85% 이상
주요 활용: 스마트 홈, 육아 모니터링, 수면 분석