Häufig gestellte Fragen

Wo finde ich Details zur API-Nutzung und zu den Endpunkten?

Bitte lesen Sie den Abschnitt zu den API-Endpunkten in unserer Dokumentation für detaillierte Informationen.

Welche Netzwerkeinstellungen und Zertifikate sind erforderlich?

Die Authentifizierung ist token-based. Alle Details zum Hostnamen und zur Verwendung der API finden Sie in unserer Dokumentation.

Beispiel:

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"'

Weitere Beispiele finden Sie im API-Bereich der Dokumentation.

Wie erhalte ich den API-Schlüssel oder das Token und wie verwende ich ihn/es?

Das API token wird von uns generiert, sobald das NDA unterzeichnet ist. Bitte informieren Sie uns, wenn dies abgeschlossen ist, und wir stellen das Token bereit. Verwendungshinweise sind in der Dokumentation beschrieben.

Wie sind Struktur und Limits von API-Anfragen und -Antworten aufgebaut?

Detaillierte Anfrage- und Antwortstrukturen, einschließlich parameters und limitations, finden Sie in der API-Dokumentation.

Ist eine Sandbox verfügbar und benötige ich ein Testkonto?

Wir stellen derzeit keine staging-Umgebung bereit.

Gibt es ein Dashboard oder Logs für Monitoring und Debugging?

Ein customer-facing-Dashboard ist verfügbar, um Einblick in Anfragen und Aktivitäten zu bieten. Diese auf Retool basierende Oberfläche ermöglicht es Benutzern, ihre Nutzung sowohl für geskriptete als auch für ungeskriptete API-Aufrufe nachzuverfolgen.

Unterstützt unsere API derzeit eine RAG-Lösung oder kann sie in eine solche integriert werden?

Obwohl unsere API keine RAG-Lösung (Retrieval-Augmented Generation) nativ implementiert, kann sie durchaus in RAG-Workflows integriert werden. Unsere Dienste konzentrieren sich auf die Analyse von Audiostreams, und die Ausgaben können als Eingabe für RAG-Systeme oder andere Pipelines verwendet werden, die von einem angereicherten audiobezogenen Kontext profitieren. Um eine präzisere Antwort zu geben oder einen optimalen Integrationsansatz vorzuschlagen, teilen Sie uns bitte etwas mehr über den beabsichtigten Anwendungsfall des Kunden oder dessen Architektur mit.

Welche Bandbreite ist für reibungslose KI-Sprachfunktionen erforderlich?

Derzeit sind die einzigen bandbreitenbezogenen Anforderungen, die wir bereitstellen, die in unserer API-Dokumentation aufgeführten. Diese gelten unabhängig davon, wie die KI-Sprachfunktionen verwendet oder integriert werden. Wenn Sie uns etwas mehr über Ihren spezifischen Anwendungsfall mitteilen, helfen wir Ihnen gerne mit einer genaueren Empfehlung.

Ist es möglich zu ermitteln, von welcher IP-Adresse jeder Chunk gesendet wurde?

Zum jetzigen Zeitpunkt speichern wir keine Informationen über den Ursprung von API-Anfragen, wie z. B. IP-Adressen. Das bedeutet, wir können nicht feststellen, von welcher IP jeder Chunk gesendet wurde. Unsere Logs konzentrieren sich auf Anfrage-Metadaten, die für die Dienstfunktionalität relevant sind, enthalten jedoch keine origin-level-Netzwerkdetails.

Welche Parameter gibt es im Antwortabschnitt „utterance"?

Die Parameter im utterance-Antwortabschnitt sind:

nativeness_score: Der Nativeness-Score, den der Benutzer für die gesamte Äußerung erzielt hat, auf einer Skala von 0–100.
nativeness_score_partial: Dieser Score spiegelt die Nativeness des Benutzers bei der Teilmenge der Wörter wider, die er tatsächlich ausgesprochen hat, mit einem Mindestscore von 25%.
decision: Eine Zeichenkette, die die Kompetenz des Benutzers beim Aussprechen der Äußerung angibt, basierend auf nativeness_score. Mögliche Werte: correct, almost_correct oder incorrect.

Hinweis: Während nativeness_score alle Wörter in der Äußerung berücksichtigt (einschließlich derer, die der Benutzer nicht gesagt hat), konzentriert sich nativeness_score_partial nur auf die vom Benutzer gesprochenen Wörter, auch wenn diese einen niedrigen Score haben.

Beispiel: Wenn die Äußerung „Hello ELSA" lautet und der Benutzer nur „Hello" sagt, berücksichtigt nativeness_score_partial nur den Score von „Hello" (vorausgesetzt, er übersteigt 25%), während nativeness_score alle Wörter einbezieht, einschließlich der nicht gesprochenen (z. B. „ELSA" mit einem niedrigen oder null Score).

Weitere Details finden Sie in der API-Dokumentation.

Welche Parameter gibt es im Antwortabschnitt „words"?

Die Parameter im words-Antwortabschnitt sind:

nativeness_score: Der Nativeness-Score (0–100) für die Aussprache des einzelnen Wortes.
decision: Kompetenzbewertung basierend auf nativeness_score, mit möglichen Werten correct, almost_correct oder incorrect.

Weitere Details finden Sie in der API-Dokumentation.

Welche Parameter gibt es im Antwortabschnitt „word_stress"?

Die Parameter im word_stress-Antwortabschnitt sind:

decision: Gibt an, ob der Benutzer die Silbe korrekt betont hat, mit möglichen Werten correct oder incorrect.

Weitere Details finden Sie in der API-Dokumentation.

Welche Parameter gibt es im Antwortabschnitt „phonemes"?

Die Parameter im phonemes-Antwortabschnitt sind:

nativeness_score: Der Score für die Phoneme in diesem Eintrag, auf einer Skala von 0–100.
decision: Gibt die Genauigkeit der Phonemaussprache an, mit möglichen Werten correct, warning oder error.

Weitere Details finden Sie in der API-Dokumentation.

Wie die Chunk-Berechnung funktioniert

Ein Chunk hat eine Dauer von 15 seconds. Die tatsächliche Anzahl der Chunks wird jedoch nach folgender Formel berechnet:

num_chunks = ceil(duration / chunk_size)

So ergibt beispielsweise eine 17-second-Audioeingabe 2 Chunks (nicht 1,13), aufgrund der Aufrundungsoperation.

Zusätzlich:

Wenn die Gesamtdauer die maximal zulässige Dauer der API geringfügig überschreitet, wird sie auf die Grenzwerte gekürzt. Dies verhindert, dass eine zweite Anfrage aufgrund von nur wenigen zusätzlichen Frames ausgelöst wird.
Wir kürzen außerdem Stille und Rauschen am Anfang oder Ende des Audios, wenn zutreffend, was die endgültige Chunk-Anzahl weiter beeinflussen kann.

Diese Faktoren erklären, warum num_standard_chunks nicht immer exakt mit num_secs / 15 übereinstimmt.

Wie erkennt Speech Analyzer Grammatikfehler?

Wir erkennen grammatikalische Fehler, korrigieren aber nur diejenigen, bei denen wir im Kontext sehr sicher sind. Konkret muss ein vorgeschlagener Korrekturvorschlag einen Konfidenzwert von mindestens 80% erreichen, bevor er angewendet wird. Dieser Ansatz stellt sicher, dass wir keine irrelevanten Änderungen bei grammatikalischer Mehrdeutigkeit vorschlagen.

Welche maximalen Upload-Limits gelten für Audiodateien?

Bytes

Die maximal zulässige Dateigröße für den Upload beträgt 100 MB. Wenn Sie Dateien hochladen müssen, die dieses Limit überschreiten, wenden Sie sich bitte an unser Support-Team.

Minuten

Die maximale Länge einer Audiodatei für ungeskriptete Anfragen mit dem auf True gesetzten Sync-Flag beträgt 15 minutes.

Geskriptet: Nicht begrenzt
Ungeskriptet:
- sync = True => 15 Minuten
- sync = False => 12 Minuten

Sind Aussprache- und Intonations-Scores miteinander verbunden?

Es gibt keine direkte Abhängigkeit zwischen pronunciation_score und intonation_score. Wir berechnen den intonation_score jedoch typischerweise nur für längere Eingaben, z. B. vollständige Sätze. Daher erhalten absolute Anfänger, die dazu neigen, sehr kurze oder unvollständige Äußerungen zu produzieren, möglicherweise keinen intonation_score. Dies kann den Eindruck einer Abhängigkeit erwecken, spiegelt jedoch eher die Eingabelänge und -qualität wider als eine tatsächliche Abhängigkeit zwischen den Scores.

Wie werden Aussprache- und Intonationsentscheidungen bewertet?

Diese Entscheidungsattribute basieren auf den entsprechenden CEFR-level-Scores (z. B. pronunciation_cefr, intonation_cefr). Ein Zuordnungsbeispiel sieht wie folgt aus:

Correct: CEFR-Level C1 oder C2
Warning: CEFR-Level B1 oder B2
Incorrect: CEFR-Level A1 oder A2

Warum fehlen bei einigen ungeskripteten API-Aufrufen EPS-Scores oder Transkripte?

Um Ergebnisse mit Metriken zu erhalten, stellen Sie sicher, dass die Audiolänge 20 seconds überschreitet.

Ist der Aussprache-Level auf einen US/UK-Muttersprachler-Akzent abgebildet?

Wir halten uns an globale Standards (CEFT, IELTS, TOEFL), bei denen Personen nicht für das Sprechen in ihrem Muttersprachen-Akzent benachteiligt werden, sondern der Fokus auf der Sprachverständlichkeit liegt. Obwohl es bei Benutzern mit stärkerem Akzent leichte Abweichungen geben kann, bleiben die Unterschiede in der Regel innerhalb desselben Bands.

Warum fehlen Grammatik- und Vokabularmetriken in ungeskripteten API-Ergebnissen?

Diese Metriken haben einen Mindestschwellenwert. Wenn Sie trotz dieses Mindestschwellenwerts Ergebnisse für Grammatik- und Vokabularmetriken in der ungeskripteten API erhalten möchten, fügen Sie einfach das Flag -F force_grammar_vocab=True hinzu. Es ist jedoch zu beachten, dass diese Ergebnisse möglicherweise nicht so genau sind wie diejenigen, die den Mindestschwellenwert erfüllen.

Welchen Standard verwenden wir für die Erklärbarkeit?

Unsere Modelle sind proprietär, und wir legen die genauen Architekturen oder internen Mechanismen nicht offen. Obwohl wir Transparenz hinsichtlich der Ausgabequalität und Leistungs-Benchmarks priorisieren, folgen wir derzeit keinem öffentlichen Standard für die Modellerklärbarkeit.

Wie berechnen wir den Gesamtscore?

Der Gesamtscore ist eine Kombination aus fünf Metriken: pronunciation, intonation, fluency, grammar und vocabulary. Wenn wir manchmal keine Vokabular- oder Grammatikscores bereitstellen, weil die Aufnahme kurz war, können wir dennoch einen Gesamtscore auf Basis der anderen verfügbaren Metriken liefern.

Wie wird der Score berechnet?

Die Art, wie wir den ELSA Score berechnen und ihn auf IELTS abbilden, wird intern entwickelt. Die Parameter zur Berechnung des ELSA-Scores können sich im Laufe der Zeit ändern, ebenso wie die Zuordnung zu IELTS. Von Zeit zu Zeit überprüfen wir diese und nehmen leichte Anpassungen vor.

Wie werden Grammatikbereich und Fehler im Grammatikscore gewichtet?

Der Anteil dieser Aspekte hängt von der Art der Aufnahme ab. Bei informeller Sprache beträgt das Verhältnis etwa 60% Grammatikfehler und 40% Grammatikbereich, bei prüfungsähnlichen Einstellungen etwa 50% Grammatikfehler und 50% Grammatikbereich. Es ist wichtig zu beachten, dass diese Zahlen angepasst werden, wenn wir neue Daten haben.

Wie berechnen wir den Aussprache-Score?

Der Aussprache-Score basiert darauf, wie genau Sie die englischen Laute in jedem Wort aussprechen, das von ELSA in Ihrer Aufnahme erkannt wurde. Die Anzahl und Schwere der hervorgehobenen Aussprachefehler tragen zum Aussprache-Score bei.

Wie berechnen wir den Flüssigkeits-Score?

Der Flüssigkeits-Score ist eine Kombination aus Ihrer Leistung in den Bereichen Pace, Pausing und Hesitations. Ein gutes Tempo zu halten, nur an natürlichen Stellen zu pausieren und die Anzahl von Füllwörtern und Wiederholungen zu reduzieren, trägt zu einem guten Flüssigkeits-Score bei.

Wie berechnen wir den Intonations-Score?

Der intonation-Score berücksichtigt Anstiege und Abfälle in Ihrer Tonhöhe sowie wie gut Sie Wörter innerhalb von Sätzen betont haben.

Wie berechnen wir den Vokabular-Score?

Der Vocabulary-Score basiert in erster Linie auf den geschätzten CEFR levels der Wörter und Ausdrücke in der Sprache des Benutzers.

Hinweis: Wir geben die raw-CEFR-Verteilung als Feedback aus (prozentualer Anteil der Wörter auf jedem A1-C2-Level), aber der Gesamtscore wird durch einen statistischen Algorithmus berechnet, der diese Verteilung auf einen 0-100-Wert abbildet (wobei 100% einer muttersprachlichen Vokabularnutzung entspricht). Der vocabulary-Score wird nur zurückgegeben, wenn der Text (aktuell) 75 words oder länger ist.

Wie berechnen wir den Grammatik-Score?

Der grammar-Score wird auf der Grundlage der Ausgaben des Grammatikfehlererkennungs- und -korrekturmoduls in Kombination mit dem identifizierten grammatikalischen Bereich berechnet. Die Grammatikfehlererkennung und -korrektur identifiziert grammatikalische Fehler im Text und gibt den Fehlerscore aus. Das Grammatikbereichsmodul identifiziert alle grammatikalischen Strukturen und berechnet den Bereichsscore basierend auf den 5 höchsten Strukturen, die erfolgreich in der Aufnahme verwendet wurden. Der grammar-Score wird nur zurückgegeben, wenn der Text (aktuell) 50 words oder länger ist.

Wie groß ist das Volumen und die Vielfalt der Trainingsdaten?

Obwohl wir keine Implementierungsdetails oder internen Strukturen unserer Modelle offenlegen, sind wir bestrebt sicherzustellen, dass die Ausgaben interpretierbar und mit den Erwartungen der Benutzer abgestimmt sind. Soweit zutreffend, stellen wir score breakdowns oder category-level-Feedback bereit, das die Bewertungslogik des Modells auf eine transparente und handlungsorientierte Weise für den Endbenutzer widerspiegelt. Intern folgen wir robusten Validierungspraktiken und Benchmark-Leistungstests, um Konsistenz und Fairness bei Modellentscheidungen sicherzustellen.

Wie genau sind die Modelle, und wie oft werden sie neu trainiert?

Wir haben in der Vergangenheit keine detaillierten Genauigkeitszahlen öffentlich geteilt. Stattdessen haben wir typischerweise kommuniziert, dass unsere Modelle Mitbewerber basierend auf unseren internen Benchmarks übertreffen. Hinsichtlich der model retraining frequency variiert diese erheblich je nach Modell. Während einige Modelle über längere Zeiträume unverändert geblieben sind, bestand unser Gesamtansatz stets darin, Benutzerdaten (where permitted) zu sammeln und die Modellleistung iterativ zu verbessern.

Welches Risiko besteht für Verzerrungen oder Diskriminierung?

ELSAs KI wurde speziell entwickelt, um non-native Englischsprechende zu unterstützen. Durch das Training mit tausenden von Stunden akzentbehafteten Englischs, das von echten Zweitsprachlernenden (L2) stammt, ist ELSA einzigartig positioniert, um die Ausspracheherausforderungen von Lernenden zu erkennen und zu adressieren. Dieser inklusive Ansatz hilft, Akzentvorurteile zu reduzieren und stellt sicher, dass sich Lernende vom ersten Tag an wahrgenommen, unterstützt und gestärkt fühlen.

Welches Gewicht hat „Intonation" im Modell, und wie wird es ethisch behandelt?

Unabhängig davon, ob der Inhalt scripted oder unscripted ist, beträgt die Erkennungsrate etwa 20%.

Bezüglich der Frage zur ethischen Behandlung ist es möglich, dass die Bedenken sich auf die potenzielle Erkennung individueller Sprachmuster oder Risiken im Zusammenhang mit Voice-Spoofing beziehen.

Zur Klarstellung: Unsere Sprach- und Intonationsanalysesysteme sind so konzipiert, dass sie gegenüber identifizierbaren Merkmalen der Stimme eines Benutzers agnostic sind. Wir führen keine Sprechererkennung durch, noch verwenden wir Audiodaten für diesen Zweck. Unser Fokus liegt ausschließlich auf der Bewertung von Aussprache und Prosodie im Kontext des Sprachenlernens.

Wie wird die API-Dienstnutzung verfolgt?

Wir bieten ein Nutzungs-Tracking-Dashboard über Retool an, das Einblick in den gesamten täglichen API-Verbrauch bietet. Dazu gehören Metriken wie die Anzahl der characters processed, request counts (aufgeteilt nach scripted- und unscripted-Nutzung), plan tier, processing time, number of chunks und number of ASR requests. Darüber hinaus bieten wir eine detaillierte per-request view, die tier, audio length und transcribed text für jede einzelne Anfrage enthält. Dieses Dashboard kann als zuverlässige Möglichkeit zur Überwachung und Verwaltung der Nutzung dienen.

Warum gibt es keine Grammatik- oder Vokabularscores für kurze Audios?

Bei kurzen Audios ist es zu erwarten, dass Grammatik- und Vokabularscores möglicherweise nicht generiert werden. Unser System benötigt in der Regel mindestens etwa 50 words for grammar evaluation und 75 words for vocabulary, um zuverlässige und aussagekräftige Ergebnisse zu erzielen.

Für beste Ergebnisse empfehlen wir die Einreichung längerer Audiobeispiele. Dies ermöglicht es unserer Scoring-Engine, Muster zu analysieren und umfassenderes Feedback zu geben.

Wie werden die Scores zugeordnet?

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

Quellen:

Warum wurde meine Anfrage blockiert (403 Forbidden)?

Ihre Anfrage wurde wahrscheinlich von Cloudflare aufgrund einer oder mehrerer durch deren Managed Ruleset ausgelöster Sicherheitsprüfungen blockiert. Diese Regeln sollen potenziell bösartigen oder verdächtigen Datenverkehr erkennen und verhindern – auch wenn die Anfrage in Ihrem spezifischen Kontext nicht schädlich ist. Einige häufige Gründe, warum eine Anfrage blockiert werden kann:

Verdächtige Dateinamen oder Erweiterungen: Dateien, die auf „.php", „.asp" oder andere ausführbare Formate enden, werden beispielsweise häufig blockiert, wenn sie in einer Anfrage hochgeladen oder referenziert werden, da sie häufig bei Exploit-Versuchen verwendet werden.
Ungewöhnliche Header oder Payloads: Wenn der Anfragekörper oder die Header unerwartete Inhalte enthalten (z. B. Code-Injection-Muster oder fehlerhafte Daten), kann Cloudflare diese als verdächtig kennzeichnen.
Parameter, die bekannten Exploit-Signaturen entsprechen: Die Anfrage könnte beispielsweise bekannten Schwachstellen entsprechen wie:
- CVE-2018-9206: Exploits im jQuery File Upload Plugin.
- CVE-2019-17132: Remote-Code-Execution-Schwachstellen in Bulletin.

Auch wenn Ihr System von diesen CVEs nicht direkt betroffen ist, kann eine strukturelle oder namensähnliche Übereinstimmung dazu führen, dass die Anfrage als Vorsichtsmaßnahme blockiert wird. Cloudflares Ansatz ist es, im Zweifelsfall auf Sicherheit zu setzen – Anfragen, die bekannten Angriffsmustern oder Heuristiken entsprechen, werden blockiert, auch wenn es sich um falsch positive Ergebnisse handelt.

So lösen Sie das Problem:

Sie können uns die vollständigen Anfragedetails (Methode, Header, Body, URL) mitteilen, damit wir analysieren können, was die Regel konkret ausgelöst hat.
Wenn die Anfrage legitim und erwartetes Verhalten ist, können wir in Betracht ziehen, eine Ausnahmeregel zu erstellen oder das Sicherheitslevel für Ihr Konto anzupassen.