Für Entwickler

API-Referenz

Jeder Endpunkt mit seinen Parametern, den Feldern seiner Antwort und einem curl-Beispiel, das du ausführen kannst. Such ihn unten nach Name oder Pfad; was jeder Fehler bedeutet, steht unter API-Fehler.

Operationen

POST/api/assess

Aussprache bewerten

Schick eine Aufnahme und den gelesenen Text; erhalte Werte, jedes Wort und jeden Laut zurück.

Multipart-Formular-Upload. Liefert sechs Werte von 0 bis 100 (accuracy, native_likeness, completeness, fluency, clarity und speech_rate_ratio), eine Aufschlüsselung jedes Wortes mit jedem erwarteten und gehörten Laut, und aligned_phonemes: die Aufnahme in Laute zerlegt, mit Zeitangaben, zum Zeichnen.

Dein API-Schlüssel. Pflicht: ein Request-Header X-API-Key mit dem Schlüssel aus deiner Operator-Konsole.

Parameter

Name	Ort	Typ	Pflicht	Beschreibung
reference_text	form	string	✓	Der Text, den die lernende Person gelesen hat. 1 bis 300 Zeichen; ein Text nur aus Leerzeichen wird abgelehnt.
language	form	string	✓	Sprache des Textes, genau einer dieser Codes: en-GB, en-US, es-ES, de-DE, fr-FR, it-IT, ca-ES. Groß- und Kleinschreibung zählt: `en-gb` wird mit `400` `assess.unsupportedLanguage` abgelehnt. `en-GB` ist britisches Englisch, `en-US` amerikanisches.
audio	form	file	✓	Die Aufnahme. WAV (16 kHz, 16 Bit, mono) ist am besten; andere Formate wie WebM oder OGG werden umgewandelt. Uploads über etwa 1 MB erhalten HTTP 413, und bewertet werden nur die ersten 15 Sekunden einer Aufnahme.
X-API-Key	header	<customer key>	✓	Dein API-Schlüssel aus der Operator-Konsole.

Antwort

Feld	Typ	Beschreibung
accuracy	number (0–100)	Wie genau die Laute den erwarteten entsprachen.
native_likeness	number (0–100)	Anteil der erwarteten Laute, die so gesprochen wurden, wie Muttersprachler sie sprechen, mit allen feinen Details; ein richtiger Laut ohne das muttersprachliche Detail zählt in `accuracy`, nicht hier.
completeness	number (0–100)	Anteil der erwarteten Laute, die gesprochen wurden.
fluency	number (0–100)	Gleichmäßiges Sprechen ohne lange Pausen, gewichtet nach Genauigkeit.
clarity	number (0–100)	Deutlichkeit: wie deutlich jemand Zuhörendes es verstehen würde.
speech_rate_ratio	number (0–100)	Anteil der Zeit zwischen dem ersten und dem letzten Laut, die gesprochen statt pausiert wurde.
duration	number (s)	Länge der Aufnahme in Sekunden.
analyzed_text	object[]	Ein Eintrag pro Wort des Textes, mit den Feldern unten.
analyzed_text[].word	string	Das Wort, wie es in `reference_text` steht.
analyzed_text[].accuracy, clarity	number (0–100)	Genauigkeit und Deutlichkeit dieses Wortes.
analyzed_text[].start_time, end_time	number (s) \| null	Anfang und Ende in Sekunden ab Beginn der Aufnahme; `null`, wenn es nicht gehört wurde.
analyzed_text[].user_audio_base64	string (base64 WAV) \| null	Die Aufnahme dieses Wortes, Base64-WAV; `null`, wenn es nicht gehört wurde.
analyzed_text[].grapheme_to_phoneme	object[]	Welche Buchstaben jeden Laut bilden: für jeden `phoneme_index` die `graphemes` (Positionen der Buchstaben im Wort).
analyzed_text[].phoneme_details	object[]	Ein Eintrag pro erwartetem Laut und pro zusätzlich gehörtem Laut, mit den Feldern unten.
analyzed_text[].phoneme_details[].phoneme	string	Der erwartete Laut in IPA; leer bei einem zusätzlichen Laut.
analyzed_text[].phoneme_details[].predicted	string	Der gehörte Laut in IPA; leer (`""`), wenn er ausgelassen wurde.
analyzed_text[].phoneme_details[].confidence	number (0–1)	Wie sicher sich das Modell beim gehörten Laut ist, von 0 bis 1.
analyzed_text[].phoneme_details[].is_insertion	boolean	Ein zusätzlicher Laut, den der Text nicht hat.
analyzed_text[].phoneme_details[].is_close	boolean	Ein falscher Laut, aber nah am erwarteten.
analyzed_text[].phoneme_details[].is_reference	boolean	Der Laut gehört zum Text (false bei einem zusätzlichen Laut).
analyzed_text[].phoneme_details[].expected_phone, heard_phone	string \| null	Der erwartete und der gehörte Laut mit dem Detail, das Muttersprachler ihm geben, z. B. `tʰ` oder `d̪`; `null`, wenn es keinen gibt.
analyzed_text[].phoneme_details[].detail_off	boolean	`true`, wenn der richtige Laut ohne sein muttersprachliches Detail gesprochen wurde (`t` für `tʰ`): Er zählt in `accuracy`, aber nicht in `native_likeness`.
analyzed_text[].phoneme_details[].user_audio_base64	string (base64 WAV) \| null	Die Aufnahme dieses Lautes, Base64-WAV; `null`, wenn er keine Zeitangabe hat.
analyzed_text[].phoneme_details[].start_time, end_time	number (s) \| null	Anfang und Ende in Sekunden ab Beginn der Aufnahme; `null`, wenn es nicht gehört wurde.
aligned_phonemes	object[]	Die Aufnahme als Folge von Lauten: `symbol`, `start`, `end`, `duration`, `word_start`, die wahrscheinlichsten `candidates` und ein Ausschnitt.
waveform	number[]	Amplitudenwerte zum Zeichnen der Aufnahme.
processed_audio_base64	string (base64 WAV)	Die bereinigte Aufnahme, die bewertet wurde.

Beispielanfrage

curl

curl https://spelly.ch/api/assess \
  -H 'X-API-Key: YOUR_KEY' \
  -F 'reference_text=The weather is lovely' \
  -F language=en-GB \
  -F audio=@recording.wav

Beispielantwort

JSON

{
  "accuracy": 100,
  "native_likeness": 92,
  "completeness": 100,
  "fluency": 100,
  "clarity": 98,
  "speech_rate_ratio": 100.0,
  "analyzed_text": [
    {
      "word": "the",
      "accuracy": 100.0,
      "clarity": 97.93445765972137,
      "phoneme_details": [
        {
          "phoneme": "ð",
          "predicted": "ð",
          "confidence": 0.9709068536758423,
          "is_insertion": false,
          "is_close": false,
          "is_reference": true,
          "expected_phone": "ð",
          "heard_phone": "ð",
          "detail_off": false,
          "user_audio_base64": "UklGRo…",
          "start_time": 0.042020833333333334,
          "end_time": 0.10505208333333334
        },
        {
          "phoneme": "ə",
          "predicted": "ə",
          "confidence": 0.9877822995185852,
          "is_insertion": false,
          "is_close": false,
          "is_reference": true,
          "expected_phone": "ə",
          "heard_phone": "ə",
          "detail_off": false,
          "user_audio_base64": "UklGRi…",
          "start_time": 0.08404166666666667,
          "end_time": 0.16808333333333333
        }
      ],
      "start_time": 0.042020833333333334,
      "end_time": 0.16808333333333333,
      "user_audio_base64": "UklGRu…",
      "grapheme_to_phoneme": [
        {
          "graphemes": [
            0,
            1,
            2
          ],
          "phoneme_index": 0
        },
        {
          "graphemes": [
            0,
            1,
            2
          ],
          "phoneme_index": 1
        }
      ]
    }
  ],
  "waveform": [
    0.00019696683739311993,
    -0.00015526238712482154,
    -0.00024423340801149607,
    1.6281235730275512e-05
  ],
  "duration": 1.387,
  "aligned_phonemes": [
    {
      "index": 0,
      "start": 0.042020833333333334,
      "duration": 0.06303125000000001,
      "end": 0.10505208333333334,
      "symbol": "ð",
      "word_start": false,
      "candidates": [
        {
          "symbol": "ð",
          "confidence": 0.8176507949829102
        }
      ],
      "user_audio_base64": "UklGRo…"
    },
    {
      "index": 1,
      "start": 0.08404166666666667,
      "duration": 0.08404166666666667,
      "end": 0.16808333333333333,
      "symbol": "ə",
      "word_start": false,
      "candidates": [
        {
          "symbol": "ə",
          "confidence": 0.9877822995185852
        }
      ],
      "user_audio_base64": "UklGRi…"
    }
  ],
  "processed_audio_base64": "UklGRn…"
}

Hinweise

Beispiel-Audio für denselben Text kommt von /api/assess/synthesize, das du gleichzeitig aufrufen kannst.