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):

JSON · excerpt of a real response
{
  "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

LanguageLocaleBelow the wordCorrection decision
Mandarin Chinesezh-CNInitial, final and tone per syllablePer initial, final and tone
Englishen-USPhoneme (IPA), expected vs heard, with timingsPer word
Frenchfr-FRPhoneme (IPA), expected vs heard, with timingsPer word
Spanishes-419Phoneme (IPA), expected vs heard, with timingsPer word
Germande-DEPhoneme (IPA), expected vs heard, with timingsPer word
Italianit-ITPhoneme (IPA), expected vs heard, with timingsPer word
Portuguesept-BRPhoneme (IPA), expected vs heard, with timingsPer word
Russianru-RUPhoneme (IPA), expected vs heard, with timingsPer word
Koreanko-KRPhoneme (IPA), expected vs heard, with timingsPer word
Japaneseja-JPPhoneme (IPA), no word timings yet; bunsetsu-like unitsPer 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:

JSON · 200 OK (real response, trimmed)
{
  "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:

JSON · 200 OK (real response, trimmed)
{
  "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.

LevelWhat you getWhere
SentenceAn 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
WordA 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[]
SoundFor 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:

FieldMeaning
expectedThe phoneme the reference requires, in IPA.
heardThe phoneme the engine estimates was said. An estimate, not a transcription.
score0–100 grade for that sound.
start_ms, end_msWhere the phoneme sits in the recording.
operationThe alignment operation, for example M (match) or S (substitution).
diagnosis_statusexperimental: 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 sh or m;
  • final, such as ang or ai;
  • 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
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:

JSON · 200 OK (real response, trimmed)
{
  "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

Python
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:

PlanPriceCredits per monthPer recording up to 15 s
Starter$10/month2,500$0.0040
Builder$50/month15,000$0.0033
Scale$150/month50,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 null today.
  • 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 warning content_mismatch_suspected or content: on a word or short phrase a learner’s confusion and another word leave the same evidence. Check warnings and completeness when a wrong or partial reading matters.
  • Every language pack is labelled experimental in GET /v1/capabilities, and every response names the model_version that 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.