Output reference

Overview

The API returns a single JSON object describing per‑phoneme scoring, edits, and prosody.

Top‑level fields

language, dialect: Language settings used during analysis (e.g., language: "en", dialect: "en-us").
match_score_mode: Scoring style used for match_score_pct. lenient is the default and gives near-matches some credit. strict only gives credit for accepted matches.
model: Optional public model selector. Send aurora-1 for multilingual adult speech, nova-1 for early-childhood speech, or leave it unset for standard English analysis. The response phone predictions and topk values follow the selected analysis mode.
reference_text: Text used for alignment. If you supply text, this is that value; otherwise it is the auto‑transcription.
reference_phones: IPA phone sequence derived from the reference (array of tokens).
predicted_phones: IPA phone sequence predicted from the audio (array of tokens).
audio: { duration_sec } for the analyzed clip.
audio_duration_sec: Audio duration in seconds (top-level convenience alias).
pause_threshold_sec: Minimum gap size (seconds) used to count a pause.
pauses: List of detected pause spans from model phone timings.
pause_metrics: Aggregate pause statistics for the utterance.
speech_rate_wpm: Words per minute including silence.
articulation_rate_wpm: Words per minute excluding detected silence.
rate_metrics: Expanded speaking-rate object with word count and speaking-time details.
summary: Aggregate accuracy metrics and counts.
word_groups: Intended/reference words used for pronunciation scoring, with canonical IPA, aligned phones, and summaries.

Optional fields (present when available):

recording_quality: Preview signal-quality measurements and recommended result handling. It does not change pronunciation scores or grades. See Recording quality.
transcription: Auto-transcribed text with word timings, timestamped surface-phone observations, and, in verbatim mode, normalized speech events. See Transcription modes.
pronunciation_lattice: Pronunciation selection metadata (when pronunciation_debug=true).
proficiency_metrics: Fluency, prosody, and intelligibility scores (when enable_proficiency_metrics=true).

Recording quality

The optional top-level recording_quality preview describes whether noise, speech level, clipping, or reverberation may make the pronunciation result less reliable. It includes:

status: good, marginal, poor, or unknown;
score_action: use_result, confirm_negative, or retry_recording;
metrics: estimated SNR, speech and noise levels, clipping, duration, and experimental reverberation risk;
reasons: stable machine-readable reason codes;
recommendation: a stable instruction code and whether a retry is recommended;
gate_applied: always false during the preview.

See Check recording quality for the complete schema, thresholds, and integration guidance.

Summary object

avg_match_score_pct: Mean match score across phones.
total_phones: Number of target phones included in the summary.
matches: Count of phones graded match.
num_insertions: Count of inserted phones.
num_deletions: Count of deleted phones.
num_substitutions: Count of substituted phones.

{
  "summary": {
    "avg_match_score_pct": 96.37,
    "total_phones": 648,
    "matches": 511,
    "num_insertions": 19,
    "num_deletions": 44,
    "num_substitutions": 100
  }
}

Word groups

Each entry in word_groups includes:

index: Zero‑based word index.
text: Word text from the reference.
ipa: IPA phone sequence for that word (array of tokens).
syllables: Written syllable chunks and their canonical-phone spans. Supported requests can also include preview lexical-stress metadata. See Lexical stress.
phones: Phone entries belonging to the word.
insertions: Extra predicted phones aligned within this word’s span that do not appear in the reference for that word.
summary: Per‑word aggregates.
prosody: Word‑level pitch and stress contours (when enable_prosody_contours=true).

Optional (when available):

acceptable_pronunciations: Candidate pronunciations.
selected_pronunciation: Chosen pronunciation.
selected_pronunciation_index: Index into acceptable_pronunciations.

Each item in insertions contains:

predicted: The predicted phone.
position: before or after relative to word_phone_index.
word_phone_index: Index within this word’s ipa/phones the insertion anchors to (or null).
word_phone_insert_index: Index where the insertion should be placed inside the word’s ipa array.
predicted_index: Index into the utterance‑level predicted_phones sequence for this inserted phone.
word_phone: The anchor phone token from the word’s IPA (or null).
timestamp_ms: { start, end } boundaries for the inserted phone in milliseconds; either value can be null when no reliable boundary is available.

{
  "word_groups": [
    {
      "index": 4,
      "text": "cities",
      "ipa": ["s", "ɪ", "ɾ", "i", "z"],
      "phones": ["..."],
      "insertions": [
        {
          "predicted": "z",
          "position": "after",
          "word_phone_index": 1,
          "word_phone_insert_index": 2,
          "predicted_index": 15,
          "word_phone": "ɪ",
          "timestamp_ms": {"start": 1860.39, "end": 1920.41}
        }
      ],
      "summary": {
        "avg_match_score_pct": 90.44,
        "total_phones": 5,
        "matches": 3,
        "num_insertions": 1,
        "num_deletions": 0,
        "num_substitutions": 1
      },
      "acceptable_pronunciations": ["s ɪ ɾ i z", "s ɪ t i z"],
      "selected_pronunciation": "s ɪ ɾ i z",
      "selected_pronunciation_index": 0
    }
  ]
}

Phone entries

Each phone entry contains:

index: Zero‑based phone index in the utterance.
target: Expected IPA phone.
predicted: Predicted IPA phone.
timestamp_ms: { start, end } in milliseconds.
match_score_pct: Match score between target and predicted phones. In lenient mode, near-matches can still receive partial credit. In strict mode, substitutions score 0 and accepted matches score 100.
grade: match, substitute, or delete.

For deletions, predicted is null. match_score_pct is nullable, so clients should handle null values. Optional:

topk: The model’s top alternative guesses for that phone, with a confidence_pct for each option.
functional_load: Priority metadata for substituted phones when the error can affect meaning or involves an important phoneme contrast. See Functional load.

{
  "index": 15,
  "target": "s",
  "predicted": "z",
  "timestamp_ms": {"start": 1860.39, "end": 2060.44},
  "match_score_pct": 90.48,
  "grade": "substitute",
  "topk": [
    {"token": "z", "confidence_pct": 91.5},
    {"token": "s", "confidence_pct": 7.81}
  ]
}

Prosody

Word‑level prosody appears on each word_groups[i].prosody (when enable_prosody_contours=true):

pitch_contour_hz: Frame‑level pitch contour (Hz) across the word span, sampled every 10 ms. Unvoiced frames are 0.
stress_contour: Frame‑level stress values (unitless 0–1) sampled every 10 ms. Derived by normalizing log‑energy and relative pitch (semitones vs. the utterance median) and averaging them, so it is best interpreted as relative emphasis within the word, not absolute loudness.

{
  "prosody": {
    "pitch_contour_hz": [169.08, 168.46, 168.55, 167.49, 165.06, 164.52],
    "stress_contour": [0.49, 0.5, 0.54, 0.52, 0.56, 0.55]
  }
}

Proficiency metrics

Returned when enable_proficiency_metrics=true. Evaluates the speech audio holistically. Set enable_proficiency_metrics=true in the analyze request (form field or JSON body) to include this object.

Pause metrics

audio_duration_sec: Clip duration in seconds.
pause_threshold_sec: Minimum duration required for a silence gap to be counted as a pause.
pauses[].start: Pause start time in seconds.
pauses[].end: Pause end time in seconds.
pauses[].duration_sec: Pause length in seconds.
pause_metrics.pause_count: Number of pauses detected.
pause_metrics.average_pause_duration_sec: Mean pause duration.
pause_metrics.total_silence_time_sec: Sum of all detected pause durations.
pause_metrics.pause_ratio: total_silence_time_sec / audio_duration_sec.

{
  "audio_duration_sec": 12.0,
  "pause_threshold_sec": 0.25,
  "pauses": [
    {"start": 2.1, "end": 2.6, "duration_sec": 0.5},
    {"start": 5.2, "end": 5.45, "duration_sec": 0.25}
  ],
  "pause_metrics": {
    "pause_count": 2,
    "average_pause_duration_sec": 0.38,
    "total_silence_time_sec": 0.75,
    "pause_ratio": 0.06
  }
}

Speaking rate metrics

speech_rate_wpm: Words per minute including pauses/silence.
articulation_rate_wpm: Words per minute excluding detected pause time.
rate_metrics.word_count: Words used for the rate calculation.
rate_metrics.speaking_time_sec: audio_duration_sec - total_silence_time_sec.

{
  "speech_rate_wpm": 110.3,
  "articulation_rate_wpm": 132.6,
  "rate_metrics": {
    "word_count": 22,
    "speech_rate_wpm": 110.3,
    "articulation_rate_wpm": 132.6,
    "speaking_time_sec": 9.95
  }
}

Each of fluency, prosody, and intelligibility contains:

value: Score out of 100.
note: Short English explanation of the score.

{
  "proficiency_metrics": {
    "fluency": {
      "value": 100,
      "note": "The speaker delivers the sentence without any hesitations, fillers, or interruptions."
    },
    "prosody": {
      "value": 95,
      "note": "Natural intonation and rhythm with appropriate emphasis on key words."
    },
    "intelligibility": {
      "value": 100,
      "note": "Every word is pronounced clearly and is easy to understand."
    }
  }
}

Notes

pitch_contour_hz includes values for every frame and is not voiced‑masked.
Per‑word stress is normalized within each word, so values are relative rather than absolute.

Example response (abridged)

{
  "language": "en",
  "dialect": "en-us",
  "reference_text": "In recent years, many cities have begun redesigning public spaces...",
  "reference_phones": ["ɪ", "n", "r", "iː", "s", "ə", "n", "t", "..."],
  "predicted_phones": ["ɪ", "n", "r", "iː", "s", "ə", "n", "t", "..."],
  "audio": {"duration_sec": 56.83},
  "audio_duration_sec": 56.83,
  "pause_threshold_sec": 0.25,
  "pauses": [{"start": 2.1, "end": 2.6, "duration_sec": 0.5}],
  "pause_metrics": {
    "pause_count": 1,
    "average_pause_duration_sec": 0.5,
    "total_silence_time_sec": 0.5,
    "pause_ratio": 0.01
  },
  "speech_rate_wpm": 138.66,
  "articulation_rate_wpm": 139.9,
  "rate_metrics": {
    "word_count": 131,
    "speech_rate_wpm": 138.66,
    "articulation_rate_wpm": 139.9,
    "speaking_time_sec": 56.33
  },
  "summary": {
    "avg_match_score_pct": 96.37,
    "total_phones": 648,
    "matches": 511,
    "num_insertions": 19,
    "num_deletions": 44,
    "num_substitutions": 100
  },
  "word_groups": [
    {
      "index": 4,
      "text": "cities",
      "ipa": ["s", "ɪ", "ɾ", "i", "z"],
      "summary": {
        "avg_match_score_pct": 90.44,
        "total_phones": 5,
        "matches": 3,
        "num_insertions": 1,
        "num_deletions": 0,
        "num_substitutions": 1
      },
      "prosody": {
        "pitch_contour_hz": [169.08, 168.46, 168.55, 167.49, 165.06, 164.52],
        "stress_contour": [0.49, 0.5, 0.54, 0.52, 0.56, 0.55]
      },
      "phones": [
        {
          "index": 15,
          "target": "s",
          "predicted": "z",
          "timestamp_ms": {"start": 1860.39, "end": 2060.44},
          "match_score_pct": 90.48,
          "grade": "substitute",
          "topk": [
            {"token": "z", "confidence_pct": 91.5},
            {"token": "s", "confidence_pct": 7.81}
          ]
        },
        {
          "index": 16,
          "target": "ɪ",
          "predicted": "ɪ",
          "timestamp_ms": {"start": 2060.44, "end": 2220.47},
          "match_score_pct": 100.0,
          "grade": "match",
          "topk": [
            {"token": "ɪ", "confidence_pct": 90.95},
            {"token": "iː", "confidence_pct": 4.55}
          ]
        },
        {
          "index": 17,
          "target": "ɾ",
          "predicted": "t",
          "timestamp_ms": {"start": 2220.47, "end": 2260.48},
          "match_score_pct": 61.72,
          "grade": "substitute",
          "topk": [
            {"token": "t", "confidence_pct": 54.07},
            {"token": "ɾ", "confidence_pct": 33.33}
          ]
        }
      ],
      "insertions": [
        {
          "predicted": "z",
          "position": "after",
          "word_phone_index": 1,
          "word_phone_insert_index": 2,
          "predicted_index": 15,
          "word_phone": "ɪ"
        }
      ]
    },
    {
      "index": 9,
      "text": "spaces",
      "ipa": ["s", "p", "eɪ", "s", "ᵻ", "z"],
      "summary": {
        "avg_match_score_pct": 96.0,
        "total_phones": 6,
        "matches": 4,
        "num_insertions": 0,
        "num_deletions": 1,
        "num_substitutions": 1
      },
      "phones": [
        {
          "index": 45,
          "target": "eɪ",
          "predicted": null,
          "timestamp_ms": {"start": 4680.99, "end": 4801.01},
          "match_score_pct": null,
          "grade": "delete",
          "topk": [
            {"token": "eɪ", "confidence_pct": 5.22},
            {"token": "ɪ", "confidence_pct": 0.29}
          ]
        }
      ],
      "insertions": []
    }
  ],
  "proficiency_metrics": {
    "fluency": {
      "value": 82,
      "note": "Generally smooth delivery with minor hesitations between phrases."
    },
    "prosody": {
      "value": 78,
      "note": "Intonation is mostly natural but slightly flat on longer phrases."
    },
    "intelligibility": {
      "value": 91,
      "note": "Nearly all words are clearly articulated and easy to understand."
    }
  }
}

Getting started

Reference

Preview

Overview

Top‑level fields

Recording quality

Summary object

Word groups

Phone entries

Prosody

Proficiency metrics

Pause metrics

Speaking rate metrics

Notes

Example response (abridged)

​Overview

​Top‑level fields

​Recording quality

​Summary object

​Word groups

​Phone entries

​Prosody

​Proficiency metrics

​Pause metrics

​Speaking rate metrics

​Notes

​Example response (abridged)

Overview

Top‑level fields

Recording quality

Summary object

Word groups

Phone entries

Prosody

Proficiency metrics

Pause metrics

Speaking rate metrics

Notes

Example response (abridged)