Skip to main content

🗣️ pronunciation.apis.how

pronunciation.apis.how 는 multi-saas-kit 에서 제공하는 발음 평가 + 세션 종합 평가 managed 예시 도메인 입니다.

이 서비스는 "한 번의 발화 평가"와 "여러 발화가 누적된 세션 종합 리포트"를 하나의 도메인에서 Layer 2 / Layer 3 두 가지 수준으로 제공합니다.

핵심 구조​

Browser / App / Server
        │
        │ Pronunciation API Token
        ▼
pronunciation.apis.how
        │
        ├─ token introspection   ← apis.how
        ├─ Layer 2  (발화 1개씩)
        │    /v1/assess/script
        │    /v1/assess/unscripted
        │    /v1/assess/stream (WebSocket)
        │
        └─ Layer 3  (세션 전체 종합)
             /v1/assessment/session/report
                    │
                    └─ utterance 결과 배열 → 집계 + LLM 내러티브

외부 사용자는 Pronunciation API Token 으로 pronunciation.apis.how 를 호출하고, 내부 pronunciation-service 는 Azure Speech / SpeechAce / LiteLLM 을 대리 호출합니다.

Layer 2 — 단일 발화 평가​

MethodPath설명
POST/v1/assess/scriptreference text + audio → 발음 점수 + 한국어 피드백
POST/v1/assess/unscriptedtopic prompt + audio → STT + LLM Grammar/Vocab/Content 분석
GET (WS)/v1/assess/streamscripted/unscripted 실시간 스트리밍 평가

응답의 공통 필드: scores.{overall, accuracy, fluency, completeness, prosody}, word_scores[], recognized_text, reference_text, 선택적으로 summary (deterministic Tier 1) / feedback (LLM Tier 2).

프리셋 4종 (utterance-level): gentle_coach, strict_teacher, exam_evaluator, unscripted_analyst.

Layer 3 — 세션 종합 평가 (v0.15.0+)​

MethodPath설명
POST/v1/assessment/session/reportutterance 결과 배열을 집계하여 세션 종합 리포트 반환

특징​

  • Stateless — 서버에 세션 데이터 저장 없음. 클라이언트가 Layer 2 결과를 배열로 전달.
  • Deterministic 항상 — 평균/최소/최대/표준편차/반복 약점 단어·음소/모드별 분포 집계는 LLM 없이 항상 반환.
  • LLM 선택 — feedback_options.enabled=true 일 때만 LLM 호출, 실패해도 200 OK + narrative=null (Graceful degradation).
  • 프리셋 3종 (session-level):
    • session_general — 범용 종합 (SUMMARY / STRENGTHS / IMPROVEMENTS / PRIORITIES)
    • session_exam_band — IELTS/TOEFL 밴드 추정 (BAND + 3 섹션)
    • session_tutor_report — 학원/튜터 리포트 (학부모 친화 톤)

요청 예시​

curl -X POST https://pronunciation.apis.how/v1/assessment/session/report \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_20260424_001",
    "learner_context": {"native_language": "ko-KR", "goal": "IELTS 7.0"},
    "utterances": [
      {"turn": 1, "mode": "scripted", "scores": {"overall": 85, "accuracy": 88}},
      {"turn": 2, "mode": "unscripted", "topic_prompt": "Describe your hometown", "scores": {"overall": 78}}
    ],
    "rubric": "session_exam_band",
    "feedback_options": {"enabled": true, "language": "ko-KR", "style": "detailed"}
  }'

응답에는 aggregated_scores, weak_patterns, per_mode, (선택) narrative 필드가 포함됩니다.

어떤 토큰을 써야 하나​

  • 외부 호출자
    • Pronunciation API Token (apis.how 에서 발급)
  • 내부 서비스
    • OPENAI_API_KEY / LITELLM_API_KEY — pronunciation-service 가 LLM 피드백 호출 시 사용
    • AZURE_SPEECH_KEY — Azure Pronunciation Assessment 호출

필요한 abilities​

토큰 생성 시 다음 중 필요한 것만 선택합니다.

Ability필요 엔드포인트
pronunciation:assess:script/v1/assess/script, /v1/assess/stream?mode=scripted
pronunciation:assess:free/v1/assess/unscripted, /v1/assess/stream?mode=unscripted
pronunciation:stream/v1/assess/stream (WebSocket)
pronunciation:premiumSpeechAce premium 프로필 (Phase D10)
pronunciation:*와일드카드 — 모든 pronunciation 액션
assessment:session:report/v1/assessment/session/report (Layer 3, v0.15.0+)
assessment:*와일드카드 — 모든 assessment 액션

Platform > Pronunciation API > API Tokens 에서 토큰 편집 시 체크박스로 선택.

Settings 페이지​

Platform > Pronunciation API > Settings 에서 다음을 관리합니다.

  • Global System Prompt (Layer 1 / 전역) — 모든 LLM 피드백 프리셋에 공통 주입되는 플랫폼 전역 프롬프트. 비워두면 skip.
  • Feedback Config 오버라이드 — 기본 preset/style/language, brand_voice, model_override (Layer 2, 테넌트 수준).
  • LLM 모델 기본값 — 실시간 대화/피드백에 사용할 기본 모델.

변경 사항은 introspection 캐시 TTL (기본 60초) 이후 반영됩니다.

Design 페이지​

Platform > Pronunciation API > Design 에서 엔드포인트 / 프로필 / 프리셋 / abilities / integration 모드 일람을 확인할 수 있습니다.

API Test 페이지​

Platform > Pronunciation API > API Test 는 운영자가 샘플 오디오로 엔드포인트 동작을 검증하는 내부 페이지입니다.

Usage 페이지​

운영자는 다음 메뉴에서 호출량/비용을 확인합니다.

  • Pronunciation API > Usage Dashboard
  • API Management > Usage Dashboard

Layer 3 엔드포인트 호출(/v1/assessment/session/report) 도 기존 usage tracker 에 자동으로 기록됩니다.

Managed vs Self-Hosted​

Managed Mode​

  • pronunciation.apis.how

Self-Hosted Mode​

  • pronunciation.${ROOT_DOMAIN}

도메인은 달라질 수 있지만, access key 정책과 프리셋/ability 구성은 동일하게 유지합니다.

서비스 내부 문서 (운영자/개발자용)​

함께 보면 좋은 문서​