Per gli sviluppatori

Riferimento dell'API

Ogni endpoint, con i suoi parametri, i campi che risponde e un esempio curl da eseguire. Cercalo qui sotto per nome o percorso; cosa significa ogni errore è in Errori dell'API.

Operazioni

POST/api/assess

Valutare la pronuncia

Invia una registrazione e il testo letto; ricevi i punteggi, ogni parola e ogni suono.

Upload di un form multipart. Restituisce sei punteggi da 0 a 100 (accuracy, native_likeness, completeness, fluency, clarity e speech_rate_ratio), il dettaglio di ogni parola con ogni suono atteso e sentito, e aligned_phonemes: la registrazione divisa in suoni, con i tempi, per disegnarla.

La tua chiave API. Obbligatorio: un header X-API-Key con la chiave della tua console operatore.

Parametri

Nome	Dove	Tipo	Obbligatorio	Descrizione
reference_text	form	string	✓	Il testo che ha letto chi impara. Da 1 a 300 caratteri; un testo fatto solo di spazi viene rifiutato.
language	form	string	✓	Lingua del testo, esattamente uno di questi codici: en-GB, en-US, es-ES, de-DE, fr-FR, it-IT, ca-ES. Maiuscole e minuscole contano: `en-gb` viene rifiutato con `400` `assess.unsupportedLanguage`. `en-GB` è l'inglese britannico, `en-US` quello americano.
audio	form	file	✓	La registrazione. L'ideale è WAV (16 kHz, 16 bit, mono); altri formati come WebM o OGG vengono convertiti. Gli upload oltre circa 1 MB ricevono HTTP 413 e vengono valutati solo i primi 15 secondi di una registrazione.
X-API-Key	header	<customer key>	✓	La tua chiave API dalla console operatore.

Risposta

Campo	Tipo	Descrizione
accuracy	number (0–100)	Quanto i suoni corrispondevano a quelli attesi.
native_likeness	number (0–100)	Quota dei suoni attesi pronunciati come li pronunciano i madrelingua, dettagli fini compresi; un suono giusto senza il dettaglio nativo conta in `accuracy`, non qui.
completeness	number (0–100)	Quota dei suoni attesi che sono stati pronunciati.
fluency	number (0–100)	Parlato regolare senza lunghe pause, ponderato per la precisione.
clarity	number (0–100)	Chiarezza: quanto chiaramente lo capirebbe chi ascolta.
speech_rate_ratio	number (0–100)	Quota del tempo tra il primo e l'ultimo suono passata a parlare invece che in pausa.
duration	number (s)	Durata della registrazione in secondi.
analyzed_text	object[]	Una voce per ogni parola del testo, con i campi qui sotto.
analyzed_text[].word	string	La parola come è scritta in `reference_text`.
analyzed_text[].accuracy, clarity	number (0–100)	La precisione e la chiarezza della parola stessa.
analyzed_text[].start_time, end_time	number (s) \| null	Inizio e fine in secondi dall'inizio della registrazione; `null` se non è stata sentita.
analyzed_text[].user_audio_base64	string (base64 WAV) \| null	La registrazione di questa parola, in WAV base64; `null` se non è stata sentita.
analyzed_text[].grapheme_to_phoneme	object[]	Quali lettere formano ogni suono: per ogni `phoneme_index`, i `graphemes` (posizioni delle lettere nella parola).
analyzed_text[].phoneme_details	object[]	Una voce per ogni suono atteso, e per ogni suono in più sentito, con i campi qui sotto.
analyzed_text[].phoneme_details[].phoneme	string	Il suono atteso in AFI; vuoto per un suono in più.
analyzed_text[].phoneme_details[].predicted	string	Il suono sentito, in AFI; vuoto (`""`) se è stato omesso.
analyzed_text[].phoneme_details[].confidence	number (0–1)	Quanto il modello è sicuro del suono sentito, da 0 a 1.
analyzed_text[].phoneme_details[].is_insertion	boolean	Un suono in più che il testo non ha.
analyzed_text[].phoneme_details[].is_close	boolean	Un suono sbagliato, ma vicino a quello atteso.
analyzed_text[].phoneme_details[].is_reference	boolean	Il suono fa parte del testo (false per un suono in più).
analyzed_text[].phoneme_details[].expected_phone, heard_phone	string \| null	Il suono atteso e quello sentito con il dettaglio che gli danno i madrelingua, ad es. `tʰ` o `d̪`; `null` se non c'è.
analyzed_text[].phoneme_details[].detail_off	boolean	`true` quando il suono giusto è stato detto senza il suo dettaglio nativo (`t` per `tʰ`): conta in `accuracy` ma non in `native_likeness`.
analyzed_text[].phoneme_details[].user_audio_base64	string (base64 WAV) \| null	La registrazione di questo suono, in WAV base64; `null` se non ha tempi.
analyzed_text[].phoneme_details[].start_time, end_time	number (s) \| null	Inizio e fine in secondi dall'inizio della registrazione; `null` se non è stata sentita.
aligned_phonemes	object[]	La registrazione come sequenza di suoni: `symbol`, `start`, `end`, `duration`, `word_start`, i `candidates` più probabili e una clip.
waveform	number[]	Campioni di ampiezza per disegnare la registrazione.
processed_audio_base64	string (base64 WAV)	La registrazione ripulita che è stata valutata.

Esempio di richiesta

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

Esempio di risposta

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

Note

L'audio di esempio per lo stesso testo arriva da /api/assess/synthesize, che puoi chiamare in contemporanea.