> 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 Type	Inputs	Outputs
describe-image	`task_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-lecture	`task_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-question	`task-question`: The question presented to the user.	Task score on scale of 0-1 where 0 is incorrect and 1 is correct.

{% hint style="info" %} **Model versions.** Each response carries the scoring model version in `task_score.version`. `describe-image` and `retell-lecture` run on model **`0.3`**, which returns a [`score_explanation`](#score-explanation) with every score. `answer-question` runs on model `0.2` and does not return one. {% endhint %} ### 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

Parameter	Type	Description
key	String	API key issued by Speechace.
dialect	String	This 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_id	String	Optional: A unique anonymized identifier (generated by your applications) for the end-user who spoke the audio.
task_type	String	The task_type to score. Supported types are: describe-image retell-lecture answer-question.

### Request Body

Parameter	Type	Description
task_context	String	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_question	String	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_file	File	file with user audio (wav, mp3, m4a, webm, ogg, aiff)
include_speech_score	String	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_text	String	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.`

### Authoring the task prompt The task score measures how completely the response covers the prompt you supply. `task_context` and `task_question` are therefore not labels — they are the rubric the model scores against, and their quality sets the ceiling on how meaningful the score is. #### answer-question `task_question` must have exactly one objective, checkable answer, because the score is binary.

Do	Example
Use a closed factual question	What is the capital of France?
Keep it self-contained	How many days are there in a leap year? — no reference to an unseen prompt or image.
Accept paraphrase, not wording	The model scores the answer's content, so "Paris" and "The capital is Paris" both score 1.
Avoid	Opinion or open questions (What do you think about remote work?), multi-part questions, and questions whose answer depends on material the model cannot see.

For open-ended questions with no single right answer, use the relevance check on [Score Speech](/api-reference/score-speech.md) instead — it judges only whether the response is on topic. #### describe-image and retell-lecture For both types `task_context` is a **model answer**: write the response that would itself score 5. The model compares the candidate's response against it, element by element, so the context should contain exactly the things you expect a strong candidate to say — and nothing more. Structure it in four parts, which map onto what the 0–5 bands reward:

#	Part	Why it matters
1	Open by naming what the stimulus is and what it shows, with units or time range.	Gives the model the frame; a response that misses it is recognisably incomplete.
2	The key features, most salient first, each with its value or label.	This is what coverage is measured against. Bands 1–3 are largely a question of how many of these the response names.
3	At least one explicit relationship — a comparison, ranking, or direction of change.	Bands 4 and 5 require the response to connect features, not just list them. If your context never states a relationship, nothing in it rewards one.
4	A closing `Overall…` takeaway.	Band 5 requires a supported conclusion. Without one in the context, the top band is unreachable in practice.

**Keep it to what a candidate can actually say.** In PTE Speaking the candidate has about 40 seconds, which is roughly 80–100 spoken words. Coverage is measured against your context as a whole, so every element you add that a candidate has no time to produce dilutes the share they can realistically reach. As a working budget:

Task type	task_context	Re-read beyond	Hard limit
describe-image	80–110 words (roughly 500–700 characters)	700 characters	1024 characters
retell-lecture	90–140 words (roughly 550–900 characters)	900 characters	1024 characters

`retell-lecture` gets the wider budget because its context is a transcript or close summary of a 1-to-1.5 minute talk, which carries connective prose an image description does not. The candidate still has only about 40 seconds, so the extra room is for the lecturer's argument, not for more facts. The 1024-character limit is a ceiling, not a target. Past the "re-read beyond" column, go back through the context and cut anything a strong candidate would not say in 40 seconds. Length on its own does not set the score — *which* elements the context contains does. Because coverage is proportional, trimming a context makes each remaining element count for more, so a response can score lower against a shorter context if the trim removed elements it happened to cover. Edit for the right elements, not for a character count. {% hint style="warning" %} **Do not** pad `task_context` with axis labels, legend colours, or an exhaustive dump of every data point. Those are details a candidate will not mention in 40 seconds, and including them lowers the coverage ratio for every response you score. {% endhint %} **A worked `describe-image` context** — 89 words, four parts, one relationship, one conclusion: ``` The bar chart compares how five countries generated their electricity in 2020, split between renewable and fossil-fuel sources. The clearest feature is that Norway produced almost all of its electricity from renewables, far more than any other country. In contrast, Poland and India relied overwhelmingly on fossil fuels. Germany and the UK sat in the middle, each with a fairly even split. Overall, the chart shows a strong divide between a few renewable leaders and the fossil-fuel-dependent countries, suggesting that national energy policy, not just resources, drives the mix. ``` **A worked `retell-lecture` context** — the same four parts applied to a transcript of the talk: the lecturer's thesis, the supporting points in the order they were made, the link between them, and the conclusion drawn. This is the context behind response example **B** below: ``` Ecology is the study of how living organisms interact with each other in their environment, focusing on biotic and abiotic factors. Biotic factors refer to living organisms that affect an ecosystem, while abiotic factors involve non-living things that alter it. For example, in an African savanna, biotic factors include grasses, plants, and animals, while abiotic factors include weather, climate, and forest fires. Ecology is not just about living organisms, as we are all part of an environment with abiotic factors like air, temperature, bacteria, and plants. Living forms can interact with each other through abiotic factors, such as plants producing oxygen or carbon dioxide that the plant can fix and grow. This interaction is essential for maintaining a healthy ecosystem and promoting the growth and development of living forms. ``` At 129 words and 838 characters this sits inside the `retell-lecture` budget, and it shows why that budget is wider: the second paragraph is mostly connective prose restating the biotic/abiotic distinction rather than adding new elements to cover. The response in example B names the two factor types and the biotic sub-categories but never states how they interact, and never reaches the conclusion — which is what holds it at 3 of 5. {% hint style="info" %} `task_context` and `task_question` must be in the same language as the `dialect` being assessed. {% endhint %} ### Request Examples

Example	Request Parameters	When to use
A. Describe image	`task_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 lecture	`task_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 question	`task_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=""`. 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.3", "score": 5, "score_explanation": "The response accurately describes all key features of the image, including the standout performance of Norway, the heavy reliance on fossil fuels in Poland and India, and the balanced approach in Germany and the UK. It also identifies the major trend of a divide between renewable and fossil-fuel-based electricity generation and offers a logical conclusion that policy, rather than natural resources, influences the energy mix. The response is concise but comprehensive, with no missing elements or inaccuracies.", "transcript": "The bar chart compares electricity generation in five countries in 2020, renewable against fossil fuel. Norway is the clear outlier, producing almost all of its electricity from renewables, while Poland and India rely overwhelmingly on fossil fuels. Germany and the UK sit between them with a fairly even split. Overall the chart shows a sharp divide between a few renewable leaders and the fossil-dependent countries, which suggests policy rather than natural resources drives the mix." }, "speech_score" : "...", "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.3", "score": 3, "score_explanation": "The response covers the main idea of the lecture by introducing ecology and the two types of factors (biotic and abiotic). It provides some supporting details, such as examples of biotic components (producers, herbivores, etc.). However, it does not convey the relationships between the main ideas or explain how biotic and abiotic factors interact to maintain a healthy ecosystem, which was a key point in the lecture. Additionally, it omits the conclusion or the significance of these interactions. The response lacks depth and connection between ideas, which limits it to a score of 3.", "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." }, "speech_score" : "...", "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." }, "speech_score": "...", "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.version` — the scoring model version. `describe-image` and `retell-lecture` are on `0.3`; `answer-question` is on `0.2`. Pin nothing to this value; it changes when a model is updated. * `task_score.score_explanation` — a short rationale for the score. See [below](#score-explanation). * `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). #### score explanation `task_score.score_explanation` is a short natural-language rationale for the score. It names the elements of `task_context` the response covered, what it missed, and which of those omissions set the band — so it can be shown to a learner as feedback, logged for review, or used to spot-check a score you disagree with.

Task type	Model	score_explanation
describe-image	`0.3`	Returned on every scored response.
retell-lecture	`0.3`	Returned on every scored response.
answer-question	`0.2`	Not returned.

Two real responses to the same `describe-image` context — the worked example above — showing a full-coverage answer and a thin one: {% tabs %} {% tab title="Task Score: 5/5" %} {% code overflow="wrap" lineNumbers="true" expandable="true" %} ```json { "status": "success", "task_score": { "type": "describe-image", "version": "0.3", "score": 5, "score_explanation": "The response accurately describes all key features of the image, including the standout performance of Norway, the heavy reliance on fossil fuels in Poland and India, and the balanced approach in Germany and the UK. It also identifies the major trend of a divide between renewable and fossil-fuel-based electricity generation and offers a logical conclusion that policy, rather than natural resources, influences the energy mix. The response is concise but comprehensive, with no missing elements or inaccuracies.", "transcript": "The bar chart compares electricity generation in five countries in 2020, renewable against fossil fuel. Norway is the clear outlier, producing almost all of its electricity from renewables, while Poland and India rely overwhelmingly on fossil fuels. Germany and the UK sit between them with a fairly even split. Overall the chart shows a sharp divide between a few renewable leaders and the fossil-dependent countries, which suggests policy rather than natural resources drives the mix." }, "speech_score" : "...", "version": "9.17" } ``` {% endcode %} {% endtab %} {% tab title="Task Score: 2/5" %} {% code overflow="wrap" lineNumbers="true" expandable="true" %} ```json { "status": "success", "task_score": { "type": "describe-image", "version": "0.3", "score": 2, "score_explanation": "The response mentions one key feature (Norway's use of renewable energy) but fails to describe other important elements of the chart, such as the roles of Poland, India, Germany, and the UK. It does not establish any relationships between the data points or identify trends. The response is very brief and lacks a conclusion or deeper analysis, which limits it to a low score.", "transcript": "It's a bar chart about electricity in different countries. Norway uses the most renewable energy." }, "speech_score" : "...", "version": "9.17" } ``` {% endcode %} {% endtab %} {% endtabs %} {% hint style="warning" %} `score_explanation` is generated prose, not a stable contract. Its wording varies between calls on the same input, so treat it as human-readable feedback — never parse it, key logic off it, or diff it between runs. The numeric `score` is the field to store and compare. {% endhint %} {% 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 %}