What it scores
Chinese learners rarely mispronounce a whole character. They miss a tone, swap sh for s, or blur -n and -ng. One POST /v1/assess call returns, for every character:
- a 0–100 grade and timestamps (
words[], one entry per character, with its pinyin); - the initial, final and tone as separate rows, each with
expected,heard, a grade and adecision; - sentence-level
overall,pronunciation,initial,finalandtonegrades.
| Field | Per syllable, for the initial, the final and the tone |
|---|---|
expected | What the reference requires: an initial such as sh, a final such as ang, or a tone number 1–5 (5 = neutral). |
heard | The engine’s estimate of what was said, in the same units. |
score | 0–100 display grade against native-speaker references. |
decision | review, uncertain or no_correction: whether your app should correct this component. |
agrees_with_prompt, confidence, alternatives | In syllables[].components: whether heard equals expected, a confidence label, and the ranked candidates with probabilities. |
start_ms, end_ms | The syllable’s position in the recording, for replaying exactly that slice. |
A real response
A short recording of 你好, scored by the deployed Mandarin model:
{
"id": "req_example",
"language": "zh",
"locale": "zh-CN",
"model_version": "mandarin-human-v2-85741cdf3967-fbf73d85ee88",
"task": "general",
"status": "completed",
"assessable": true,
"reason": null,
"scores": {
"overall": 99.6,
"pronunciation": 97.8,
"initial": 98.2,
"final": 97.3,
"tone": 98,
"fluency": null,
"rhythm": null,
"integrity": null
},
"words": [
{
"word": "你",
"pinyin": "ni3",
"score": 99.3,
"start_ms": 0,
"end_ms": 155,
"phones": [
{
"dimension": "initial",
"expected": "n",
"heard": "n",
"score": 96.6,
"decision": "no_correction",
"flagged": false
},
{
"dimension": "final",
"expected": "i",
"heard": "i",
"score": 96.1,
"decision": "no_correction",
"flagged": false
},
{
"dimension": "tone",
"expected": 3,
"heard": 2,
"score": 99.7,
"decision": "no_correction",
"flagged": false
}
]
},
{
"word": "好",
"pinyin": "hao3",
"score": 99.5,
"start_ms": 155,
"end_ms": 424,
"phones": [
{
"dimension": "initial",
"expected": "h",
"heard": "h",
"score": 99.8,
"decision": "no_correction",
"flagged": false
},
{
"dimension": "final",
"expected": "ao",
"heard": "ao",
"score": 98.5,
"decision": "no_correction",
"flagged": false
},
{
"dimension": "tone",
"expected": 3,
"heard": 3,
"score": 96.3,
"decision": "no_correction",
"flagged": false
}
]
}
],
"syllables": [
{
"index": 0,
"expected": {
"pinyin": "ni3",
"initial": "n",
"final": "i",
"tone": 3
},
"span_ms": [
0,
155
],
"score": 99.3,
"components": {
"initial": {
"expected": "n",
"heard": "n",
"agrees_with_prompt": true,
"score": 96.6,
"confidence": "high",
"decision": "no_correction",
"advice": null
},
"final": {
"expected": "i",
"heard": "i",
"agrees_with_prompt": true,
"score": 96.1,
"confidence": "high",
"decision": "no_correction",
"advice": null
},
"tone": {
"expected": 3,
"heard": 2,
"agrees_with_prompt": false,
"score": 99.7,
"confidence": "high",
"decision": "no_correction",
"advice": null
}
}
},
{
"index": 1,
"expected": {
"pinyin": "hao3",
"initial": "h",
"final": "ao",
"tone": 3
},
"span_ms": [
155,
424
],
"score": 99.5,
"components": {
"initial": {
"expected": "h",
"heard": "h",
"agrees_with_prompt": true,
"score": 99.8,
"confidence": "high",
"decision": "no_correction",
"advice": null
},
"final": {
"expected": "ao",
"heard": "ao",
"agrees_with_prompt": true,
"score": 98.5,
"confidence": "high",
"decision": "no_correction",
"advice": null
},
"tone": {
"expected": 3,
"heard": 3,
"agrees_with_prompt": true,
"score": 96.3,
"confidence": "high",
"decision": "no_correction",
"advice": null
}
}
}
],
"heard": {
"syllables": [
{
"initial": "n",
"final": "i",
"tone": 2
},
{
"initial": "h",
"final": "ao",
"tone": 3
}
]
},
"duration_seconds": 0.54,
"billing": {
"credits": 1,
"balance_credits": 2499
}
}你 was heard with a 2nd tone where a 3rd is written. Before another 3rd tone, that is the correct pronunciation (3-3 tone sandhi), so the decision is no_correction. Third-tone sandhi and the 不 change before a 4th tone are taken into account; the 一 change is not, because it depends on the word.
Request
curl https://api.toneperfect.app/v1/assess \
-H "Authorization: Bearer $TONEPERFECT_API_KEY" \
-H "Idempotency-Key: lesson-42-attempt-1" \
-F "audio=@take.wav" \
-F "text=你好" \
-F "language=zh-CN" \
-F "task=connected_speech"Send simplified or traditional characters in text (up to 100 characters, numbers written in Chinese), or numbered pinyin in pinyin; see the pinyin guide. Use task=connected_speech for sentences: that is the context the component correction decisions are designed for. Audio can be WAV, MP3, M4A, Ogg or WebM, up to 30 seconds.
What it does not do
It scores scripted speech, so you supply the text; it is not speech recognition. Fluency and rhythm are not scored for Mandarin. Pronunciation is assessed against standard Mainland Mandarin.
Known weak spots of the current Mandarin model: the neutral tone is not reliably told apart from a 1st tone, ü / i is the least sensitive final, and a retroflex said where a dental was expected (sh for s) is caught far less often than the reverse. The pack is labelled experimental in /v1/capabilities, and every response names the model_version that scored it. More on the Mandarin pack page and the methodology.