All Products
Search
Document Center

API reference

Last Updated: Dec 16, 2019

Features

Intelligent Speech Interaction supports recognizing short speech that lasts within 1 minute. This applies to short speech recognition scenarios such as chat conversations and voice command control. It has the following features:

  • Supports the following audio coding formats: pulse-code modulation (PCM) (uncompressed PCM or WAV files), Opus, and 16-bit mono.
  • Supports the following audio sampling rates: 8,000 Hz and 16,000 Hz.
  • Allows you to specify whether to return intermediate results, whether to add punctuation marks during post-processing, and whether to convert Chinese numerals to Arabic numerals.
  • Recognizes multiple languages. You can specify the language to be recognized by selecting a model when you modify a project in the Intelligent Speech Interaction console.

Limits

  • The duration of the speech to be recognized cannot exceed 60 seconds.

Endpoint

Access type Description URL
External access from the Internet This endpoint allows you to access the short sentence recognition service from any host over the Internet. By default, the Internet access URL is built in the SDK. You do not need to set the URL manually. wss://nls-gateway-ap-southeast-1.aliyuncs.com/ws/v1

Interaction process

Note: The interaction flowchart applies to Java SDK, C++ SDK, iOS SDK, and Android SDK, but does not apply to the RESTful API. For more information about the flowchart for the RESTful API, see RESTful API 2.0.

ASR

Note: The server adds the task_id field to the response header for all responses to indicate the ID of the recognition task. You need to record the value of this field. If an error occurs, you can open a ticket to submit the task ID and error message.

0. Authenticate the client

To establish a WebSocket connection with the server, the client must use a token for authentication. For more information about how to obtain the token, see Obtain a token.

1. Start and confirm recognition

The client sends a short sentence recognition request. The server confirms that the request is valid. You need to use the relevant set method of the SpeechRecognizer object to set common request parameters. The following table describes request parameters.

Parameter Type Required Description
appkey String Yes Indicates the appkey of a project created in the Intelligent Speech Interaction console.
format String No Specifies the audio coding format. Valid values: pcm (which indicates non-compressed PCM or WAV files), opus, and 16-bit mono. Default value: pcm.
sample_rate Integer No Specifies the audio sampling rate, in Hz. Default value: 16000. Select a model that supports the audio sampling rate for your project in the console.
enable_intermediate_result Boolean No Specifies whether to return intermediate results. Default value: false.
enable_punctuation_prediction Boolean No Specifies whether to add punctuation marks during post-processing. Default value: false.
enable_inverse_text_normalization Boolean No Specifies whether to enable inverse text normalization (ITN) during post-processing. A value of true indicates that Chinese numerals are converted to Arabic numerals. Default value: false.
customization_id String No Specifies the custom model ID.
vocabulary_id String No Indicates the ID of the custom extensive hotword.
enable_voice_detection Boolean No Specifies whether to enable voice detection. Default value: false.
max_start_silence Integer No Specifies the maximum duration of start silence. Unit: milliseconds. If the duration of start silence exceeds the value of this parameter, the server sends a RecognitionCompleted message to end the recognition task. This parameter takes effect only when the enable_voice_detection parameter is set to true.
max_end_silence Integer No Specifies the maximum duration of end silence. Unit: milliseconds. If the duration of end silence exceeds the value of this parameter, the server sends a RecognitionCompleted message to end the recognition task. This parameter takes effect only when the enable_voice_detection parameter is set to true.

2. Send and recognize audio data

The client cyclically sends audio data and continuously receives recognition results from the server.

  • If the enable_intermediate_result parameter is set to true, the server sends multiple RecognitionResultChanged messages to return intermediate results. For example, the client sends the following audio data:
  1. Weather in
  2. Weather in Beijing

The server returns the following message:

  1. {
  2. "header": {
  3. "namespace": "SpeechRecognizer",
  4. "name": "RecognitionResultChanged",
  5. "status": 20000000,
  6. "message_id": "e06d2b5d50ca40d5a50d4215c7c8d37c",
  7. "task_id": "4c3502c7a5ce4ac3bdc488749ce4f235",
  8. "status_text": "Gateway:SUCCESS:Success."
  9. },
  10. "payload": {
  11. "result": "Weather in Beijing"
  12. }
  13. }

The following table describes the parameters in the header object.

Parameter Type Description
namespace String The namespace of the message.
name String The name of the message. The RecognitionResultChanged message indicates that an intermediate result is obtained.
status Integer The status code, which indicates whether the request is successful. For more information, see Service status codes.
status_text String The status message.
task_id String The GUID of the task. Record the value of this field to facilitate troubleshooting.
message_id String The ID of the message.

The following table describes the parameters in the payload object.

Parameter Type Description
result String The intermediate result.

Note: The last intermediate result may be different from the final result. The final result is returned in the RecognitionCompleted message.

  • If the enable_intermediate_result parameter is set to false, the server does not return any messages in this step.

3. Stop and complete recognition

The client sends a request for stopping short sentence recognition to the server. The server returns the final recognition result:

  1. {
  2. "header": {
  3. "namespace": "SpeechRecognizer",
  4. "name": "RecognitionCompleted",
  5. "status": 20000000,
  6. "message_id": "10490c992aef44eaa4246614838fde86",
  7. "task_id": "4c3502c7a5ce4ac3bdc488749ce4f235",
  8. "status_text": "Gateway:SUCCESS:Success."
  9. },
  10. "payload": {
  11. "result": "Weather in Beijing."
  12. }
  13. }

The following table describes the parameters in the header object.

Parameter Type Description
namespace String The namespace of the message.
name String The name of the message. The RecognitionCompleted message indicates that an intermediate result is obtained.
status Integer The status code, which indicates whether the request is successful. For more information, see Service status codes.
status_text String The status message.
task_id String The GUID of the task. Record the value of this field to facilitate troubleshooting.
message_id String The ID of the message, which is automatically generated by the SDK.

The following table describes the parameters in the payload object.

Parameter Type Description
result String The result of short sentence recognition.

Service status codes

Each response message contains a status field, which indicates the service status code. The following table describes service status codes.

Common errors

Error code Description Solution
40000001 The error message returned because the client fails authentication. Check whether the token used by the client is correct and valid.
40000002 The error message returned because the message is invalid. Check whether the message sent by the client meets relevant requirements.
403 The error message returned because the token expires or the request contains incorrect parameters. Check whether the token used by the client is valid. Then, check request parameter settings.
40000004 The error message returned because the idle status of the client times out. Check whether the client does not send any data to the server for a long time.
40000005 The error message returned because the number of requests exceeds the upper limit. Check whether the number of concurrent connections or the queries per second (QPS) exceeds the upper limit.
41010101 Unsupported sampling rate please note that the sampling rate parameter (8000 or 16000) set in the code must match the model (8k or 16k) corresponding to APPKEY on the console
40000000 The error message returned because a client error has occurred. This is the default client error code. Resolve the error according to the error message or open a ticket.
50000000 The error message returned because a server error has occurred. This is the default server error code. If the error code is occasionally returned, ignore it. If the error code is returned multiple times, open a ticket.
50000001 The error message returned because an internal call error has occurred. If the error code is occasionally returned, ignore it. If the error code is returned multiple times, open a ticket.

Gateway errors

Error code Description Solution
40010001 The error message returned because the method is not supported. If you use the SDK, open a ticket.
40010002 The error message returned because the instruction is not supported. If you use the SDK, open a ticket.
40010003 The error message returned because the instruction is invalid. If you use the SDK, open a ticket.
40010004 The error message returned because the client is disconnected. Check whether the client is disconnected before the server completes the requested task.
40010005 The error message returned because the task status is incorrect. Check whether the instruction is supported in the current task status.

Metadata errors

Error code Description Solution
40020105 The error message returned because the application does not exist. Resolve the route to check whether the application exists.
40020106 The error message returned because the appkey and token do not match. Check whether the appkey is correct and belongs to the same account as the token.
40020503 The error message returned because RAM user authentication fails. Use your Alibaba Cloud account to authorize the RAM user to access the POP API.