This document details the technical parameters and returned results for the English story retelling speech evaluation, which analyzes a test-taker's pronunciation, fluency, and content integrity from audio.-Smart Science and Education Content Platform(SSECP)-阿里云帮助中心

This document is a technical guide for developers who want to integrate the English story retelling speech evaluation feature.

Scenarios for this question type:

A test-taker listens to an audio clip and then retells the content.

Evaluation request parameters

Field	Type	Optional	Description
coreType	String	Required	en.retell.score indicates the English story retelling question type.
rank	int	Optional	The scoring system for the total score.
attachAudioUrl	int	Optional	Specifies whether to return the audio URL in the evaluation result. 0: Does not return the URL. 1: Returns the URL.
precision	double	Optional	Sets the scoring precision. Supported values are 0.1, 0.5, and 1. The default value is 1. If you set a value other than 0.1 or 0.5, it is processed as 1.
lm	array	Required	An array of dictionaries that contains the sample text for the retelling content. Note: The lm field is the lowercase form of LM.
grade	int	Optional	Specifies the academic level. Supported values are 1 and 2. The default value is 1. 1: Junior high school level (requires about 90% coverage of key points for a full score). 2: Senior high school level (requires about 80% coverage for a high score because the topics are more difficult).
phones	object	Optional	Specifies the pronunciation of words. If a word has multiple pronunciations, separate them with a pipe character (\|). You must use a space between each phoneme and between phonemes and the syllable separator (-). Example: "phones":{"directory":"d ih - 'r eh k - tr ih\|d ax - 'r eh k - t ax - r ih"}
points	array	Optional	Sets the key points of the answer. Each key point is a text object.
rateScale	float	Optional	The scoring leniency. The value ranges from 0.8 to 1.5. The default is 1.0. If the value is less than 0.8, it is processed as 0.8. If the value is greater than 1.5, it is processed as 1.5. This parameter acts as a multiplier. A higher value results in a higher score.

Parameter example

{
    "coreType": "en.retell.score",
    "rank": 100,
    "precision": 0.5,
    "attachAudioUrl":1,
    "lm": [
        {
            "text": "My aunt Judy was a single mother of fifty, working as a secretary. When doctors discovered she had a very serious heart disease, she didn't give in. She began studying medical reports and found an article in a magazine about a well known heart doctor, Dr. Michael Baker, of Houston, Texas. The article said Dr. Baker's fees were very high; Aunt Judy couldn't afford them. But could he tell her of someone whose fee she could pay? So Aunt Judy wrote to him. She simply listed her reasons for wanting to live: her three children, who would be independent in three or four more years, her little girl dream of travelling and seeing the world. There wasn't a word of self pity only warmth and humor and the joy of living. She mailed the letter, not really expecting an answer. A few days later, Aunt Judy rushed into my house, and read aloud a letter: your beautiful letter moved me very deeply. If you can come to Houston, there will be no charge for either the hospital or the operation. Michael Baker. That was seven years ago. Since then, Aunt Judy has been around the world. Her three children are happily married."
        }
    ],
    "points": [
        {
            "text": "My aunt Judy was a single mother of fifty, working as a secretary."
        },
        {
            "text": "When doctors discovered she had a very serious heart disease, she didn't give in."
        },
        {
            "text": "She began studying medical reports and found an article in a magazine about a well known heart doctor, Dr. Michael Baker, of Houston, Texas."
        },
        {
            "text": "The article said Dr. Baker's fees were very high; Aunt Judy couldn't afford them."
        },
        {
            "text": "But could he tell her of someone whose fee she could pay? So Aunt Judy wrote to him."
        },
        {
            "text": "She simply listed her reasons for wanting to live: her three children, who would be independent in three or four more years, her little girl dream of travelling and seeing the world."
        },
        {
            "text": "There wasn't a word of self pity only warmth and humor and the joy of living."
        },
        {
            "text": "She mailed the letter, not really expecting an answer."
        },
        {
            "text": "A few days later, Aunt Judy rushed into my house, and read aloud a letter: your beautiful letter moved me very deeply. If you can come to Houston, there will be no charge for either the hospital or the operation. Michael Baker."
        },
        {
            "text": "That was seven years ago. Since then, Aunt Judy has been around the world. Her three children are happily married."
        }
    ]
}

Description of returned results

Key	Type	Description	Usage suggestion
recordId	string	The unique ID of the audio file.	For reference.
tokenId	string	The unique ID of the user request.	For reference.
applicationId	string	The provided authorization account, which is the AppKey.	Internal parameter.
dtLastResponse	string	The timestamp of the cloud response.	Internal parameter.
eof	int	0: The response is not complete. More results will follow. 1: All results for this evaluation have been returned.	Internal parameter.
params	object	Echoes the evaluation request parameters sent by the client.
- app	object
- - applicationId	string	The provided authorization account, which is the AppKey.
- - userId	string	The user ID. A custom string to help locate and troubleshoot issues.
- - timestamp	string	The start time.
- - sig	string	The verification code.
- - clientId	string
- request	object	The request parameter section for scoring.
- audio	object	Number of audio parameter nodes per scoring request
result	object	The evaluation result.
- res	string	The name of the resource used for evaluating this question type.	Internal parameter.
- version	string	The engine version, including the release date.	Internal parameter.
- rank	int	The scoring system.	Internal parameter.
- precision	float	The scoring precision.	Internal parameter.
- pretime	int	The time taken by the cloud to call the Start API, in ms.	Internal parameter.
- systime	int	The total time taken for the entire evaluation process, in ms.	Internal parameter.
- delaytime	int	The time from when the cloud finishes feeding the audio to when the result is obtained, in ms.	Internal parameter.
- wavetime	int	The duration of the audio, in ms.	For reference.
- overall	float	The total score.	Recommended field.
- fluency	float	The fluency score. This reflects how smoothly the user speaks and is independent of the correct answer.	Recommended field.
- pron	float	The pronunciation score. This reflects pronunciation quality and is independent of the correct answer. It only relates to the accuracy of word pronunciation.	Recommended field.
- rhythm	float	The rhythm score. (Currently not in use).	Internal parameter.
- integrity	float	The integrity score.	Internal parameter.
- keypoints_hit	array	An array that corresponds to the hit status of each key point, in the same order as the points field. This field is not returned if the points field is absent.	Recommended field.
- fake_words	object	This field is returned only for out-of-vocabulary (OOV) words. To evaluate OOV words, you can pass their phonetic transcriptions using refText.
- -char	string
- info	object
- - snr	float	The signal-to-noise ratio (SNR). A higher value indicates clearer audio. The range is 0 to 40 dB. If this parameter affects the score, a corresponding tipId value is set.	For reference.
- - clip	float	Indicates audio clipping due to high volume. The range is 0 to 1. If this parameter affects the score, a corresponding tipId value is set.	Internal parameter.
- - volume	int	The recording volume. The range is 0 to 180 dB.	For reference.
- - tipId	int	The audio quality. For more information, see tipId message descriptions.	Recommended field.

Note: Fields in the returned result that are not described in this document are internal parameters and can be ignored.

Result example

Dimension	Description	Details
overall	Total score	The evaluation score for the question type.
pron	Pronunciation score
fluency	Fluency
keypoints_hit	Hit rate for each key point.	See the description for the corresponding question type.

Returned result on evaluation failure

If the result structure in the response is empty, the evaluation failed. You can retrieve the errId and error from the response. Use the corresponding error code to handle the failure.

Error codes

For more information, see Evaluation error codes.