Score Text
The Score Text API scores a speaker reading a known script aloud — a phrase, a sentence, or a passage of up to 45 seconds. Pronunciation is always scored; fluency, lexical stress, and intonation are added on demand, and you can override the expected phonemes with markup or match the speaker against a set of choices. Everything runs through a single endpoint — the capabilities below are switched on with request parameters, not separate APIs.
For scoring a single word, letter name, letter sound, or non-word, use Score Word. For spontaneous, open-ended speech, use Score Speech.
Scoring modes
Pronunciation
(default — always on)
Word, syllable, and phoneme quality_score, phoneme and syllable stress_score plus overall Pronunciation score.
Fluency
include_fluency=1
Overall Fluency score (Speechace, IELTS, PTE, TOEIC, CEFR).
A fluency node with rate, pauses, and articulation metrics, segment level metrics, plus fidelity detection.
Intonation
include_intonation=1
Pitch and intonation information in word_intonation_list and syllable_intonation_list.
Markup language
markup_language=arpa_mark
Scores against phonemes you specify inside the text, instead of the Speechace lexicon.
Multiple choice
A list of Newline-separated options in the text parameter
Matches the speaker to the closest option, then scores that option's pronunciation.
Request Format
The endpoint you use depends on the region of your subscription. For example, for US West the endpoint is https://api.speechace.co.
POST https://api.speechace.co/api/scoring/text/v9/json
Query Parameters
dialect
String
This is the dialect in which the speaker will be assessed.
Note: Not all features of the score/text API support every dialect. Applicable dialects will be explicitly mentioned.
user_id
String
Optional: A unique anonymized identifier (generated by your application) for the end-user who spoke the audio.
Request Body
text
String
A word, phrase, or sentence to score. This should be in the dialect chosen. For example, if fr-fr is the chosen dialect, then the word can be Salut.
user_audio_file
File
file with user audio (wav, mp3, m4a, webm, ogg, aiff)
question_info
String
Optional: A unique identifier (generated by your application) for the activity or question this user audio is answering.
no_mc
String
Optional: no_mc = 1 to indicate the text field is not a Multiple Choice request. This is the default when include_fluency = 1.
include_fluency
String
Optional: include_fluency= 1 to include fluency scoring in the response.
See this guide for how to use this field.
include_intonation
String
Optional: include_intonation= 1 to include intonation (pitch) scores.
See this guide for how to use this field.
markup_language
String
Optional: markup_language = arpa_mark
This key signifies that the text parameter may contain markup annotations.
See this guide for how to use this field.
include_unknown_words
String
Optional: include_unknown_words = 1
This key instructs Speechace to automatically infer the expected pronunciation for unknown terms, such as names, places, and other specific terminology. This ensures accurate feedback even for unfamiliar words.
detect_dialect
String
Optional field: Possible values - 0 | 1
1: will apply language detection and warn if the majority of the response language is different from the intended scoring dialect.
Request Examples
The examples below show each mode called against a sentence or passage. Request parameters are identical across modes — only the highlighted fields change.
A. Pronunciation
text="Some parents admire famous athletes as strong role models, so they name their children after them."
Score how clearly a read-aloud phrase, sentence, or passage is pronounced.
B. Fluency
text="Yes, I do. Travel today is vastly different…" (full passage)
include_fluency="1"
Score fluency together with pronunciation for a passage read aloud (up to 45 seconds).
C. Intonation
text="Some parents admire famous athletes as strong role models…"
include_intonation="1"
Add pitch and intonation metrics for the passage. (Lexical stress is returned by default.)
D. Markup
text="I love to [read]{r iy1 d}. Last year I [read]{r eh1 d} Anna Karenina by [Tol|stoy]{t ow1 l|s t oy2}."
markup_language="arpa_mark"
Prescribe the exact expected phonemes — e.g. to fix a heteronym or spell out an acronym.
E. Multiple Choice
text="I went to the park.\nI went to the market."
Match the speaker to the closest of several target sentences, then score that sentence.
Markup language
When markup_language=arpa_mark is set, the text may carry markup on zero, one, or many words. Each markup has the pattern [l1|l2|...|ln]{s1|s2|...|sn}, where l1..ln are substrings of the word and s1..sn are the corresponding syllables; each syllable is a space-separated list of ARPABET phonemes, and a vowel phoneme ends in 0, 1, or 2 to mark its stress. Use it to:
Specify exact syllable boundaries and phonemes —
There was [noth|ing]{n ah1 th|ih0 ng} on the rock.Disambiguate a heteronym (same spelling, different pronunciation) —
He [read]{r eh1 d} his [frag|ments]{f r ae1 g|m ah0 n t s} aloud.Handle acronyms, numbers, or special terms —
Agent [0||||07]{d ah1 | b ah0 l | ow1 | s eh1 | v ah0 n} worked for MI6.
The spoken-score interpretation is unchanged from the default mode — the only difference is that the expected phonemes come from your markup rather than the Speechace lexicon. For the full specification, see the Markup Language guide.
Response Examples
Response fields
Overall scores
The overall score rates the pronunciation quality of the whole utterance, expressed on several standard scales.
Word scores
Each entry in word_score_list[] carries a quality_score (0–100) for that word. Use it to colour-code feedback:
90 – 100
Green
Excellent. Native or native-like.
80 – 90
Green
Very good and clearly intelligible.
70 – 80
Orange
Good. Intelligible but with one or two evident mistakes.
60 – 70
Red
Fair. Possibly not intelligible, with several evident mistakes.
0 – 60
Red
Poor and must be reattempted.
See the quality-score guide for the full scale.
Phoneme & syllable scores
Within each word, phone_score_list[] and syllable_score_list[] give a quality_score at the phoneme and syllable level. Each syllable also reports stress_level (the expected stress), predicted_stress_level (the stress detected in the audio), and stress_score (0–100, how correct the stress was), where stress is 0 = unstressed, 1 = primary, 2 = secondary. Each phoneme reports sound_most_like — the phoneme the speaker's sound most resembled, which pinpoints substitution errors.
Intonation metrics
Returned when include_intonation=1. Lexical stress (stress_level, predicted_stress_level, stress_score) is part of the default response — see Phoneme & syllable scores above; include_intonation adds pitch and intonation on top of it.
syllable_score_list[] adds:
pitch_range[]—[begin_pitch, end_pitch]for the syllable, in Hertz.
word_intonation_list[] adds, per syllable, syllable_intonation_list[] = [pitch_change_from_previous, pitch_change_in_current]:
pitch_change_from_previous — pitch movement from the previous syllable to the start of this one.
nullif the syllable wasn't recognised;REDUCEDif recognised but unvoiced.pitch_change_in_current — pitch movement across the current syllable. Values:
RISE,FALL,FLAT,REDUCED, ornull.
Compare the expected against the detected intonation to visualise an intonation "staircase" for the learner.
Fluency metrics
Returned when include_fluency=1, under the fluency node. Overall fluency scores appear alongside the pronunciation scores on the standard scales (see the overall-scores guide); the per-response metrics are:
duration
Total length of speech in seconds.
articulation
Length of articulation (speech minus pauses, hesitations, and non-speech events such as laughter). Excludes leading silence on the first segment and trailing silence on the last.
speech_rate
Speaking rate in syllables per second.
syllable_count / word_count
Count of syllables / words in the segment.
correct_syllable_count / correct_word_count
Count of correctly spoken syllables / words in the segment.
syllable_correct_per_minute / word_correct_per_minute
Correct count divided by duration in minutes.
all_pause_count / all_pause_duration
Count and total seconds of all pauses (filled and unfilled) longer than the minimum threshold.
all_pause_list[]
Every pause with begin/end markers, in extents of 10 ms.
mean_length_run / max_length_run
Mean / max run length in syllables between pauses.
segment_metrics_list[]
The above metrics computed per segment of the text/audio.
The most commonly surfaced metrics are word_correct_per_minute (compare against ~120 wpm, a common minimum fluent rate), all_pause_list[] (flag medium pauses ≥500 ms and long pauses >1 s), and duration vs. articulation (how much of the time was actual speech).
Fidelity detection
A unique capability of fluency scoring: it detects incomplete or off-script attempts, where the speaker deviates from the intended passage. When this happens the API lowers the overall scores and adds a score_issue_list[] entry:
See interpreting fidelity class for how to read and act on these signals.
Last updated