자주 묻는 질문

API 사용법 및 엔드포인트 세부 정보는 어디에서 찾을 수 있나요?

자세한 정보는 저희 문서의 API 엔드포인트 섹션을 참조하시기 바랍니다.

어떤 네트워크 설정 및 인증서가 필요한가요?

인증 방식은 token-based입니다. 호스트명 및 API 사용 방법에 관한 모든 세부 정보는 저희 문서에서 확인하실 수 있습니다.

예시:

curl -X POST 'https://api.elsanow.io/api/v1/score_audio_plus' \
     -H 'Content-Type: multipart/form-data' \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer <TOKEN>' \
     -F 'api_plan="premium"' \
     -F 'return_json="true"' \
     -F 'audio_file=@"/path/to/file"'

추가 예시는 문서의 API 섹션에서 확인하실 수 있습니다.

API 키 또는 토큰을 어떻게 발급받고 사용하나요?

API token은 NDA 서명 완료 후 저희가 발급해 드립니다. 서명이 완료되면 알려 주시면 토큰을 제공해 드리겠습니다. 사용 방법은 문서에 안내되어 있습니다.

API 요청 및 응답의 구조와 제한 사항은 무엇인가요?

parameters 및 limitations를 포함한 상세한 요청 및 응답 구조는 API 문서에서 확인하실 수 있습니다.

샌드박스를 이용할 수 있나요? 테스트 계정이 필요한가요?

현재 staging 환경은 제공하고 있지 않습니다.

모니터링 및 디버깅을 위한 대시보드나 로그가 있나요?

요청 및 활동 현황을 파악할 수 있도록 customer-facing 대시보드가 제공됩니다. 이 Retool 기반 인터페이스를 통해 사용자는 스크립트 방식 및 비스크립트 방식의 API 호출에 대한 사용량을 추적할 수 있습니다.

현재 API가 RAG 솔루션을 지원하거나 통합할 수 있나요?

저희 API는 RAG(Retrieval-Augmented Generation) 솔루션을 기본적으로 구현하고 있지는 않지만, RAG 워크플로우에 통합하는 것은 충분히 가능합니다. 저희 서비스는 오디오 스트림 분석에 초점을 맞추고 있으며, 그 출력값은 RAG 시스템이나 풍부한 오디오 기반 컨텍스트를 활용하는 다른 파이프라인의 입력으로 사용할 수 있습니다. 보다 맞춤화된 답변이나 최적의 통합 방식을 제안해 드리기 위해, 고객의 의도된 사용 사례나 아키텍처에 대해 좀 더 자세히 공유해 주시기 바랍니다.

AI 발화 기능을 원활하게 사용하려면 어느 정도의 대역폭이 필요한가요?

현재 저희가 제공하는 대역폭 관련 요구 사항은 API 문서에 명시된 내용이 전부입니다. 이 요구 사항은 AI 발화 기능의 사용 방식이나 통합 방법에 관계없이 동일하게 적용됩니다. 특정 사용 사례에 대해 좀 더 자세히 공유해 주시면 보다 정확한 권장 사항을 안내해 드리겠습니다.

각 청크가 어떤 IP 주소에서 전송되었는지 확인할 수 있나요?

현재 저희는 IP 주소와 같은 API 요청의 출처 정보를 보관하지 않습니다. 따라서 각 청크가 어떤 IP에서 전송되었는지 확인할 수 없습니다. 저희 로그는 서비스 기능과 관련된 요청 메타데이터에 초점을 맞추고 있으며, origin-level 네트워크 세부 정보는 포함하지 않습니다.

"utterance" 응답 섹션의 파라미터는 무엇인가요?

utterance 응답 섹션의 파라미터는 다음과 같습니다:

nativeness_score: 전체 발화에 대해 사용자가 달성한 원어민 점수로, 0–100 척도로 표시됩니다.
nativeness_score_partial: 사용자가 실제로 발음한 단어의 부분 집합에 대한 원어민 점수로, 최소 점수 기준은 25%입니다.
decision: nativeness_score를 기반으로 발화 발음에 대한 사용자의 숙련도를 나타내는 문자열입니다. 가능한 값: correct, almost_correct, incorrect.

참고: nativeness_score는 사용자가 말하지 않은 단어를 포함한 발화의 모든 단어를 고려하는 반면, nativeness_score_partial은 낮은 점수를 받더라도 사용자가 실제로 발화한 단어만을 대상으로 합니다.

예시: 발화 내용이 "Hello ELSA"이고 사용자가 "Hello"만 말한 경우, nativeness_score_partial은 "Hello"의 점수만 고려합니다(25%를 초과한다고 가정). 반면 nativeness_score는 발화하지 않은 단어(예: 낮은 점수 또는 0점인 "ELSA")를 포함한 모든 단어를 반영합니다.

자세한 내용은 API 문서를 참조하시기 바랍니다.

"words" 응답 섹션의 파라미터는 무엇인가요?

words 응답 섹션의 파라미터는 다음과 같습니다:

nativeness_score: 개별 단어 발음에 대한 원어민 점수(0–100)입니다.
decision: nativeness_score를 기반으로 한 숙련도 평가로, 가능한 값은 correct, almost_correct, incorrect입니다.

자세한 내용은 API 문서를 참조하시기 바랍니다.

"word_stress" 응답 섹션의 파라미터는 무엇인가요?

word_stress 응답 섹션의 파라미터는 다음과 같습니다:

decision: 사용자가 음절을 올바르게 강세 처리했는지 여부를 나타내며, 가능한 값은 correct 또는 incorrect입니다.

자세한 내용은 API 문서를 참조하시기 바랍니다.

"phonemes" 응답 섹션의 파라미터는 무엇인가요?

phonemes 응답 섹션의 파라미터는 다음과 같습니다:

nativeness_score: 해당 항목의 음소 점수로, 0–100 척도로 표시됩니다.
decision: 음소 발음의 정확도를 나타내며, 가능한 값은 correct, warning, error입니다.

자세한 내용은 API 문서를 참조하시기 바랍니다.

청크 계산 방식

청크의 기본 길이는 15초입니다. 단, 실제 청크 수는 다음 공식으로 계산됩니다:

num_chunks = ceil(duration / chunk_size)

예를 들어, 17초 오디오 입력의 경우 천장 함수 적용으로 인해 2개의 청크가 됩니다(1.13이 아님).

추가 사항:

전체 길이가 API의 최대 허용 길이를 약간 초과하는 경우, 제한 내에 맞도록 잘립니다. 이를 통해 몇 개의 여분 프레임으로 인해 두 번째 요청이 발생하는 것을 방지합니다.
해당하는 경우, 오디오의 시작 또는 끝부분의 무음 및 잡음도 제거하며, 이로 인해 최종 청크 수에 영향을 줄 수 있습니다.

이러한 요인들로 인해 num_standard_chunks가 num_secs / 15와 항상 정확히 일치하지 않을 수 있습니다.

Speech Analyzer는 문법 오류를 어떻게 감지하나요?

저희는 문법 오류를 감지하지만, 문맥상 높은 확신이 있는 경우에만 수정을 제안합니다. 구체적으로, 제안된 수정 사항이 적용되려면 최소 80% 신뢰도 점수를 충족해야 합니다. 이 방식을 통해 문법적 모호성이 있는 경우 불필요한 변경을 제안하는 것을 방지합니다.

최대 오디오 파일 업로드 제한은 얼마인가요?

바이트

업로드 가능한 최대 파일 크기는 100MB입니다. 이 제한을 초과하는 파일을 업로드해야 하는 경우, 지원팀에 문의하시기 바랍니다.

분

sync 플래그가 True로 설정된 비스크립트 요청의 최대 오디오 파일 길이는 15분입니다.

스크립트: 제한 없음
비스크립트:
- sync = True => 15분
- sync = False => 12분

발음 점수와 억양 점수는 서로 관련이 있나요?

pronunciation_score와 intonation_score 사이에는 직접적인 연관성이 없습니다. 다만, 저희는 일반적으로 전체 문장과 같이 길이가 긴 입력에 대해서만 intonation_score를 계산합니다. 따라서 절대 초보자로서 매우 짧거나 불완전한 발화를 하는 경향이 있는 사용자는 intonation_score를 받지 못할 수 있습니다. 이로 인해 두 점수 사이에 연관성이 있는 것처럼 보일 수 있지만, 이는 점수 간 의존성보다는 입력 길이와 품질을 반영하는 것입니다.

발음 및 억양 판정은 어떻게 평가되나요?

이 판정 속성들은 해당 CEFR 레벨 점수(예: pronunciation_cefr, intonation_cefr)를 기반으로 합니다. 매핑 예시는 다음과 같습니다:

Correct: CEFR 레벨 C1 또는 C2
Warning: CEFR 레벨 B1 또는 B2
Incorrect: CEFR 레벨 A1 또는 A2

일부 비스크립트 API 호출에서 EPS 점수나 전사 결과가 누락되는 이유는 무엇인가요?

지표가 포함된 결과를 얻으려면 오디오 길이가 20초를 초과해야 합니다.

발음 레벨이 미국/영국 원어민 억양을 기준으로 매핑되나요?

저희는 글로벌 표준(CEFT, IELTS, TOEFL)을 따르며, 개인의 모국어 억양으로 말하는 것에 불이익을 주지 않고 말의 명료성에 초점을 맞춥니다. 강한 억양을 가진 사용자의 경우 약간의 차이가 있을 수 있지만, 일반적으로 같은 등급 내에서 차이가 유지됩니다.

비스크립트 API 결과에 문법 및 어휘 지표가 누락되는 이유는 무엇인가요?

이 지표들에는 최소 기준이 있습니다. 최소 기준에 관계없이 비스크립트 API에서 문법 및 어휘 지표 결과를 얻고 싶다면 -F force_grammar_vocab=True 플래그를 추가하시면 됩니다. 다만, 이러한 결과는 최소 기준을 충족하는 결과에 비해 정확도가 낮을 수 있습니다.

설명 가능성을 위해 어떤 표준을 사용하나요?

저희 모델은 독점적이며 정확한 아키텍처나 내부 메커니즘을 공개하지 않습니다. 출력 품질 및 성능 벤치마크 측면에서의 투명성을 우선시하지만, 현재 모델 설명 가능성에 대한 공개 표준은 따르고 있지 않습니다.

전체 점수는 어떻게 계산되나요?

전체 점수는 발음, 억양, 유창성, 문법, 어휘의 다섯 가지 지표를 조합하여 산출됩니다. 녹음이 짧아 어휘나 문법 점수를 제공하지 못하는 경우에도, 나머지 이용 가능한 지표를 기반으로 전체 점수를 제공할 수 있습니다.

점수는 어떻게 산출되나요?

ELSA Score 산출 및 IELTS 매핑 방식은 내부적으로 개발된 것입니다. ELSA 점수를 계산하는 파라미터는 시간이 지남에 따라 변경될 수 있으며, IELTS 매핑도 마찬가지입니다. 저희는 주기적으로 이를 재평가하고 일부 조정합니다.

문법 점수에서 문법 범위와 오류의 가중치는 어떻게 되나요?

이 두 항목의 비율은 녹음 유형에 따라 다릅니다. 일상적인 발화의 경우 대략 문법 오류 60%, 문법 범위 40%이며, 시험 유형 환경에서는 대략 문법 오류 50%, 문법 범위 50%입니다. 이 수치는 새로운 데이터가 생기면 조정된다는 점을 유의하시기 바랍니다.

발음 점수는 어떻게 계산되나요?

발음 점수는 녹음에서 ELSA가 인식한 각 단어의 영어 발음이 얼마나 정확한지를 기반으로 합니다. 강조 표시된 _잘못된 발음_의 수와 정도가 발음 점수에 영향을 줍니다.

유창성 점수는 어떻게 계산되나요?

유창성 점수는 속도, 쉬기, 머뭇거림에서의 수행을 조합하여 산출됩니다. 적절한 속도 유지, 자연스러운 위치에서만 쉬기, 간투사 및 반복 횟수 줄이기가 좋은 유창성 점수에 기여합니다.

억양 점수는 어떻게 계산되나요?

억양 점수는 음높이의 상승과 하강, 그리고 문장 내 단어에 얼마나 잘 강세를 부여했는지를 고려합니다.

어휘 점수는 어떻게 계산되나요?

어휘 점수는 주로 사용자 발화에 포함된 단어와 표현의 추정 CEFR 레벨을 기반으로 합니다.

참고: 피드백으로 원시 CEFR 분포(각 A1-C2 레벨에 해당하는 단어의 비율)를 출력하지만, 전체 점수는 이 분포를 0-100 값으로 매핑하는 통계 알고리즘으로 계산됩니다(여기서 100%는 원어민 수준의 어휘 사용에 해당). 어휘 점수는 텍스트가 현재 기준 75단어 이상인 경우에만 반환됩니다.

문법 점수는 어떻게 계산되나요?

문법 점수는 문법 오류 감지 및 수정 모듈의 출력과 식별된 문법 범위를 조합하여 계산됩니다. 문법 오류 감지 및 수정은 텍스트의 문법 오류를 식별하고 오류 점수를 출력합니다. 문법 범위 모듈은 모든 문법 구조를 식별하고 녹음에서 성공적으로 사용된 상위 5개 고급 구조를 기반으로 범위 점수를 계산합니다. 문법 점수는 텍스트가 현재 기준 50단어 이상인 경우에만 반환됩니다.

학습 데이터의 규모와 다양성은 어느 정도인가요?

저희는 모델의 구현 세부 정보나 내부 구조를 공개하지 않지만, 출력 결과가 해석 가능하고 사용자 기대에 부합하도록 하는 것을 최우선으로 합니다. 해당하는 경우, 최종 사용자에게 투명하고 실행 가능한 방식으로 모델의 평가 논리를 반영하는 점수 세부 분석 또는 카테고리별 피드백을 제공합니다. 내부적으로는 강력한 검증 관행을 따르고 성능 벤치마킹을 통해 모델 결정의 일관성과 공정성을 보장합니다.

모델의 정확도는 얼마나 되며, 얼마나 자주 재학습되나요?

저희는 역사적으로 상세한 정확도 수치를 공개적으로 공유하지 않았습니다. 대신 내부 벤치마크를 기반으로 저희 모델이 경쟁사보다 우수하다는 것을 일반적으로 전달해 왔습니다. 모델 재학습 빈도와 관련하여, 이는 모델에 따라 크게 다릅니다. 일부 모델은 장기간 변경되지 않은 반면, 저희의 전반적인 접근 방식은 지속적으로 사용자 데이터(허가된 경우)를 수집하고 반복적으로 모델 성능을 개선하는 것입니다.

편향 또는 차별의 위험은 무엇인가요?

ELSA의 AI는 비원어민 영어 사용자를 지원하기 위해 특별히 제작되었습니다. 실제 제2외국어(L2) 화자로부터 수집한 수천 시간의 억양이 있는 영어로 학습함으로써, ELSA는 학습자의 발음 문제를 인식하고 해결하는 데 독보적인 위치에 있습니다. 이 포용적인 접근 방식은 억양 편향을 줄이고 학습자가 처음부터 인정받고, 지원받고, 자신감을 가질 수 있도록 도와줍니다.

모델에서 "억양"의 가중치는 얼마이며, 윤리적으로 어떻게 처리되나요?

콘텐츠가 스크립트 방식이든 비스크립트 방식이든, 감지율은 약 20%입니다.

이를 윤리적으로 처리하는 방법에 관한 질문은 개인 발화 패턴 감지 가능성이나 음성 스푸핑 관련 위험과 관련이 있을 수 있습니다.

명확히 말씀드리면: 저희 음성 및 억양 분석 시스템은 사용자 음성의 식별 가능한 특성에 독립적으로 설계되었습니다. 저희는 화자 식별을 수행하지 않으며, 해당 목적으로 오디오 데이터를 사용하지도 않습니다. 저희는 오직 언어 학습의 맥락에서 발음과 운율 평가에만 집중합니다.

API 서비스 사용량은 어떻게 추적되나요?

저희는 Retool을 통한 사용량 추적 대시보드를 제공하여 전체 일일 API 사용량에 대한 가시성을 확보할 수 있습니다. 여기에는 처리된 문자 수, 요청 수(스크립트 및 비스크립트 사용별 분류), 플랜 등급, 처리 시간, 청크 수, ASR 요청 수와 같은 지표가 포함됩니다. 또한 각 개별 요청에 대한 등급, 오디오 길이, 전사된 텍스트를 포함한 상세한 요청별 보기도 제공합니다. 이 대시보드는 사용량을 모니터링하고 관리하는 신뢰할 수 있는 방법으로 활용될 수 있습니다.

짧은 오디오에서 문법 또는 어휘 점수가 없는 이유는 무엇인가요?

짧은 오디오의 경우 문법 및 어휘 점수가 생성되지 않을 수 있습니다. 저희 시스템은 신뢰할 수 있고 의미 있는 결과를 생성하기 위해 일반적으로 문법 평가에는 최소 50단어, 어휘 분석에는 75단어 이상을 필요로 합니다.

최상의 결과를 위해 더 긴 오디오 샘플을 제출하시기를 권장합니다. 이를 통해 저희 채점 엔진이 패턴을 분석하고 보다 종합적인 피드백을 제공할 수 있습니다.

점수는 어떻게 매핑되나요?

CEFRIELTSTOEFL SpeakingPTE RangeA11.50-110-10A122-310-10A12.54-510-10A236-710-11A23.58-912-15B1410-1116-19B14.512-2320-25B1514-1526-31B25.516-1732-40B2618-1941-50B26.520-2251-60C1723-2361-70C17.524-2571-79C1826-2780-86C28.528-2987-89C2930-3090-90

참조:

요청이 차단된 이유는 무엇인가요(403 Forbidden)?

요청이 Cloudflare의 Managed Ruleset에 의해 트리거된 하나 이상의 보안 검사로 인해 차단되었을 가능성이 높습니다. 이 규칙들은 특정 상황에서 해당 요청이 해롭지 않더라도 잠재적으로 악의적이거나 의심스러운 트래픽을 감지하고 차단하도록 설계되어 있습니다. 요청이 차단되는 일반적인 이유는 다음과 같습니다:

의심스러운 파일 이름 또는 확장자: 예를 들어, ".php", ".asp" 또는 기타 실행 가능한 형식으로 끝나는 파일은 요청에서 업로드되거나 참조될 때 종종 차단됩니다. 이는 익스플로잇 시도에 일반적으로 사용되기 때문입니다.
비정상적인 헤더 또는 페이로드: 요청 본문이나 헤더에 예상치 못한 콘텐츠(예: 코드 인젝션 패턴 또는 잘못된 형식의 데이터)가 포함된 경우 Cloudflare가 이를 의심스럽게 표시할 수 있습니다.
알려진 익스플로잇 시그니처와 일치하는 파라미터: 예를 들어, 요청이 다음과 같은 알려진 취약점과 일치할 수 있습니다:
- CVE-2018-9206: jQuery File Upload 플러그인의 익스플로잇.
- CVE-2019-17132: 게시판 원격 코드