常見問題解答

我在哪裡可以找到 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（API 權杖）將在 NDA（保密協議）簽署後由我們產生。請在完成簽署後通知我們，我們將提供該權杖。使用說明已在文件中列明。

API 請求與回應的結構和限制為何？

您可以在 API 文件中找到詳細的請求與回應結構，包括 parameters（參數）和 limitations（限制）。

是否提供沙盒環境，以及是否需要測試帳號？

我們目前不提供 staging（預備）環境。

是否有儀表板或日誌可用於監控和除錯？

我們提供 customer-facing（面向客戶）的儀表板，以呈現請求和活動的可見性。此以 Retool 為基礎的介面讓使用者可以追蹤腳本式和非腳本式 API 呼叫的使用情況。

我們的 API 目前是否支援或能整合 RAG 解決方案？

雖然我們的 API 並未原生實作 RAG（Retrieval-Augmented Generation，檢索增強生成）解決方案，但它確實可以整合至 RAG 工作流程中。我們的服務專注於音訊串流分析，其輸出結果可作為 RAG 系統或其他受益於豐富音訊衍生情境之管道的輸入。為了提供更具針對性的解答或建議最佳整合方式，請分享更多有關客戶預期使用情境或其架構的詳情。

流暢的 AI 語音功能需要多少頻寬？

目前，我們所提供的頻寬相關要求僅限於 API 文件中所列項目，無論 AI 語音功能如何使用或整合，這些要求皆適用。如果您能分享更多有關您具體使用情境的資訊，我們將很樂意提供更精確的建議。

是否可以識別每個區塊是從哪個 IP 位址傳送的？

目前，我們不保留任何有關 API 請求來源的資訊，例如 IP 位址。這意味著我們無法確定每個區塊是從哪個 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 則會計入所有詞彙，包括未說出的詞彙（例如「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% 的信心分數才會被採用。此方法可確保我們避免在文法語義模糊的情況下提出不相關的更改建議。

音訊檔案上傳的最大限制為何？

位元組（Bytes）

允許上傳的最大檔案大小為 100MB。若您需要上傳超過此限制的檔案，請聯絡我們的支援團隊尋求協助。

分鐘（Minutes）

同步旗標設為 True 的非腳本式請求，允許上傳的音訊檔案最大長度為 15 分鐘。

腳本式：無限制
非腳本式：
- sync = True => 15 分鐘
- sync = False => 12 分鐘

發音分數和語調分數有關聯嗎？

pronunciation_score 和 intonation_score 之間沒有直接的依賴關係。然而，我們通常僅針對較長的輸入（例如完整句子）計算 intonation_score。因此，完全初學者因傾向產出非常短暫或不完整的語句，可能不會獲得 intonation_score。這可能給人一種兩者有關聯的印象，但這更多反映的是輸入長度和品質，而非分數之間的依賴關係。

發音和語調的決策是如何評估的？

這些決策屬性是基於對應的 CEFR-level（歐洲語言共同參考框架等級）分數（例如 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。但請注意，這些結果的準確度可能不如符合最低門檻的結果。

我們使用什麼可解釋性標準？

我們的模型為專有模型，不對外揭露確切的架構或內部機制。雖然我們在輸出品質和效能基準方面優先考量透明度，但目前並未遵循任何公開的模型可解釋性標準。

我們如何計算整體分數？

整體分數是以下五項指標的綜合結果：pronunciation（發音）、intonation（語調）、fluency（流暢度）、grammar（文法）和 vocabulary（詞彙）。有時，若因錄音較短而未提供詞彙或文法分數，我們仍可根據其他可用指標提供整體分數。

分數是如何計算的？

我們計算 ELSA Score 並將其映射至 IELTS 的方式是內部自行研發的。計算 ELSA 分數的參數可能會隨時間變化，映射至 IELTS 的方式亦然。我們會不定期重新評估並進行微調。

文法分數中，文法範疇和文法錯誤的權重如何？

這些面向的比例取決於錄音的類型。對於日常對話，大約為 60% 文法錯誤和 40% 文法範疇；對於考試情境，大約為 50% 文法錯誤和 50% 文法範疇。請注意，這些數值會在我們取得新資料時進行調整。

我們如何計算發音分數？

發音分數是根據您在錄音中每個被 ELSA 識別的詞彙中，英語發音的準確程度來計算的。被標示的_發音錯誤_數量和嚴重程度將影響發音分數。

我們如何計算流暢度分數？

流暢度分數是 Pace（語速）、Pausing（停頓）和 Hesitations（猶豫）三項表現的綜合結果。保持良好的語速、僅在自然之處停頓，以及減少填充詞和重複，都有助於獲得良好的流暢度分數。

我們如何計算語調分數？

intonation（語調）分數會考量您音調的升降變化，以及您對句子中詞彙的強調程度。

我們如何計算詞彙分數？

Vocabulary（詞彙）分數主要根據使用者語音中詞彙和表達方式的估計 CEFR levels（CEFR 等級）來計算。

注意：我們輸出 raw（原始）CEFR 分布作為回饋（每個 A1-C2 等級的詞彙百分比），但整體分數由統計演算法將此分布映射至 0-100 的數值（其中 100% 對應母語級詞彙使用）。vocabulary（詞彙）分數僅在文字（目前）達到 75 個詞彙或以上時才會回傳。

我們如何計算文法分數？

grammar（文法）分數是根據文法錯誤偵測與修正模組的輸出結果，結合所識別的文法範疇來計算的。文法錯誤偵測與修正模組會識別文本中的文法錯誤並輸出錯誤分數。文法範疇模組會識別所有文法結構，並根據錄音中成功使用的最高等級的 5 種結構來計算範疇分數。grammar（文法）分數僅在文字（目前）達到 50 個詞彙或以上時才會回傳。

訓練資料的數量和多樣性為何？

雖然我們不揭露模型的實作細節或內部結構，但我們致力於確保輸出結果具有可解釋性，並符合使用者的期望。在適用情況下，我們會提供 score breakdowns（分數細項）或 category-level（類別層級）回饋，以透明且可行動的方式反映模型的評估邏輯，供終端使用者參考。在內部，我們遵循嚴謹的驗證實務，並對效能進行基準測試，以確保模型決策的一致性和公平性。

模型的準確度如何，多久重新訓練一次？

我們過去並未公開分享詳細的準確度數據。我們通常表示，根據我們的內部基準測試，我們的模型優於競爭對手。關於模型重新訓練頻率，這會因模型而有顯著差異。雖然某些模型在較長時間內保持不變，但我們的整體方法始終如一：在（獲得許可的情況下）收集使用者資料，並持續迭代改善模型效能。

偏見或歧視的風險為何？

ELSA 的 AI 專為支援非母語英語使用者而設計。透過對數千小時的帶腔英語進行訓練（這些資料來源自真實的第二語言（L2）使用者），ELSA 具有獨特的優勢，能夠識別並應對學習者的發音挑戰。這種包容性方法有助於減少腔調偏見，並確保學習者從第一天起就感到被重視、獲得支持和充滿信心。

"intonation"（語調）在模型中的權重為何，以及如何以合乎道德的方式處理？

無論內容是腳本式還是非腳本式，偵測率約為 20%。

關於如何以合乎道德方式處理此問題，相關疑慮可能涉及偵測個人語音模式的潛在風險或聲音欺騙的風險。

澄清說明：我們的語音和語調分析系統設計上對使用者聲音的任何可識別特徵保持不可知（agnostic）。我們不執行說話者識別，也不將音訊資料用於該目的。我們的重點僅在於評估語言學習情境中的發音和韻律。

API 服務使用量如何追蹤？

我們透過 Retool 提供使用量追蹤儀表板，以呈現每日整體 API 使用情況的可見性。這包括以下指標：characters processed（已處理字元數）、request counts（請求數，按腳本式和非腳本式使用量細分）、plan tier（方案等級）、processing time（處理時間）、number of chunks（區塊數量）以及 number of ASR requests（ASR 請求數）。此外，我們還提供詳細的每次請求檢視，其中包含每個個別請求的 tier（等級）、audio length（音訊長度）和 transcribed text（轉錄文字）。此儀表板可作為監控和管理使用量的可靠方式。

為何短音訊沒有文法或詞彙分數？

對於短音訊，文法和詞彙分數可能不會產生，這是預期的行為。我們的系統通常需要至少約 50 個詞彙才能進行文法評估，以及 75 個詞彙才能進行詞彙分析，以產生可靠且有意義的結果。

為獲得最佳結果，我們建議提交較長的音訊樣本。這能讓我們的評分引擎分析規律並提供更全面的回饋。

分數如何映射？

CEFR	IELTS	TOEFL Speaking	PTE Range
A1	1.5	0-1	10-10
A1	2	2-3	10-10
A1	2.5	4-5	10-10
A2	3	6-7	10-11
A2	3.5	8-9	12-15
B1	4	10-11	16-19
B1	4.5	12-23	20-25
B1	5	14-15	26-31
B2	5.5	16-17	32-40
B2	6	18-19	41-50
B2	6.5	20-22	51-60
C1	7	23-23	61-70
C1	7.5	24-25	71-79
C1	8	26-27	80-86
C2	8.5	28-29	87-89
C2	9	30-30	90-90

參考資料：

為何我的請求被封鎖（403 Forbidden）？

您的請求可能因觸發 Cloudflare 的 Managed Ruleset（受管規則集）中的一項或多項安全性檢查而被封鎖。這些規則旨在偵測並防止潛在的惡意或可疑流量——即使該請求在您的特定情境中並無危害。請求被封鎖的常見原因包括：

可疑的檔案名稱或副檔名：例如，以「.php」、「.asp」或其他可執行格式結尾的檔案，在上傳或於請求中引用時通常會被封鎖，因為這些格式常被用於攻擊嘗試。
異常的標頭或酬載：若請求主體或標頭包含非預期的內容（例如程式碼注入模式或格式異常的資料），Cloudflare 可能會將其標示為可疑。
參數符合已知的攻擊特徵：例如，請求可能符合以下已知漏洞的特徵：
- CVE-2018-9206：jQuery File Upload 插件中的漏洞利用。
- CVE-2019-17132：公告遠端程式碼執行漏洞。

即使您的系統未直接受到這些 CVE 的影響，結構或命名上的相似性也可能導致請求被預防性地封鎖。Cloudflare 的處理方式傾向於謹慎為先——優先透過封鎖符合已知攻擊模式或啟發式規則的請求來確保安全性，即使這些請求最終是誤判（false positive）。

解決方式：

您可以將完整的請求詳情（方法、標頭、主體、URL）分享給我們，以便我們分析具體觸發了哪條規則。
若該請求為合法且預期的行為，我們可以考慮安全地建立例外規則或調整您帳號的安全等級。