よくある質問

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: ユーザーがutterance全体で達成したネイティブらしさのスコア（0〜100のスケール）。
nativeness_score_partial: ユーザーが実際に発音した単語のサブセットに対するネイティブらしさのスコアを示します（最低スコアは25%）。
decision: nativeness_scoreに基づいて、ユーザーのutteranceの発音の習熟度を示す文字列。使用可能な値：correct、almost_correct、またはincorrect。

注意: nativeness_scoreはutterance内のすべての単語（ユーザーが発音しなかった単語を含む）を考慮しますが、nativeness_score_partialはユーザーが実際に発話した単語のみに注目します（スコアが低い場合も含む）。

例: utteranceが「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の最大許容時間をわずかに超える場合、制限内に収まるよう切り捨てられます。これにより、わずかな余分なフレームによって2回目のリクエストが発生するのを防ぎます。
該当する場合、音声の冒頭または末尾の無音やノイズもトリムされるため、最終的なチャンク数にさらに影響を与えることがあります。

これらの要因により、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を受け取れない場合があります。これは関係性があるように見えるかもしれませんが、スコア間の依存関係というよりも、入力の長さや質を反映しているものです。

発音とイントネーションの評価はどのように行われますか？

これらのdecision属性は、対応する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（語彙）の5つの指標を組み合わせたものです。録音が短いために語彙や文法スコアが提供できない場合でも、他の利用可能な指標に基づいて総合スコアを提供できることがあります。

スコアはどのように計算されますか？

ELSA Scoreの計算方法およびIELTSへのマッピングは社内で開発されています。ELSAスコアの計算パラメーターは時間とともに変化する可能性があり、IELTSへのマッピングも同様です。弊社では定期的に評価を見直し、わずかに調整を行っています。

文法スコアにおける文法の幅とエラーの比重は？

これらの側面の比率は録音の種類によって異なります。日常的な会話では、おおよそ60%が文法エラー、40%が文法の幅となり、試験のような設定ではおおよそ50%が文法エラー、50%が文法の幅となります。なお、これらの数値は新しいデータが得られた際に調整されることをご注意ください。

発音スコアはどのように計算されますか？

発音スコアは、録音においてELSAが認識した各単語の英語の音の発音精度に基づいています。ハイライトされた_誤発音_の数と深刻さが発音スコアに影響します。

流暢さスコアはどのように計算されますか？

流暢さスコアは、Pace（ペース）、Pausing（間の取り方）、Hesitations（ためらい）の各パフォーマンスを組み合わせたものです。適切なペースを維持し、自然な箇所でのみ間を取り、フィラーワードや繰り返しを減らすことで、流暢さスコアが向上します。

イントネーションスコアはどのように計算されますか？

intonation（イントネーション）スコアは、ピッチの上昇と下降、および文中の単語への強調の付け方を考慮しています。

語彙スコアはどのように計算されますか？

Vocabulary（語彙）スコアは、主にユーザーのスピーチに含まれる単語や表現の推定CEFRレベルに基づいています。

注意: rawなCEFR分布はフィードバックとして出力されます（各A1〜C2レベルの単語の割合）が、総合スコアは統計アルゴリズムによってこの分布を0〜100の値にマッピングして計算されます（100%はネイティブに近い語彙使用に相当します）。vocabularyスコアは、テキストが（現時点では）75語以上の場合にのみ返されます。

文法スコアはどのように計算されますか？

grammar（文法）スコアは、文法エラー検出・修正モジュールの出力と、識別された文法の幅を組み合わせて計算されます。文法エラー検出・修正はテキストの文法エラーを識別し、エラースコアを出力します。文法の幅モジュールはすべての文法構造を識別し、録音で使用された上位5つの高レベル構造に基づいて幅スコアを計算します。grammarスコアは、テキストが（現時点では）50語以上の場合にのみ返されます。

トレーニングデータの量と多様性は？

弊社はモデルの実装詳細や内部構造を公開していませんが、出力が解釈可能でユーザーの期待に沿ったものになるよう努めています。該当する場合、エンドユーザーにとって透明性があり実行可能な形でモデルの評価ロジックを反映したscore breakdownsまたはcategory-levelフィードバックを提供しています。社内では、モデルの判断における一貫性と公平性を確保するための堅固な検証実践とパフォーマンスのベンチマーク測定を実施しています。

モデルの精度はどの程度で、どのくらいの頻度で再トレーニングされますか？

これまで詳細な精度数値を公開してきませんでした。その代わり、弊社の内部ベンチマークに基づいて競合他社のモデルを上回ることを一般的にお伝えしてきました。モデルの再トレーニング頻度については、モデルによって大きく異なります。一部のモデルは長期間変更されていませんが、弊社の全体的なアプローチとして、（許可がある場合に）ユーザーデータを収集し、モデルのパフォーマンスを継続的に改善してきました。

バイアスや差別のリスクは何ですか？

ELSAのAIは非ネイティブの英語話者をサポートするために特化して構築されています。実際の第二言語（L2）話者から収集したアクセント付き英語の何千時間ものデータでトレーニングすることで、ELSAは学習者の発音の課題を認識して対処するのに独自の強みを持っています。このインクルーシブなアプローチは、アクセントバイアスを軽減し、学習者が最初から認められ、サポートされ、力を与えられていると感じられるようにします。

モデルにおける「イントネーション」の重みと、倫理的な扱いは？

コンテンツがscriptedかunscriptedかに関わらず、検出率は約20%です。

倫理的な取り扱いに関するご質問については、個々の発話パターンの検出や音声スプーフィングのリスクに関する懸念が含まれている可能性があります。

明確にするために: 弊社の音声・イントネーション分析システムは、ユーザーの声の識別可能な特徴に対してagnostic（非依存）になるよう設計されています。話者識別は行わず、その目的での音声データの使用もしておりません。弊社の焦点は、言語学習のコンテキストにおける発音とプロソディの評価のみです。

APIサービスの使用状況はどのように追跡されますか？

Retoolを通じた使用状況追跡ダッシュボードを提供しており、日次のAPI消費全体を可視化できます。これには、処理された文字数、リクエスト数（scriptedとunscriptedの使用に分けて）、プランティア、処理時間、チャンク数、ASRリクエスト数などのメトリクスが含まれます。また、各個別リクエストのティア、音声の長さ、文字起こしテキストを含む詳細なリクエストごとのビューも提供しています。このダッシュボードは、使用状況を監視・管理するための信頼できる手段として活用できます。

短い音声に文法・語彙スコアがないのはなぜですか？

短い音声の場合、文法・語彙スコアが生成されないことがあるのは想定内です。弊社のシステムでは、信頼性の高い意味のある結果を生成するために、通常、文法評価には最低約50語、語彙分析には75語が必要です。

最良の結果を得るために、より長い音声サンプルの提出を推奨します。これにより、スコアリングエンジンがパターンを分析し、より包括的なフィードバックを提供できます。

スコアはどのようにマッピングされますか？

CEFR	IELTS	TOEFL Speaking	PTE Range
A1	1.5	0-11	0-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によってトリガーされた1つ以上のセキュリティチェックによってブロックされた可能性があります。これらのルールは、悪意のある、または不審なトラフィックを検出・防止するために設計されています（特定のコンテキストでは有害でない場合も含む）。リクエストがブロックされる一般的な理由：

不審なファイル名または拡張子：例えば、「.php」「.asp」などの実行可能形式で終わるファイルは、エクスプロイトの試みで一般的に使用されるため、アップロード時や参照時にブロックされることが多いです。
異常なヘッダーまたはペイロード：リクエストボディやヘッダーに予期しないコンテンツ（コードインジェクションパターンや不正なデータなど）が含まれている場合、Cloudflareが不審とみなすことがあります。
既知のエクスプロイトシグネチャに一致するパラメーター：例えば、以下のような既知の脆弱性と一致する場合があります：
- CVE-2018-9206: jQuery File UploadプラグインのExploit。
- CVE-2019-17132: Bulletinのリモートコード実行の脆弱性。

これらのCVEの直接的な影響がないシステムでも、構造や命名の類似性によってリクエストが予防的にブロックされることがあります。Cloudflareのアプローチは安全を優先し、既知の攻撃パターンやヒューリスティックに一致するリクエストを（誤検知であっても）ブロックすることです。

解決するには:

リクエストの詳細（メソッド、ヘッダー、ボディ、URL）を弊社に共有していただければ、何が具体的にルールをトリガーしたかを分析できます。
リクエストが正当であり期待される動作である場合、お客様のアカウントに対して例外ルールを安全に作成するか、セキュリティレベルを変更することを検討できます。