What a phoneme row looks like, from a real English response (the word sunny, its second sound heard as ɔ where ə was expected; full response below):
{
"words": [
{
"word": "sunny",
"score": 83.9,
"decision": "no_correction",
"phones": [
{
"expected": "ə",
"heard": "ɔ",
"score": 81.3,
"operation": "S"
}
]
}
]
}Phoneme-level feedback for English and Spanish
Short answer: yes. For English (en-US) and Spanish (es-419), every word in the response carries phones[]: the IPA phoneme the text requires (expected), the phoneme the engine estimates was said (heard), a 0–100 score, timings and an alignment operation (M match, S substitution, D deletion). The correction decision is made per word, and phoneme rows are labelled diagnosis_status: experimental. English is scored against an American reference; Spanish against a Latin American one.
Other APIs that document phoneme-level output for both languages, checked 30 October 2026: Speechace (English US/UK, Spanish Spain/Mexico) and Azure Pronunciation Assessment (phoneme granularity in es-ES, es-MX and its English locales). SpeechSuper lists phoneme scores and an English phoneme demo. See which pronunciation assessment API fits a language learning app for the full comparison.
What each language returns
| Language | Locale | Below the word | Correction decision |
|---|---|---|---|
| Mandarin Chinese | zh-CN | Initial, final and tone per syllable | Per initial, final and tone |
| English | en-US | Phoneme (IPA), expected vs heard, with timings | Per word |
| French | fr-FR | Phoneme (IPA), expected vs heard, with timings | Per word |
| Spanish | es-419 | Phoneme (IPA), expected vs heard, with timings | Per word |
| German | de-DE | Phoneme (IPA), expected vs heard, with timings | Per word |
| Italian | it-IT | Phoneme (IPA), expected vs heard, with timings | Per word |
| Portuguese | pt-BR | Phoneme (IPA), expected vs heard, with timings | Per word |
| Russian | ru-RU | Phoneme (IPA), expected vs heard, with timings | Per word |
| Korean | ko-KR | Phoneme (IPA), expected vs heard, with timings | Per word |
| Japanese | ja-JP | Phoneme (IPA), no word timings yet; bunsetsu-like units | Per word |
Real English response
Reference text I like sunny days., sent to the live demo on 30 October 2026 by a synthetic voice. Trimmed to the word sunny and to fields documented in openapi.json:
{
"language": "en",
"locale": "en-US",
"status": "completed",
"assessable": true,
"model_version": "multilingual-native-v1-en-9de342222052+fallback",
"scores": {
"overall": 88.2,
"pronunciation": 87.4,
"integrity": 100
},
"words": [
{
"word": "sunny",
"expected_ipa": "səni",
"score": 83.9,
"start_ms": 486,
"end_ms": 830,
"decision": "no_correction",
"omission_suspected": false,
"phones": [
{
"expected": "s",
"heard": "s",
"score": 93.3,
"start_ms": 486,
"end_ms": 577,
"operation": "M",
"diagnosis_status": "experimental"
},
{
"expected": "ə",
"heard": "ɔ",
"score": 81.3,
"start_ms": 577,
"end_ms": 688,
"operation": "S",
"diagnosis_status": "experimental"
},
{
"expected": "n",
"heard": "n",
"score": 79.7,
"start_ms": 688,
"end_ms": 769,
"operation": "M",
"diagnosis_status": "experimental"
},
{
"expected": "i",
"heard": "i",
"score": 92.3,
"start_ms": 769,
"end_ms": 830,
"operation": "M",
"diagnosis_status": "experimental"
}
]
}
],
"engine_route": {
"engine": "fallback",
"fallback": true
},
"duration_seconds": 1.82
}The vowel was heard as ɔ where ə was expected (operation: "S", score 81.3). The word still scored 83.9 and its decision is no_correction, so an app would show the row but not interrupt the learner.
Real Spanish response
Reference text Buenos días, ¿cómo estás?, same day, same demo, a synthetic voice. Trimmed to the word días:
{
"language": "es",
"locale": "es-419",
"status": "completed",
"assessable": true,
"model_version": "multilingual-native-v1-es-c75449b9fca0+fallback",
"scores": {
"overall": 96.6,
"pronunciation": 93.8,
"integrity": 100
},
"words": [
{
"word": "días",
"expected_ipa": "dias",
"score": 88.9,
"start_ms": 404,
"end_ms": 980,
"decision": "no_correction",
"omission_suspected": false,
"phones": [
{
"expected": "d",
"heard": null,
"score": 0,
"start_ms": 404,
"end_ms": 454,
"operation": "D",
"diagnosis_status": "experimental"
},
{
"expected": "i",
"heard": "i",
"score": 95.9,
"start_ms": 454,
"end_ms": 566,
"operation": "M",
"diagnosis_status": "experimental"
},
{
"expected": "a",
"heard": "a",
"score": 72.7,
"start_ms": 566,
"end_ms": 717,
"operation": "M",
"diagnosis_status": "experimental"
},
{
"expected": "s",
"heard": "s",
"score": 87,
"start_ms": 717,
"end_ms": 980,
"operation": "M",
"diagnosis_status": "experimental"
}
]
}
],
"engine_route": {
"engine": "fallback",
"fallback": true
},
"duration_seconds": 2.04
}The d of días was not found (operation: "D", heard: null, score 0), yet the word’s decision stays no_correction: one weak row is evidence, not a verdict. Both answers came from the backup engine (engine_route.engine: "fallback"), whose grades are calibrated differently from the primary engine’s; the fields are the same.
What is scored
Scoring is scripted: your app supplies the text the learner reads, so every result is measured against a known target. One POST /v1/assess request returns three linked levels.
| Level | What you get | Where |
|---|---|---|
| Sentence | An overall grade plus the dimensions the language supports: pronunciation and completeness, or initial, final and tone for Mandarin. Fluency and rhythm are reserved and null with the current engine. | scores |
| Word | A grade and start_ms / end_ms for every word (every character in Mandarin), so you can highlight it and replay exactly that slice. Outside Mandarin each word also carries its expected_ipa, the correction decision and omission_suspected. | words[] |
| Sound | For every phoneme, or every Mandarin initial, final and tone: expected, heard and a score. | words[].phones[] |
Grades are display scores calibrated per unit against native-speaker references. They are not accuracy percentages, and a 70 in one language is not the same distance from native as a 70 in another. A dimension a language does not measure is null, never zero.
Phoneme scoring: expected vs heard
For English, French, Spanish, German, Italian, Portuguese, Russian, Korean and Japanese, the reference text is converted to the phonemes a native speaker would say. Each phoneme row in words[].phones[] has:
| Field | Meaning |
|---|---|
expected | The phoneme the reference requires, in IPA. |
heard | The phoneme the engine estimates was said. An estimate, not a transcription. |
score | 0–100 grade for that sound. |
start_ms, end_ms | Where the phoneme sits in the recording. |
operation | The alignment operation, for example M (match) or S (substitution). |
diagnosis_status | experimental: phoneme rows are evidence for the learner, not validated corrections. |
The correction decision for these languages is made per word: review when the evidence of an error is strong, uncertain when it is not, no_correction otherwise. Act on the word’s decision and use the phoneme rows to show where the word went wrong, for example an English learner whose ʌ in sunny came out closer to ɑ. Japanese words are bunsetsu-like units, and they have no timings yet.
Sounds outside a pack’s inventory (the English ɝ of bird, for instance) are returned as unassessed rather than wrong: the warning unsupported_phonetic_symbols is set and phonetic_coverage lists the affected words, so your UI can say “not assessed”.
Mandarin: initial, final and tone per syllable
Mandarin is not split into phonemes. Every character is one syllable, scored as three components, each with its own expected, heard, grade and decision:
- initial, such as
shorm; - final, such as
angorai; - tone, as a number from 1 to 5 (5 = neutral).
syllables[].components adds agrees_with_prompt, a confidence label and, where the engine reports them, alternatives: the ranked candidates with probabilities. Third-tone sandhi and 不 before a 4th tone are taken into account, so a learner who applies them correctly is not told the tone is wrong. Details on the Mandarin tone scoring and Chinese pronunciation API pages.
A real request and response
The reference text was 我想卖书 (“I want to sell books”, mài, 4th tone); the learner said mǎi (“buy”, 3rd tone). The request:
curl https://api.toneperfect.app/v1/assess \
-H "Authorization: Bearer $TONEPERFECT_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-F "audio=@take.wav" \
-F "text=我想卖书" \
-F "language=zh-CN" \
-F "task=connected_speech"The response from the deployed Mandarin model, trimmed to the scored syllable:
{
"id": "req_example",
"language": "zh",
"locale": "zh-CN",
"model_version": "mandarin-human-v2-85741cdf3967-fbf73d85ee88",
"task": "connected_speech",
"status": "completed",
"assessable": true,
"reason": null,
"scores": {
"overall": 99.3,
"pronunciation": 97.8,
"initial": 97.8,
"final": 97.9,
"tone": 81.7,
"fluency": null,
"rhythm": null,
"integrity": null
},
"words": [
{
"word": "卖",
"pinyin": "mai4",
"score": 96.4,
"start_ms": 423,
"end_ms": 645,
"phones": [
{
"dimension": "initial",
"expected": "m",
"heard": "m",
"score": 96.7,
"decision": "no_correction",
"flagged": false
},
{
"dimension": "final",
"expected": "ai",
"heard": "ai",
"score": 98.1,
"decision": "no_correction",
"flagged": false
},
{
"dimension": "tone",
"expected": 4,
"heard": 3,
"score": 60,
"decision": "uncertain",
"flagged": false
}
]
}
],
"syllables": [
{
"index": 2,
"expected": {
"pinyin": "mai4",
"initial": "m",
"final": "ai",
"tone": 4
},
"span_ms": [
423,
645
],
"score": 96.4,
"components": {
"initial": {
"expected": "m",
"heard": "m",
"agrees_with_prompt": true,
"score": 96.7,
"confidence": "high",
"decision": "no_correction",
"advice": null
},
"final": {
"expected": "ai",
"heard": "ai",
"agrees_with_prompt": true,
"score": 98.1,
"confidence": "high",
"decision": "no_correction",
"advice": null
},
"tone": {
"expected": 4,
"heard": 3,
"agrees_with_prompt": false,
"score": 60,
"confidence": "high",
"alternatives": [
{
"label": 4,
"probability": 0.0004
},
{
"label": 3,
"probability": 0.9986
},
{
"label": 2,
"probability": 0.0008
},
{
"label": 1,
"probability": 0.0002
}
],
"decision": "uncertain",
"advice": null
}
}
}
],
"heard": {
"syllables": [
{
"initial": "m",
"final": "ai",
"tone": 3
}
]
},
"duration_seconds": 0.989,
"billing": {
"credits": 1,
"balance_credits": 2499
}
}The initial m and the final ai were heard as expected and graded above 96. The tone was heard as a 3rd (probability 0.9986) where a 4th was expected, and its grade fell to 60. The decision is uncertain rather than review: the grade says how native-like a sound was, the decision says whether the evidence is strong enough to interrupt the learner. Show the grade; act on the decision.
The same request works for every language: change text and language, for example -F "text=I like sunny days." -F "language=en-US". The language pages show each pack’s fields and limits, and the API reference documents every field. To get a versioned, stable shape, send TonePerfect-Response: compact: each word then lists its units with dimension (phoneme, or initial / final / tone), expected, heard, score and decision.
Reading phoneme rows in code
for word in result["words"]:
if word.get("decision") != "review":
continue # non-Mandarin: the correction decision is on the word
for p in word.get("phones", []):
if p["expected"] != p["heard"]:
print(f'{word["word"]}: expected /{p["expected"]}/, heard /{p["heard"]}/ ({p["score"]})')For Mandarin, read the decision on each initial, final and tone row instead; the tone scoring guide has the loop.
Pricing and free credits
Every new account gets 50 free credits, no card and no subscription, through the real API with your own key. Then:
| Plan | Price | Credits per month | Per recording up to 15 s |
|---|---|---|---|
| Starter | $10/month | 2,500 | $0.0040 |
| Builder | $50/month | 15,000 | $0.0033 |
| Scale | $150/month | 50,000 | $0.0030 |
One credit covers each started 15 seconds of a recording: two credits for 15–30 seconds, eight at the 120-second maximum. Every plan includes all 10 languages and every score dimension, at the same price. Failed and unassessable requests are not charged, and a retry with the same Idempotency-Key is charged once. Unused credits roll over while you subscribe. Details on the pricing page.
Limits
- Scripted speech only: it is not speech recognition, and it does not score unscripted answers.
- Up to 120 seconds and 10 MB of audio per request, in WAV, MP3, M4A, Ogg or WebM. Audio is deleted after scoring.
- Lexical stress, intonation and Japanese pitch accent are not scored; fluency and rhythm are
nulltoday. - A recording of a different sentence of 10 syllables or more (Mandarin: 10 characters) is refused (
different_content, not charged) in every language. A shorter prompt is scored instead, usually low, with warningcontent_mismatch_suspectedorcontent: on a word or short phrase a learner’s confusion and another word leave the same evidence. Checkwarningsand completeness when a wrong or partial reading matters. - Every language pack is labelled
experimentalinGET /v1/capabilities, and every response names themodel_versionthat scored it. See the methodology for what that means.
Compared with other pronunciation assessment APIs
Side-by-side notes on fields, languages and pricing: TonePerfect vs SpeechSuper, Speechace alternative, Azure pronunciation assessment alternative and all comparisons. For background, read how pronunciation scoring works.