본문으로 건너뛰기

발음 피드백 - 간편 (Pronunciation Feedback Simple)

Theta One 간편 발음 피드백 API는 정답 텍스트만으로 학생의 발음을 평가합니다. 원어민 음성이 필요 없으며, 1회 API 호출로 단어/음소 단위의 발음 분석 결과를 반환합니다.

[학생 음성 + 정답 텍스트] → /pronunciation-simple → 발음 피드백

/pronunciation과의 차이​

항목/pronunciation/pronunciation-simple
API 호출 횟수2회 (/analyze-native + /pronunciation)1회
원어민 음성 필요OX
발음 점수 범위50~700~100
강세/휴지기/속도 피드백점수 + 텍스트null (user_speech_components에 데이터는 포함)
단어/음소/음절 상세전체전체 (동일)
강세/휴지기 데이터는 여전히 제공됩니다

원어민 음성이 없어도 user_speech_components에는 단어/음소의 is_stressed와 휴지기의 is_long 정보가 포함됩니다. 이는 학생 음성 자체에서 측정한 값입니다. 원어민과의 비교 피드백 점수 (강세, 휴지기, 속도)만 null로 반환됩니다.

사전 준비​

API 사용에는 유효한 API 키와 선불 크레딧 또는 후불 결제 계약이 필요합니다. 아직 준비가 되지 않으셨다면 아래 문서들을 참고하여 준비해주시기 바랍니다.

학생 발음 평가 (/pronunciation-simple)​

학생의 음성 파일과 정답 텍스트를 입력하면, 음소/음절 단위의 발음 분석 결과와 발음 점수를 반환합니다.

요청 파라미터​

파라미터타입필수설명
fileFile (WAV)O학생 음성 파일 (.wav 형식)
optionsJSON stringO평가 옵션 (아래 참조)
x-api-key (Header)stringOAPI 키 (sk-theta-로 시작)

options 필드​

필드타입필수설명
gold_textstringO정답 텍스트 (예: "Wow, check out this castle.")
languagestringX피드백 텍스트의 언어 (기본값: "ko"). 지원: ko, en

API 호출​

curl -X 'POST' \
  'https://stt.thetaone-ai.com/pronunciation-simple' \
  -H 'accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@student_audio.wav;type=audio/wav' \
  -F 'options={"gold_text": "Wow, check out this castle.", "language": "ko"}'

응답 예시​

{
  "user_speech_components": [
    {
      "type": "word",
      "word": "Wow",
      "start": 0.45,
      "end": 1.02,
      "score": 72.0,
      "is_correct": true,
      "is_stressed": true,
      "feedback": null,
      "syllables": [
        {
          "syllable": "Wow",
          "grapheme": null,
          "score": 72.0,
          "start": 0.45,
          "end": 1.02
        }
      ],
      "phonemes": [
        {
          "phoneme": "w",
          "user_phoneme": "w",
          "score": 85.0,
          "is_correct": true,
          "is_stressed": true,
          "feedback": null,
          "start": 0.45,
          "end": 0.62
        },
        {
          "phoneme": "aʊ",
          "user_phoneme": "æ",
          "score": 58.0,
          "is_correct": false,
          "is_stressed": false,
          "feedback": "'aʊ' 대신 'æ'로 발음했어요. 입을 크게 벌리고 'ah-oo'로 발음해 보세요.",
          "start": 0.62,
          "end": 1.02
        }
      ]
    },
    {
      "type": "pause",
      "start": 1.02,
      "end": 1.45,
      "is_long": true
    },
    {
      "type": "word",
      "word": "check",
      "start": 1.45,
      "end": 1.88,
      "score": 65.0,
      "is_correct": false,
      "is_stressed": false,
      "feedback": "'check'의 발음이 부정확해요.",
      "syllables": [
        {
          "syllable": "check",
          "grapheme": null,
          "score": 65.0,
          "start": 1.45,
          "end": 1.88
        }
      ],
      "phonemes": [
        {
          "phoneme": "ʧ",
          "user_phoneme": "ʃ",
          "score": 45.0,
          "is_correct": false,
          "is_stressed": false,
          "feedback": "'ch' 대신 'sh'로 발음했어요. 혀끝을 윗잇몸에 대고 떼면서 'ch'로 발음해 보세요.",
          "start": 1.45,
          "end": 1.58
        },
        {
          "phoneme": "ɛ",
          "user_phoneme": "ɛ",
          "score": 98.0,
          "is_correct": true,
          "is_stressed": false,
          "feedback": null,
          "start": 1.58,
          "end": 1.72
        },
        {
          "phoneme": "k",
          "user_phoneme": "k",
          "score": 92.0,
          "is_correct": true,
          "is_stressed": false,
          "feedback": null,
          "start": 1.72,
          "end": 1.88
        }
      ]
    }
  ],
  "feedback": {
    "pronunciation": {
      "score": 78,
      "feedback": "발음이 잘못된 부분이 2개 있어요. 다시 시도해보세요!"
    },
    "stress": null,
    "pause": null,
    "speed": null
  }
}

응답 필드 설명​

user_speech_components​

학생 음성의 분석 결과입니다. 구조는 발음 피드백 API의 응답과 동일합니다. 발음이 부정확한 경우, feedback 필드에 구체적인 교정 피드백이 포함됩니다.

필드 상세는 발음 피드백 API의 응답 필드 설명을 참고하세요.

feedback​

영역점수 범위설명
pronunciation0~100정확하게 발음한 단어의 비율 기반 점수
stressnull원어민 기준 데이터 없이 비교 불가
pausenull원어민 기준 데이터 없이 비교 불가
speednull원어민 기준 데이터 없이 비교 불가

피드백 텍스트는 language 옵션에 따라 해당 언어로 제공됩니다.

워크플로우 예시 (Python)​

import requests
import json

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://stt.thetaone-ai.com"
GOLD_TEXT = "Wow, check out this castle."

headers = {"x-api-key": API_KEY}

# 1회 API 호출 — 원어민 음성 불필요
with open("student_audio.wav", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/pronunciation-simple",
        headers=headers,
        files={"file": ("student_audio.wav", f, "audio/wav")},
        data={
            "options": json.dumps({
                "gold_text": GOLD_TEXT,
                "language": "ko"
            })
        }
    )

result = response.json()
feedback = result["feedback"]

print(f"발음 점수: {feedback['pronunciation']['score']}점")
print(f"→ {feedback['pronunciation']['feedback']}")

# 단어별 상세 확인
for comp in result["user_speech_components"]:
    if comp["type"] == "word":
        status = "O" if comp["is_correct"] else "X"
        print(f"  [{status}] {comp['word']} (점수: {comp['score']})")
        for ph in comp.get("phonemes", []):
            if not ph["is_correct"]:
                print(f"    음소 오류: {ph['phoneme']} → {ph['user_phoneme']} (점수: {ph['score']})")
                if ph.get("feedback"):
                    print(f"      → {ph['feedback']}")

오류 응답​

API 처리에 실패할 경우, HTTP 오류 코드와 함께 오류 메시지를 포함한 json이 반환됩니다.

400 Bad Request​

요청 형식에 문제가 있는 경우입니다. 다음 사항을 확인해주세요.

  • options가 올바른 JSON 문자열인지
  • gold_text가 포함되어 있는지
  • 음성 파일에 모든 단어가 포함되어 있는지 (일부 단어만 발화된 경우 NotAllWordsSpokenError 발생)

401 Unauthorized​

API 인증에 문제가 있는 경우입니다. API 키가 올바르게 입력되었는지, API 키의 상태가 유효한지 확인해주세요.

402 PAYMENT_REQUIRED​

요금 청구 관련 오류입니다. 충전되어 있는 크레딧의 양이 충분한지, 결제 정보가 유효한지 확인해주세요.

429 RATE_LIMIT_EXCEEDED​

할당된 분당 요청 제한(Request Per Minute Limit)을 초과한 요청을 보낼 경우 발생하는 오류입니다. 잠시 후에 다시 시도하거나, RPM 상향 문의를 통해 제한량을 필요에 맞게 상향하여 주시기 바랍니다.

500 INTERNAL_SERVER_ERROR​

Theta One API 서버 측에서 발생하는 오류입니다. 발생할 경우, 에러 로그와 함께 발생 시간, 사용하신 API 키 등을 이메일(support@thetaone.co)으로 남겨주시면 빠르게 해결을 도와드리겠습니다.