API v1

SpeechMap API 문서

SpeechMap의 AI 음성 분석 기능을 외부 서비스에서 활용할 수 있는 REST API입니다. 아동 음성을 업로드하면 5개 언어 발달 지표를 자동으로 분석합니다.

빠른 분석

음성 파일 업로드 후 30초 내 결과 반환

API 키 인증

Bearer 토큰 기반 안전한 인증

5개 지표

유창성, 생산성, 어휘, 구문, 조음

인증

모든 API 요청에는 Authorization 헤더가 필요합니다.

Authorization: Bearer sk_your_api_key_here

API 키는 관리자에게 요청하여 발급받을 수 있습니다.

엔드포인트

POST

/api/v1/analyze

음성 파일을 업로드하여 분석을 시작합니다. 비동기로 처리되며 analysis_id를 반환합니다.

요청 파라미터 (multipart/form-data)

파라미터	타입	필수	설명
audio_file	File	필수	WAV, WebM, M4A 형식의 음성 파일
child_age_months	number	선택	아동 월령 (24-84, 기본값: 48)
child_gender	string	선택	'M' 또는 'F' (기본값: 'M')

응답 (202 Accepted)

{
  "analysis_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "message": "분석이 시작되었습니다.",
  "estimated_time_seconds": 30
}

GET

/api/v1/analysis/{id}

분석 결과를 조회합니다. 분석 완료 후 언어 지표와 음향 분석 결과를 반환합니다.

응답 (200 OK - 분석 완료)

{
  "analysis_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "language_metrics": {
    "overallScore": 78,
    "fluencyScore": 85,
    "productivityScore": 72,
    "lexicalDiversityScore": 68,
    "syntaxComplexityScore": 65,
    "articulationAccuracyScore": 80,
    "rawMetrics": {
      "wpm": 86,
      "wordCount": 43,
      "uniqueWordCount": 28,
      "ttr": 0.65,
      "mluW": 3.58,
      "utteranceCount": 12
    }
  },
  "transcription": "아이가 놀이터에서 놀고 있어요...",
  "acoustic_features": {
    "pitch": { "mean": 280.5, "std": 45.2 },
    "jitter": 0.012,
    "shimmer": 0.035,
    "hnr": 18.5
  },
  "pause_analysis": {
    "pause_count": 8,
    "long_pauses": 2,
    "mean_pause_duration": 0.45
  }
}

3. 임상 리포트 조회

GET

/api/v1/analysis/{id}/report

분석 완료 후 상세 임상 리포트를 조회합니다. 5개 언어지표 점수, 원시 메트릭, 음향 분석, 쉼 분석, 임상 소견이 포함됩니다.

요청 헤더

Authorization: Bearer sk_your_api_key

응답 예시 (completed)

{
  "analysis_id": "abc-123",
  "status": "completed",
  "report": {
    "child_info": { "age_months": 48, "gender": "M" },
    "overall_scores": {
      "total": 72,
      "fluency": 80,
      "productivity": 65,
      "lexical_diversity": 70,
      "syntax_complexity": 60,
      "articulation_accuracy": 75
    },
    "raw_metrics": {
      "words_per_minute": 78,
      "word_count": 45,
      "unique_word_count": 29,
      "type_token_ratio": 0.65,
      "mean_length_utterance": 3.58,
      "utterance_count": 12,
      "duration_seconds": 34.6
    },
    "transcription": "아이가 놀이터에서...",
    "acoustic_features": { "pitch": {...}, "jitter": 0.012 },
    "pause_analysis": { "pause_count": 8, "long_pauses": 2 },
    "clinical_opinion": {
      "diagnosis": "경도 언어발달 지연",
      "strengths": ["어휘 다양성 양호", "발화 의도 명확"],
      "weaknesses": ["구문 복잡성 부족", "쉼 빈도 높음"],
      "recommendations": ["구문 확장 훈련 권장", "유창성 중재 고려"]
    }
  }
}

* clinical_opinion은 Path 4 (Gemini AI) 임상 분석이 완료된 경우에만 포함됩니다.

코드 예시

1. 분석 요청

curl -X POST https://your-domain.com/api/v1/analyze \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "audio_file=@sample.wav" \
  -F "child_age_months=48" \
  -F "child_gender=M"

2. 결과 조회

curl https://your-domain.com/api/v1/analysis/ANALYSIS_ID \
  -H "Authorization: Bearer sk_your_api_key"

3. 임상 리포트 조회

curl https://your-domain.com/api/v1/analysis/ANALYSIS_ID/report \
  -H "Authorization: Bearer sk_your_api_key"

언어 발달 지표

25%

유창성 (Fluency)

쉼 패턴 기반 발화 유창성 평가

20%

생산성 (Productivity)

분당 어절 수(WPM) 기반 발화량 평가

20%

어휘 다양성 (Lexical Diversity)

어휘 유형-빈도 비율(TTR) 기반 평가

20%

구문 복잡성 (Syntax Complexity)

평균 발화 길이(MLU-w) 기반 평가

15%

조음 정확도 (Articulation)

G2P 기반 음소 분석 정확도

종합 점수(overallScore)는 위 5개 지표의 가중 합산으로 산출됩니다 (0-100점).

Rate Limits

플랜	시간당 요청	동시 분석
테스트	100건	5건
기본	500건	10건
엔터프라이즈	커스텀	커스텀

에러 코드

HTTP	코드	설명
401	UNAUTHORIZED	인증 헤더 누락
401	INVALID_API_KEY	유효하지 않은 API 키
400	MISSING_AUDIO	오디오 파일 누락
404	NOT_FOUND	분석 결과 없음
500	INTERNAL_ERROR	서버 내부 오류

API 사용에 대한 문의는 api@speechmap.io로 연락해주세요.