Pour les développeurs

Référence de l'API

Chaque endpoint, avec ses paramètres, les champs qu'il renvoie et un exemple curl à lancer. Cherche-le ci-dessous par nom ou chemin ; ce que signifie chaque erreur est dans Erreurs de l'API.

Opérations

POST/api/assess

Évaluer la prononciation

Envoie un enregistrement et le texte lu ; récupère les scores, chaque mot et chaque son.

Envoi de formulaire multipart. Renvoie six scores de 0 à 100 (accuracy, native_likeness, completeness, fluency, clarity et speech_rate_ratio), le détail de chaque mot avec chaque son attendu et entendu, et aligned_phonemes : l'enregistrement découpé en sons, avec leur minutage, pour le dessiner.

Ta clé API. Obligatoire : un en-tête de requête X-API-Key avec la clé de ta console opérateur.

Paramètres

Nom	Emplacement	Type	Obligatoire	Description
reference_text	form	string	✓	Le texte que l'apprenant a lu. 1 à 300 caractères ; un texte fait uniquement d'espaces est refusé.
language	form	string	✓	Langue du texte, exactement l'un de ces codes : en-GB, en-US, es-ES, de-DE, fr-FR, it-IT, ca-ES. La casse compte : `en-gb` est refusé avec `400` `assess.unsupportedLanguage`. `en-GB` est l'anglais britannique, `en-US` l'américain.
audio	form	file	✓	L'enregistrement. Le WAV (16 kHz, 16 bits, mono) est idéal ; les autres formats comme WebM ou OGG sont convertis. Les envois de plus d'environ 1 Mo reçoivent HTTP 413, et seules les 15 premières secondes d'un enregistrement sont évaluées.
X-API-Key	header	<customer key>	✓	Ta clé API depuis la console opérateur.

Réponse

Champ	Type	Description
accuracy	number (0–100)	À quel point les sons correspondaient à ceux attendus.
native_likeness	number (0–100)	Part des sons attendus prononcés comme les natifs les prononcent, détails fins compris ; un son juste sans le détail natif compte dans `accuracy`, pas ici.
completeness	number (0–100)	Part des sons attendus qui ont été prononcés.
fluency	number (0–100)	Une parole régulière sans longues pauses, pondérée par la précision.
clarity	number (0–100)	Clarté : à quel point un auditeur le comprendrait clairement.
speech_rate_ratio	number (0–100)	Part du temps entre le premier et le dernier son passée à parler plutôt qu'en pause.
duration	number (s)	Durée de l'enregistrement en secondes.
analyzed_text	object[]	Une entrée par mot du texte, avec les champs ci-dessous.
analyzed_text[].word	string	Le mot tel qu'il est écrit dans `reference_text`.
analyzed_text[].accuracy, clarity	number (0–100)	La précision et la clarté propres au mot.
analyzed_text[].start_time, end_time	number (s) \| null	Début et fin en secondes depuis le début de l'enregistrement ; `null` s'il n'a pas été entendu.
analyzed_text[].user_audio_base64	string (base64 WAV) \| null	L'enregistrement de ce mot, en WAV base64 ; `null` s'il n'a pas été entendu.
analyzed_text[].grapheme_to_phoneme	object[]	Quelles lettres forment chaque son : pour chaque `phoneme_index`, les `graphemes` (positions des lettres dans le mot).
analyzed_text[].phoneme_details	object[]	Une entrée par son attendu, et par son supplémentaire entendu, avec les champs ci-dessous.
analyzed_text[].phoneme_details[].phoneme	string	Le son attendu en IPA ; vide pour un son supplémentaire.
analyzed_text[].phoneme_details[].predicted	string	Le son entendu, en IPA ; vide (`""`) quand il a été omis.
analyzed_text[].phoneme_details[].confidence	number (0–1)	À quel point le modèle est sûr du son entendu, de 0 à 1.
analyzed_text[].phoneme_details[].is_insertion	boolean	Un son supplémentaire que le texte n'a pas.
analyzed_text[].phoneme_details[].is_close	boolean	Un son faux, mais proche du son attendu.
analyzed_text[].phoneme_details[].is_reference	boolean	Le son fait partie du texte (false pour un son supplémentaire).
analyzed_text[].phoneme_details[].expected_phone, heard_phone	string \| null	Le son attendu et le son entendu avec le détail que lui donnent les natifs, par ex. `tʰ` ou `d̪` ; `null` quand il n'y en a pas.
analyzed_text[].phoneme_details[].detail_off	boolean	`true` quand le bon son a été dit sans son détail natif (`t` pour `tʰ`) : il compte dans `accuracy` mais pas dans `native_likeness`.
analyzed_text[].phoneme_details[].user_audio_base64	string (base64 WAV) \| null	L'enregistrement de ce son, en WAV base64 ; `null` quand il n'a pas de minutage.
analyzed_text[].phoneme_details[].start_time, end_time	number (s) \| null	Début et fin en secondes depuis le début de l'enregistrement ; `null` s'il n'a pas été entendu.
aligned_phonemes	object[]	L'enregistrement comme suite de sons : `symbol`, `start`, `end`, `duration`, `word_start`, les `candidates` les plus probables et un extrait.
waveform	number[]	Des échantillons d'amplitude pour dessiner l'enregistrement.
processed_audio_base64	string (base64 WAV)	L'enregistrement nettoyé qui a été évalué.

Exemple de requête

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 réponse

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

Remarques

L'audio d'exemple pour le même texte vient de /api/assess/synthesize, que tu peux appeler en même temps.