This API operation uses POST requests to submit and query spoken language evaluation tasks. It returns multi-dimensional AI evaluation results for analyzing pronunciation, fluency, and integrity in educational scenarios.-Smart Science and Education Content Platform(SSECP)-阿里云帮助中心

Warning

Spoken language evaluation is available only to customers on the whitelist. Calls from other customers will fail.

This API queries the evaluation results, generated by a large language model, for a spoken language recording. To retrieve the comments from these results, provide the application ID (app_id), recording ID (record_id), user ID (user_id), and warrant ID (warrant_id).

Submit an evaluation task

Request type: POST

Format: form-data

1.1 Request URL

https://aiservice.ssapi.cn/api/v1/oralEvaluation/classTaskSubmit

1.2 Request body

Name	Type	Required	Description
app_id	string	Yes	The application ID.
user_id	string	Yes	The user ID.
warrant_id	string	Yes	The ID of the authorization credential.
record_ids	list<string>	Yes	A list of record IDs.

curl -X POST 'https://aiservice.ssapi.cn/api/v1/oralEvaluation/classTaskSubmit' \
--form 'app_id="YOUR_APP_ID"' \
--form 'user_id="YOUR_USER_ID"' \
--form 'warrant_id="YOUR_WARRANT_ID"' \
--form 'record_ids="[\"record_id_1\",\"record_id_2\"]"'

1.3 Return values

Name	Type	Example	Description
success	boolean	true	Indicates whether the request was successful.
err_code	string	PARAMETER_ERROR_PARAM	The error code.
err_message	string	Invalid parameter	The error message.
data	Object
-task_id	string	TASK_20231012_ABCD1234	The ID returned for the task.

{
  "success": true,
  "data": {
    "task_id": "TASK_20231012_ABCD1234"
  }
}

{
  "success": false,
  "err_code": "PARAMETER_ERROR_PARAM",
  "err_message": "Some required parameters are missing from the request."
}

Query evaluation results

Request type: POST

Format: form-data

2.1 Request URL

https://aiservice.ssapi.cn/api/v1/oralEvaluation/classTaskQuery

1.2 Request Body

Name	Type	Required	Description
app_id	string	Yes	The application ID.
user_id	string	Yes	The user ID.
warrant_id	string	Yes	The ID of the authorization credential.
task_id	string	Yes	The task ID.

curl -X POST "https://aiservice.ssapi.cn/api/v1/oralEvaluation/classTaskQuery" \
     -F "app_id=your_app_id" \
     -F "user_id=your_user_id" \
     -F "warrant_id=your_warrant_id" \
     -F "task_id=task1"

1.3 Return value

Name	Type	Example	Description
success	boolean	true	Indicates whether the request was successful.
err_code	string	PARAMETER_ERROR_PARAM	The error code.
err_message	string	Invalid parameter	The error message.
data	Object
- process_type	string	finish	Process: Processing, Finish: Completed
- evaluation	Object
- - pronunciation_evaluation	string		The pronunciation evaluation.
- - improvement_suggestions	string		Suggestions for improvement.
- - fluency_evaluation	string		The fluency evaluation.
- - integrity_evaluation	string		The integrity evaluation.
- - audio_quality_evaluation	string		The audio quality evaluation.
- - overall_evaluation	string		The overall evaluation.

{
    "success": true,
    "data": {
        "process_type": "finish",
        "evaluation": {
            "pronunciation_evaluation": "Overall pronunciation is very accurate. Most words and phonemes scored near full marks.",
            "improvement_suggestions": "Maintain a stable volume.",
            "fluency_evaluation": "The reading is generally fluent, with occasional pauses in paragraph sections.",
            "integrity_evaluation": "All questions were read completely with no missing words.",
            "audio_quality_evaluation": "The audio quality is normal for most recordings, but the volume is low in one section.",
            "overall_evaluation": "Excellent overall performance, with scores near full marks on multiple questions."
        }
    }
}

{
  "success": false,
  "err_code": "PARAMETER_ERROR_PARAM",
  "err_message": "Some required parameters are missing from the request."
}