Per a desenvolupadors

Referència de l'API

Cada endpoint, amb els seus paràmetres, els camps que respon i un exemple de curl que pots executar. Busca'l a sota per nom o ruta; què vol dir cada error és a Errors de l'API.

Operacions

POST/api/assess

Avaluar la pronunciació

Envia una gravació i el text llegit; rep les puntuacions, cada paraula i cada so.

Enviament de formulari multipart. Retorna sis puntuacions de 0 a 100 (accuracy, native_likeness, completeness, fluency, clarity i speech_rate_ratio), el detall de cada paraula amb cada so esperat i sentit, i aligned_phonemes: la gravació dividida en sons, amb els seus temps, per dibuixar-la.

La teva clau d'API. Obligatòria: una capçalera X-API-Key amb la clau de la teva consola d’operador.

Paràmetres

Nom	On	Tipus	Obligatori	Descripció
reference_text	form	string	✓	El text que ha llegit qui aprèn. D’1 a 300 caràcters; un text fet només d’espais es rebutja.
language	form	string	✓	Idioma del text, exactament un d’aquests codis: en-GB, en-US, es-ES, de-DE, fr-FR, it-IT, ca-ES. Les majúscules compten: `en-gb` es rebutja amb `400` `assess.unsupportedLanguage`. `en-GB` és l’anglès britànic, `en-US` l’americà.
audio	form	file	✓	La gravació. El millor és WAV (16 kHz, 16 bits, mono); altres formats com WebM o OGG es converteixen. Els enviaments de més d’1 MB aproximadament reben HTTP 413, i només s’avaluen els primers 15 segons d’una gravació.
X-API-Key	header	<customer key>	✓	La teva clau d’API de la consola d’operador.

Resposta

Camp	Tipus	Descripció
accuracy	number (0–100)	Com de bé han coincidit els sons amb els esperats.
native_likeness	number (0–100)	Proporció dels sons esperats dits com els diuen els nadius, amb tot el detall; un so correcte sense el detall natiu compta a `accuracy`, no aquí.
completeness	number (0–100)	Proporció dels sons esperats que s’han dit.
fluency	number (0–100)	Parla regular sense pauses llargues, ponderada per la precisió.
clarity	number (0–100)	Claredat: amb quina claredat ho entendria qui escolta.
speech_rate_ratio	number (0–100)	Proporció del temps entre el primer i l’últim so dedicada a parlar en lloc de fer pauses.
duration	number (s)	Durada de la gravació en segons.
analyzed_text	object[]	Una entrada per paraula del text, amb els camps de sota.
analyzed_text[].word	string	La paraula tal com està escrita a `reference_text`.
analyzed_text[].accuracy, clarity	number (0–100)	La precisió i la claredat de la mateixa paraula.
analyzed_text[].start_time, end_time	number (s) \| null	Inici i final en segons des del començament de la gravació; `null` si no s’ha sentit.
analyzed_text[].user_audio_base64	string (base64 WAV) \| null	La gravació d’aquesta paraula, en WAV base64; `null` si no s’ha sentit.
analyzed_text[].grapheme_to_phoneme	object[]	Quines lletres formen cada so: per a cada `phoneme_index`, els `graphemes` (posicions de les lletres a la paraula).
analyzed_text[].phoneme_details	object[]	Una entrada per cada so esperat, i per cada so de més que s’ha sentit, amb els camps de sota.
analyzed_text[].phoneme_details[].phoneme	string	El so esperat en AFI; buit per a un so de més.
analyzed_text[].phoneme_details[].predicted	string	El so que s’ha sentit, en AFI; buit (`""`) si s’ha omès.
analyzed_text[].phoneme_details[].confidence	number (0–1)	Com de segur està el model del so sentit, de 0 a 1.
analyzed_text[].phoneme_details[].is_insertion	boolean	Un so de més que el text no té.
analyzed_text[].phoneme_details[].is_close	boolean	Un so equivocat, però proper a l’esperat.
analyzed_text[].phoneme_details[].is_reference	boolean	El so és del text (false per a un so de més).
analyzed_text[].phoneme_details[].expected_phone, heard_phone	string \| null	El so esperat i el sentit amb el detall que hi donen els nadius, p. ex. `tʰ` o `d̪`; `null` si no n’hi ha.
analyzed_text[].phoneme_details[].detail_off	boolean	`true` quan el so correcte s’ha dit sense el seu detall natiu (`t` per `tʰ`): compta a `accuracy` però no a `native_likeness`.
analyzed_text[].phoneme_details[].user_audio_base64	string (base64 WAV) \| null	La gravació d’aquest so, en WAV base64; `null` si no té temps.
analyzed_text[].phoneme_details[].start_time, end_time	number (s) \| null	Inici i final en segons des del començament de la gravació; `null` si no s’ha sentit.
aligned_phonemes	object[]	La gravació com a seqüència de sons: `symbol`, `start`, `end`, `duration`, `word_start`, els `candidates` més probables i un fragment.
waveform	number[]	Mostres d’amplitud per dibuixar la gravació.
processed_audio_base64	string (base64 WAV)	La gravació neta que s’ha avaluat.

Exemple de petició

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

Exemple de resposta

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…"
}

Notes

L’àudio d’exemple per al mateix text ve de /api/assess/synthesize, que pots cridar alhora.