> For the complete documentation index, see [llms.txt](https://api-docs.speechace.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.speechace.com/api-reference/score-task.md). # Score Task {% hint style="info" %} This features requires a Premium Subscription\ **Run in Postman:** [Score Task](https://docs.speechace.com/#07bbedef-8c33-48dc-b84f-6e94ebb3fc80) {% endhint %} The **Score Task** API scores **task achievement** — how completely a spoken (or written) response fulfills a specific task, independent of its language quality. It complements the language scores from [Score Speech](/api-reference/score-speech.md): the task score reflects *what* the speaker communicated, while the language scores reflect *how well* they said it. The task score is continuous, so a partial response earns a partial score. {% hint style="info" %} Score Task is available by invitation. Email to request access. {% endhint %} ### Task types Choose a task type with the `task_type` query parameter. Each type has its own inputs and score range:
Task TypeInputsOutputs
describe-imagetask_context: A model description of the image which is presented to the speaker.
Max length: 1024 chars.		Task score on scale of 0-5.
retell-lecturetask_context: A model summary of the lecture which is presented to the speaker.
Max length: 1024 chars.		Task score on scale of 0-5.
answer-questiontask-question: The question presented to the user.Task score on scale of 0-1 where 0 is incorrect and 1 is correct.
### Audio or text, with or without language scores * **`user_audio_file` or `user_audio_text`** — submit the response as audio, or as a text transcript you already have. With `user_audio_text` the task score is returned but speech scoring is skipped. * **`include_speech_score`** — set `1` to also score pronunciation, fluency, grammar, vocabulary, and coherence (as in [Score Speech](/api-reference/score-speech.md)); set `0` for the task score only. It is always `0` when `user_audio_text` is used. All task types are available in English (`en-us`, `en-gb`), Spanish (`es-es`, `es-mx`), and French (`fr-fr`, `fr-ca`). ### Request Format The endpoint you use depends on the [region](/getting-started/api-regions-and-endpoints.md) of your subscription. For example, for US West the endpoint is . `POST` [`https://api.speechace.co/api/scoring/task/v9/json`](https://api.speechace.co/api/scoring/task/v9/json) ### Query Parameters
ParameterTypeDescription
keyStringAPI key issued by Speechace.
dialectStringThis is the dialect in which the speaker will be assessed. Supported values are: en-us, en-gb, fr-fr, fr-ca, es-es, es-mx.
user_idStringOptional: A unique anonymized identifier (generated by your applications) for the end-user who spoke the audio.
task_typeString

The task_type to score. Supported types are:

  • describe-image
  • retell-lecture
  • answer-question.
### Request Body
ParameterTypeDescription
task_contextString

The context or model or model answer for the task presented to the speaker.

Used in the following task-types:

  • describe-image: a model description of the image
  • retell-lecture: a model description of the lecture

This must be provided in the same language as the one being assessed.

task_questionString

The task question presented to the speaker, used in task-type = answer-question.

This must be provided in the same language as the one being assessed.

user_audio_fileFilefile with user audio (wav, mp3, m4a, webm, ogg, aiff)
include_speech_scoreString
  • Set to 1, to include scoring other aspects of the speech: Pronunciation, Fluency, Grammar, Vocab, Coherence.
  • Set to 0 if you only want to receive the task score only.
user_audio_textString

A text transcript of the speaker's response.

  • Use this field instead of user_audio_file if you already have a transcript of the user's response and do not wish to re-transcribe an audio.
  • Note: In this case, you will only be able to receive an overall task_score.
### Request Examples
ExampleRequest ParametersWhen to use
A. Describe imagetask_type=describe-image
task_context="<model description of the image>"
user_audio_file=answer.wav
include_speech_score="1"		Score how well the speaker describes a presented image or chart (0–5).
B. Re-tell lecturetask_type=retell-lecture
task_context="<model summary of the lecture>"
user_audio_file=answer.wav
include_speech_score="1"		Score a spoken summary of a short lecture (0–5).
C. Answer questiontask_type=answer-question
task_question="<the question asked>"
user_audio_file=answer.wav		Score a short spoken answer as correct or incorrect (0 or 1).
{% hint style="info" %} To score a written response instead of audio, replace `user_audio_file` with `user_audio_text="<transcript>"`. Only the task score is returned in that case. {% endhint %} ### Response Examples The overall task-achievement score is `task_score.score`; when `include_speech_score=1`, the language scores appear under `speech_score` exactly as in [Score Speech](/api-reference/score-speech.md). {% tabs %} {% tab title="A. Describe image" %} {% code overflow="wrap" lineNumbers="true" expandable="true" %} ```json { "status": "success", "task_score": { "type": "describe-image", "version": "0.2", "score": 5, "score_explanation": "The response provides a clear and accurate description of the data presented in the image, including the specific percentages for each year and the overall trend of continuous decrease in farm labor engagement. The information is well-organized and effectively communicates the key points of the bar chart.", "transcript": "This bar graph shows the percent of the U.S. workforce engaged in farm labor from 1840 to 1900. Starting in 1840 the figure was about 70%. It then falls gradually to around 60% in 1860, and down to about 50% in 1880. By 1900 it had decreased to under 40%. Overall there is a continuous decrease in farm labor engagement." }, "quota_remaining": -1, "speech_score": { "transcript": "This bar graph shows the percent of the U.S. workforce engaged in farm labor from 1840 to 1900. Starting in 1840 the figure was about 70%. It then falls gradually to around 60% in 1860, and down to about 50% in 1880. By 1900 it had decreased to under 40%. Overall there is a continuous decrease in farm labor engagement.", "word_score_list": [ { "word": "This", "quality_score": 100, "quality_class": "pass", "phone_score_list": [ { "phone": "dh", "stress_level": null, "extent": [ 5, 17 ], "quality_score": 100, "word_extent": [ 0, 2 ], "sound_most_like": "dh" }, { "phone": "ih", "stress_level": 1, "extent": [ 17, 23 ], "quality_score": 99.5, "stress_score": 100, "predicted_stress_level": 1, "word_extent": [ 2, 3 ], "sound_most_like": "ih" }, { "phone": "s", "stress_level": null, "extent": [ 23, 32 ], "quality_score": 99.66666666666667, "word_extent": [ 3, 4 ], "sound_most_like": "s" } ], "syllable_score_list": [ { "phone_count": 3, "stress_level": 1, "letters": "this", "quality_score": 100, "stress_score": 100, "predicted_stress_level": 1, "extent": [ 5, 32 ] } ] }, "... (69 more)" ], "ielts_score": { "pronunciation": 8.5, "fluency": 8, "grammar": 6.5, "coherence": 5.5, "vocab": 6, "overall": 7 }, "pte_score": { "pronunciation": 90, "fluency": 85, "grammar": 62, "coherence": 42, "vocab": 52, "overall": 69 }, "speechace_score": { "pronunciation": 97, "fluency": 89, "grammar": 74, "coherence": 61, "vocab": 68, "overall": 79 }, "toeic_score": { "pronunciation": 190, "fluency": 180, "grammar": 140, "coherence": 110, "vocab": 120, "overall": 160 }, "cefr_score": { "pronunciation": "C2", "fluency": "C1+", "grammar": "B1+", "coherence": "A2+", "vocab": "B1", "overall": "B2" }, "fluency": { "segment_metrics_list": [ { "segment": [ 0, 20 ], "duration": 5.85, "articulation_length": 5.61, "syllable_count": 29, "correct_syllable_count": 29, "correct_word_count": 20, "word_count": 20, "speech_rate": 4.957264957264957, "articulation_rate": 5.16934046345811, "syllable_correct_per_minute": 297.43589743589746, "word_correct_per_minute": 205.12820512820514, "all_pause_count": 1, "all_pause_duration": 0.24, "mean_length_run": 5.61, "max_length_run": 5.61, "all_pause_list": [ [ 566, 590 ] ], "ielts_score": { "pronunciation": 9, "fluency": 8, "grammar": 5.5, "coherence": 6, "vocab": 6.5 }, "pte_score": { "pronunciation": 90, "fluency": 83, "grammar": 40, "coherence": 50, "vocab": 57 }, "speechace_score": { "pronunciation": 99, "fluency": 88, "grammar": 60, "coherence": 67, "vocab": 71 }, "toeic_score": { "pronunciation": 200, "fluency": 180, "grammar": 110, "coherence": 120, "vocab": 140 }, "cefr_score": { "pronunciation": "C2", "fluency": "C1+", "grammar": "A2+", "coherence": "B1", "vocab": "B1+" } }, "... (4 more)" ], "overall_metrics": { "segment": [ 0, 70 ], "duration": 21.81, "articulation_length": 19.75, "syllable_count": 115, "correct_syllable_count": 111, "correct_word_count": 67, "word_count": 70, "speech_rate": 5.27281063732233, "articulation_rate": 5.822784810126582, "syllable_correct_per_minute": 305.3645116918845, "word_correct_per_minute": 184.31911966987622, "all_pause_count": 7, "all_pause_duration": 2.06, "mean_length_run": 2.46875, "max_length_run": 5.61, "all_pause_list": [ [ 566, 614 ], [ 893, 935 ], "... (5 more)" ] }, "fluency_version": "0.7", "ielts_subscore_version": "0.4" }, "asr_version": "0.17" }, "version": "9.17" } ``` {% endcode %} {% endtab %} {% tab title="B. Re-tell lecture" %} {% code overflow="wrap" lineNumbers="true" expandable="true" %} ```json { "status": "success", "task_score": { "type": "retell-lecture", "version": "0.2", "score": 5, "transcript": "The lecture was about ecosystems. Ecology is the study of living organisms in an environment. An ecosystem has two factors. The first is biotic, the living things, which include producers, herbivores, carnivores, omnivores and detritivores. The second is abiotic, the non-living things in the environment." }, "quota_remaining": -1, "speech_score": { "transcript": "The lecture was about ecosystems. Ecology is the study of living organisms in an environment. An ecosystem has two factors. The first is biotic, the living things, which include producers, herbivores, carnivores, omnivores and detritivores. The second is abiotic, the non-living things in the environment.", "word_score_list": [ { "word": "The", "quality_score": 99, "quality_class": "pass", "phone_score_list": [ { "phone": "dh", "stress_level": null, "extent": [ 8, 14 ], "quality_score": 98, "word_extent": [ 0, 2 ], "sound_most_like": "dh" }, { "phone": "ah", "stress_level": 0, "extent": [ 14, 17 ], "quality_score": 100, "stress_score": 100, "predicted_stress_level": 0, "word_extent": [ 2, 3 ], "sound_most_like": "ah" } ], "syllable_score_list": [ { "phone_count": 2, "stress_level": 0, "letters": "the", "quality_score": 99, "stress_score": 100, "predicted_stress_level": 0, "extent": [ 8, 17 ] } ] }, "... (44 more)" ], "ielts_score": { "pronunciation": 8.5, "fluency": 8.5, "grammar": 6, "coherence": 7, "vocab": 7, "overall": 7.5 }, "pte_score": { "pronunciation": 90, "fluency": 90, "grammar": 47, "coherence": 67, "vocab": 66, "overall": 73 }, "speechace_score": { "pronunciation": 97, "fluency": 96, "grammar": 64, "coherence": 78, "vocab": 77, "overall": 81 }, "toeic_score": { "pronunciation": 190, "fluency": 190, "grammar": 120, "coherence": 160, "vocab": 160, "overall": 170 }, "cefr_score": { "pronunciation": "C2", "fluency": "C2", "grammar": "B1", "coherence": "B2", "vocab": "B2", "overall": "C1" }, "fluency": { "segment_metrics_list": [ { "segment": [ 0, 5 ], "duration": 1.92, "articulation_length": 1.68, "syllable_count": 10, "correct_syllable_count": 10, "correct_word_count": 5, "word_count": 5, "speech_rate": 5.208333333333334, "articulation_rate": 5.9523809523809526, "syllable_correct_per_minute": 312.5, "word_correct_per_minute": 156.25, "all_pause_count": 2, "all_pause_duration": 0.24, "mean_length_run": 0.84, "max_length_run": 0.87, "all_pause_list": [ [ 95, 98 ], [ 179, 200 ] ], "ielts_score": { "pronunciation": 9, "fluency": 8, "grammar": 4.5, "coherence": 4, "vocab": 4 }, "pte_score": { "pronunciation": 90, "fluency": 83, "grammar": 23, "coherence": 20, "vocab": 20 }, "speechace_score": { "pronunciation": 99, "fluency": 88, "grammar": 49, "coherence": 44, "vocab": 44 }, "toeic_score": { "pronunciation": 200, "fluency": 180, "grammar": 80, "coherence": 50, "vocab": 50 }, "cefr_score": { "pronunciation": "C2", "fluency": "C1+", "grammar": "A1+", "coherence": "A1", "vocab": "A1" } }, "... (4 more)" ], "overall_metrics": { "segment": [ 0, 45 ], "duration": 18.54, "articulation_length": 15.75, "syllable_count": 89, "correct_syllable_count": 82, "correct_word_count": 44, "word_count": 45, "speech_rate": 4.800431499460626, "articulation_rate": 5.650793650793651, "syllable_correct_per_minute": 265.37216828478967, "word_correct_per_minute": 142.3948220064725, "all_pause_count": 11, "all_pause_duration": 2.79, "mean_length_run": 1.3125, "max_length_run": 3, "all_pause_list": [ [ 95, 98 ], [ 179, 221 ], "... (9 more)" ] }, "fluency_version": "0.7", "ielts_subscore_version": "0.4" }, "asr_version": "0.17" }, "version": "9.17" } ``` {% endcode %} {% endtab %} {% tab title="C. Answer question" %} {% code overflow="wrap" lineNumbers="true" expandable="true" %} ```json { "status": "success", "task_score": { "type": "answer-question", "version": "0.2", "score": 1, "transcript": "Jupiter." }, "quota_remaining": -1, "speech_score": { "transcript": "Jupiter.", "word_score_list": [ { "word": "Jupiter", "quality_score": 99, "quality_class": "pass", "phone_score_list": [ { "phone": "jh", "stress_level": null, "extent": [ 8, 17 ], "quality_score": 98.66666666666667, "word_extent": [ 0, 1 ], "sound_most_like": "jh" }, { "phone": "uw", "stress_level": 1, "extent": [ 17, 23 ], "quality_score": 94.5, "stress_score": 100, "predicted_stress_level": 1, "word_extent": [ 1, 2 ], "sound_most_like": "uw" }, { "phone": "p", "stress_level": null, "extent": [ 23, 35 ], "quality_score": 100, "word_extent": [ 2, 3 ], "sound_most_like": "p" }, { "phone": "ih", "stress_level": 0, "extent": [ 35, 38 ], "quality_score": 100, "stress_score": 100, "predicted_stress_level": 0, "word_extent": [ 3, 4 ], "sound_most_like": "ih" }, { "phone": "t", "stress_level": null, "extent": [ 38, 41 ], "quality_score": 99, "word_extent": [ 4, 5 ], "sound_most_like": "t" }, { "phone": "er", "stress_level": 0, "extent": [ 41, 62 ], "quality_score": 100, "stress_score": 100, "predicted_stress_level": 0, "word_extent": [ 5, 7 ], "sound_most_like": "er" } ], "ending_punctuation": ".", "syllable_score_list": [ { "phone_count": 2, "stress_level": 1, "letters": "ju", "quality_score": 97, "stress_score": 100, "predicted_stress_level": 1, "extent": [ 8, 23 ] }, { "phone_count": 2, "stress_level": 0, "letters": "pi", "quality_score": 100, "stress_score": 100, "predicted_stress_level": 0, "extent": [ 23, 38 ] }, { "phone_count": 2, "stress_level": 0, "letters": "ter", "quality_score": 100, "stress_score": 100, "predicted_stress_level": 0, "extent": [ 38, 62 ] } ] } ], "ielts_score": { "pronunciation": 9, "fluency": 8, "grammar": 4, "coherence": 4, "vocab": 4, "overall": 0 }, "pte_score": { "pronunciation": 90, "fluency": 83, "grammar": 20, "coherence": 20, "vocab": 20, "overall": 10 }, "speechace_score": { "pronunciation": 99, "fluency": 88, "grammar": 44, "coherence": 44, "vocab": 44, "overall": 0 }, "toeic_score": { "pronunciation": 200, "fluency": 180, "grammar": 50, "coherence": 50, "vocab": 50, "overall": 0 }, "cefr_score": { "pronunciation": "C2", "fluency": "C1+", "grammar": "A1", "coherence": "A1", "vocab": "A1", "overall": "A0" }, "score_issue_list": [ { "source": "overall", "status": "warning", "short_message": "response_too_short", "detail_message": "The response is less than 20 words." } ], "fluency": { "segment_metrics_list": [ { "segment": [ 0, 1 ], "duration": 0.54, "articulation_length": 0.54, "syllable_count": 3, "correct_syllable_count": 3, "correct_word_count": 1, "word_count": 1, "speech_rate": 5.555555555555555, "articulation_rate": 5.555555555555555, "syllable_correct_per_minute": 333.3333333333333, "word_correct_per_minute": 111.1111111111111, "all_pause_count": 0, "all_pause_duration": 0, "mean_length_run": 0.54, "max_length_run": 0.54, "all_pause_list": [], "ielts_score": { "pronunciation": 9, "fluency": 8, "grammar": 4, "coherence": 4, "vocab": 4 }, "pte_score": { "pronunciation": 90, "fluency": 83, "grammar": 20, "coherence": 20, "vocab": 20 }, "speechace_score": { "pronunciation": 99, "fluency": 88, "grammar": 44, "coherence": 44, "vocab": 44 }, "toeic_score": { "pronunciation": 200, "fluency": 180, "grammar": 50, "coherence": 50, "vocab": 50 }, "cefr_score": { "pronunciation": "C2", "fluency": "C1+", "grammar": "A1", "coherence": "A1", "vocab": "A1" } } ], "overall_metrics": { "segment": [ 0, 1 ], "duration": 0.54, "articulation_length": 0.54, "syllable_count": 3, "correct_syllable_count": 3, "correct_word_count": 1, "word_count": 1, "speech_rate": 5.555555555555555, "articulation_rate": 5.555555555555555, "syllable_correct_per_minute": 333.3333333333333, "word_correct_per_minute": 111.1111111111111, "all_pause_count": 0, "all_pause_duration": 0, "mean_length_run": 0.54, "max_length_run": 0.54, "all_pause_list": [] }, "fluency_version": "0.7", "ielts_subscore_version": "0.4" }, "asr_version": "0.17" }, "version": "9.17" } ``` {% endcode %} {% endtab %} {% endtabs %} ### Response fields * `task_score.type` — the `task_type` that was scored. * `task_score.score` — the task-achievement score (0–5 for describe-image and retell-lecture; 0 or 1 for answer-question). * `task_score.transcript` — the transcript used to score the task. * `speech_score` — present when `include_speech_score=1`; pronunciation, fluency, grammar, vocabulary, and coherence, interpreted exactly as in [Score Speech](/api-reference/score-speech.md). {% hint style="info" %} **`task_context` / `task_question` vs. `relevance_context`.** [Relevance](/api-reference/score-speech.md) is binary and high-level — it judges only whether a response is on-topic (`TRUE`/`FALSE`). Task achievement is more nuanced — it scores *how well* the response addresses the specifics of the task. Use relevance for open questions with no single right answer; use task achievement when a specific, complete answer is expected (e.g. "What does this business chart tell us?"). {% endhint %}