Q&A pair

Updated at:

This document provides technical details about the English Q&A speech assessment for developers integrating this feature.

Scenarios for this question type

  • A scenario is described, followed by a question about the scenario. The user answers the question based on the information they heard.

  • The difference between a Q&A pair and an extended multiple-choice question is that an extended multiple-choice question provides options for a semi-open-ended answer. In contrast, a Q&A pair provides no options. The user must answer the question based on the scenario they heard.

Parameter description

Field

Type

Optional

Description

coreType

String

Required

en.pqan.score indicates the English Q&A question type.

rank

int

Optional

The scoring system for the total score.

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, the system uses 1.

quest_ans

String

Optional

The text of the question.

key

array

Required

key includes possible expressions of key points. Key points significantly affect the score.

para

String

Optional

The text that describes the scenario.

lm

array

Required

Sets possible correct answers. Each text in lm represents a correct answer. Note: The lm field is the lowercase form of Language Model (LM).

phones

String

Optional

Specifies the pronunciation of a word. If a word has multiple pronunciations, separate them with a pipe character (|). 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"};

attachAudioUrl

int

Optional

Specifies whether to return the audio URL in the assessment result.
0: Do not return.
1: Return.

unkey

Array

Optional

unkey represents incorrect answers. If the user's pronunciation matches any of these incorrect answers, the score is significantly lowered.

rateScale

float

Optional

The scoring leniency. The range is 0.8 to 1.5, and the default is 1.0. If the value is less than 0.8, it is treated as 0.8. If the value is greater than 1.5, it is treated as 1.5. This parameter acts as a multiplier. A higher value results in a higher score.

Parameter example

{
      "coreType": "en.pqan.score",
      "attachAudioUrl":1,
      "para": "It's unbelievable. He looks stupid, but in fact, he is such a great and humorous actor. What's going on? You know what? Mr. Bean graduate from Oxford University. Exactly, I am also very crazy about Mr. Bean. He is really a funny guy and he does have a great sense of humor. In my eyes, he is a genius. I really admire him. I couldn't agree more, and it's his giftedness and hard works that make him succeed. After seeing his interesting films, I feel cheerful and excited, he brings happiness to us. Yes, I hope we can bring laughter to people too, just like Mr. Bean. I can't wait to see more his films after class. But first thing first, let's get our homework done.",
            "quest_ans": "What makes Mr. Bean so successful?",
            "lm": [
                {
                    "text": "It's his giftedness and hard works that make him succeed."
                },
                {
                    "text": "his talents and hard works."
                },
                {
                    "text": "is talent and hard work."
                },
                {
                    "text": "His giftedness and hard works."
                },
                {
                    "text": "His giftedness and hard works makes Mr. Bean so successful."
                },
                {
                    "text": "His talent and hard work makes him successful."
                },
                {
                    "text": "His body language is so funny, he makes people laugh, feel happy and relaxed."
                },
                {
                    "text": "Hard work and giftedness."
                },
                {
                    "text": "His giftedness and hard work."
                },
                {
                    "text": "his talents and he is very hard working."
                },
                {
                    "text": "His gift and hard works."
                }
            ],
            "key": [    
                {
                    "text": "giftedness hard work"
                },
                {
                    "text": "gift hard work"
                },
                {
                    "text": "talent hard work"
                }
            ] , 
            "unkey":[
                {
                    "text":"no"
                }
            ]
        }


Response example

{
    "tokenId": "612f300a88bf5b0000010001",
    "applicationId": "a148",
    "audioUrl": "http:\/\/files.cloud.ssapi.cn:8080\/a148\/11ec0af8d87bb60e915ba14862618bc6",
    "connect": {
        "param": {
            "app": {
                "timestamp": "1630482442",
                "applicationId": "a148",
                "sig": "b49047a625766bce5467fb292c3902b7d8373452"
            },
            "sdk": {
                "os": "6.2(9200)1",
                "product": "",
                "source": 7,
                "protocol": 1,
                "os_version": "6.2(9200)",
                "arch": "586",
                "version": 16778752
            }
        },
        "cmd": "connect"
    },
    "params": {
        "app": {
            "timestamp": "1630482442",
            "userId": "ssound_text",
            "sig": "b49047a625766bce5467fb292c3902b7d8373452",
            "connect_id": "612f300a88bf5b0000030002",
            "clientId": "",
            "applicationId": "a148"
        },
        "audio": {
            "sampleBytes": 2,
            "audioType": "ogg",
            "sampleRate": 16000,
            "channel": 1
        },
        "request": {
            "quest_ans": "What makes Mr. Bean so successful?",
            "tokenId": "612f300a88bf5b0000010001",
            "para": "It's unbelievable. He looks stupid, but in fact, he is such a great and humorous actor. What's going on? You know what? Mr. Bean graduate from Oxford University. Exactly, I am also very crazy about Mr. Bean. He is really a funny guy and he does have a great sense of humor. In my eyes, he is a genius. I really admire him. I couldn't agree more, and it's his giftedness and hard works that make him succeed. After seeing his interesting films, I feel cheerful and excited, he brings happiness to us. Yes, I hope we can bring laughter to people too, just like Mr. Bean. I can't wait to see more his films after class. But first thing first, let's get our homework done.",
            "coreType": "en.pqan.score",
            "attachAudioUrl": 1,
            "request_id": "612f300a88bf5b0000020001",
            "key": [
                {
                    "text": "giftedness hard work"
                },
                {
                    "text": "gift hard work"
                },
                {
                    "text": "talent hard work"
                }
            ],
            "lm": [
                {
                    "text": "It's his giftedness and hard works that make him succeed."
                },
                {
                    "text": "his talents and hard works."
                },
                {
                    "text": "is talent and hard work."
                },
                {
                    "text": "His giftedness and hard works."
                },
                {
                    "text": "His giftedness and hard works makes Mr. Bean so successful."
                },
                {
                    "text": "His talent and hard work makes him successful."
                },
                {
                    "text": "His body language is so funny, he makes people laugh, feel happy and relaxed."
                },
                {
                    "text": "Hard work and giftedness."
                },
                {
                    "text": "His giftedness and hard work."
                },
                {
                    "text": "his talents and he is very hard working."
                },
                {
                    "text": "His gift and hard works."
                }
            ]
        }
    },
    "recordId": "11ec0af8d87bb60e915ba14862618bc6",
    "eof": 1,
    "result": {
        "overall": 99,
        "wavetime": 4990,
        "precision": 1,
        "pron": 90,
        "systime": 1521,
        "res": "eng.pqan.mfcc.0.1",
        "version": "0.0.80.2021.8.27.04:29:39",
        "fake_words": {
            "char": "giftedness"
        },
        "info": {
            "tipId": 0,
            "clip": 0,
            "snr": 17.190611,
            "volume": 83
        },
        "fluency": 93,
        "rank": 100,
        "rhythm": 0,
        "integrity": 100,
        "pretime": 621,
        "delaytime": 82
    },
    "dtLastResponse": "2021-09-01 15:47:25:709",
    "cloud_platform": {
        "origin_audio_length": 19132
    }
}

Assessment response

Key

Type

Description

Recommended use

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 authorized account, which is the user's AppKey.

Internal parameter

audioUrl

string

The user's audio URL. By default, it is stored in the cloud for one month. Save the URL to your product server.

For reference

dtLastResponse

string

The time of the cloud response.

Internal parameter

eof

Int

0 indicates that the response is incomplete and more results will follow. 1 indicates that all responses for this assessment are complete.

Internal parameter

params

object

Echoes the assessment request parameters passed in by the client.

- app

object

- - applicationId

string

The authorized account, which is the user's AppKey.

- - userId

string

The user ID. A custom string for easy troubleshooting.

- - timestamp

string

The start time.

- - sig

string

The verification code.

- - clientId

string

- request

object

The node for scoring request parameters.

- audio

object

The number of audio parameter nodes in the scoring request.

result

object

The assessment result.

- res

string

The name of the resource used to assess this question type.

Internal parameter

- version

string

The version and publish time of the DPI engine.

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 for the entire assessment 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 audio duration, in ms.

For reference

- overall

float

The total score.

Recommended field

- fluency

float

The fluency score.

Internal parameter

- pron

float

The pronunciation score.

Internal parameter

- rhythm

float

The rhythm score (not currently used).

Internal parameter

- integrity

float

The integrity score.

Internal parameter

- fake_words

object

This field is returned only for out-of-vocabulary (OOV) words. To assess an OOV word, pass its phonemes using refText.

- -char

string

- info

object

- - snr

float

The signal-to-noise ratio (SNR). A higher value indicates greater clarity. Range: 0 to 40 dB. If this parameter affects the score, a corresponding tipId value is set.

For reference

- - clip

float

The audio volume is too high, which causes clipping. Range: 0 to 1. If this parameter affects the score, a corresponding tipId value is set.

Internal parameter

- - volume

int

The recording volume. Range: 0 to 180 dB.

For reference

- - tipId

int

Audio quality. For more information, see tipId message description.

Recommended field

Suggestions for displaying assessment results

Dimension

Description

Details

overall

Total score

The total assessment score.

Response for a failed assessment

If the result structure in the response is empty, the assessment failed. Retrieve the errId and error from the response and handle the error based on the corresponding error code.

Error codes

For error codes, see Assessment error codes.