This topic describes the flow for submitting an audio file for recognition and retrieving the results.
Usage notes
Supported input formats: WAV, MP3, and AAC.
The audio file for recognition cannot exceed 100 MB.
To set up multi-language recognition, you can select a model by editing the project in the console. For more information, see Manage projects.
Endpoint
Access type | Description | URL | Host |
Public network access | All servers can use the public access URL. |
|
|
Internal access from an Alibaba Cloud ECS instance in Shanghai | If you use an Alibaba Cloud ECS instance in the China (Shanghai), China (Beijing), or China (Shenzhen) region, you can use the internal access URL. ECS instances in the classic network cannot access AnyTunnel. This means they cannot access the Voice Service over the internal network. To use AnyTunnel, create a VPC and access the service from within it. Note
|
|
|
The following sections use public access URLs as examples. If you use an Alibaba Cloud ECS instance in Shanghai and need to use an internal access URL, you must use the HTTP protocol and replace the public access URL and Host with the internal ones.
Interaction flow
The following figure shows the interaction flow for the iOS SDK and the Android SDK.
Authentication and initialization
When the client connects to the server, it uses an access token for authentication. For more information about how to obtain a token, see Overview of obtaining a token.
Initialization parameters
Parameter
Type
Required
Description
url
String
Yes
The URL of the Voice Service.
app_key
String
Yes
The appkey of the project that you created in the console.
token
String
Yes
Ensure that the token is valid and has not expired.
NoteYou can set the token during initialization or update it through parameter settings.
device_id
String
Yes
The device ID, which uniquely identifies a device, such as a MAC address, serial number (SN), or UniquePseudoID.
Start file recognition
When the client initiates a file recognition request, you must pass the `params` parameter in JSON format through the API.
Parameter
Type
Required
Description
file_path
String
Yes
The absolute path of the file to recognize.
direct_ip
String
No
You can perform DNS resolution for the endpoint and pass the IP address for access.
nls_config
JsonObject
No
Configuration of service details.
The `nls_config` field is used to set specific configuration parameters for the service. These parameters are mostly related to recognition performance.
Parameter
Type
Required
Description
format
String
Yes
The audio coding format. Supported formats are WAV, MP3, and AAC.
sample_rate
Integer
No
The sample rate used by the recognition model. This is typically configured in the console instead of being set here.
enable_inverse_text_normalization
Boolean
No
Inverse text normalization (ITN), which converts Chinese numerals to Arabic numerals. If you set this parameter to `True`, Chinese numerals are converted to Arabic numerals in the output. Default value: `False`.
max_end_silence
Integer
No
The maximum allowed trailing silence in milliseconds. Default value: 450.
customization_id
String
No
The ID of a custom model created using a POP API. By default, this parameter is not added.
vocabulary_id
String
No
The ID of a custom vocabulary. By default, this parameter is not added.
enable_word_level_result
Boolean
No
Specifies whether to return word-level information. Default value: `false`.
first_channel_only
Boolean
No
Specifies whether to process only the first sound channel. Default value: `false`.
Obtain the recognition result
After the task starts, you will receive the `EVENT_FILE_TRANS_RESULT` event. The time it takes to receive this event depends on the file length and network conditions. This event contains the complete transcription result. The following code provides an example.
{ "task_id":"e76f979b33d9443eb6fbf770315a****", "status":20000000, "message":"SUCCESS", "flash_result":{ "duration":299, // Audio duration "completed":true, "sentences":[ { "text":"Ah,", // Sentence-level recognition result "begin_time":3700, // Start time of the sentence in milliseconds "end_time":3940, // End time of the sentence in milliseconds "channel_id":0, // For audio files with multiple channels, recognition results are returned for each channel. The channel ID starts from 0. "words":[ { "text":"Ah", // Word information in the current sentence "begin_time":3700, // Start time of the current word in milliseconds "end_time":3940, // End time of the current word in milliseconds "punc":"," // Punctuation at the end of the current word. This field is empty if there is no punctuation. } ] }, { "text":"Where am I.", "begin_time":3940, "end_time":4720, "channel_id":0, "words":[ { "text":"I", "begin_time":3940, "end_time":4040, "punc":"," }, { "text":"where", "begin_time":4040, "end_time":4340, "punc":"," }, { "text":"am", "begin_time":4340, "end_time":4720, "punc":"," } ] } ] } }The response message is in JSON format and contains the following fields.
Field
Description
task_id
The task ID, which is the unique identifier of the task.
status
Status code
message
Status message
flash_result
The recognition result object.
The `flash_result` object includes the following fields.
Field
Description
sentences
The sentence-level recognition results, which is an array of objects.
Each object in the `sentences` array contains the following fields.
Field
Description
text
The recognition result.
begin_time
The time offset of the start of the recognized speech in the audio stream, in milliseconds.
end_time
The time offset of the end of the recognized speech in the audio stream, in milliseconds.
Error codes
General-purpose error codes
Status code | Status message | Cause | Solution |
40000000 | The default client error code. This code corresponds to multiple error messages. | Invalid parameters or call logic was used. | Compare your code with the sample code in the official documentation to test and verify it. |
40000001 | The token 'xxx' has expired. The token 'xxx' is invalid | Invalid parameters or call logic was used. This is a general-purpose client error code that usually indicates an incorrect token, such as an expired or invalid token. | Compare your code with the sample code in the official documentation to test and verify it. |
40000002 | Gateway:MESSAGE_INVALID:Can't process message in state'FAILED'! | The message is invalid or incorrect. | Compare your code with the sample code in the official documentation to test and verify it. |
40000003 | PARAMETER_INVALID Failed to decode url params | The parameters passed by the user are incorrect. This error is common for RESTful API calls. | Compare your code with the sample code in the official documentation to test and verify it. |
40000005 | Gateway:TOO_MANY_REQUESTS:Too many requests! | Too many concurrent requests. | If you are using the Free Edition, you can upgrade to a commercial version to increase the concurrency. If you are already using a commercial version, you can purchase a concurrency resource plan to increase your concurrency quota. |
40000009 | Invalid wav header! | The message header is invalid. | If you send a WAV audio file and set the |
40000009 | Too large wav header! | The WAV header of the transmitted audio is invalid. | You can send the audio stream in a format such as PCM or OPUS. If you use the WAV format, make sure that the WAV header of the audio file contains the correct data length. |
40000010 | Gateway:FREE_TRIAL_EXPIRED:The free trial has expired! | The trial period has ended, and the commercial version is not activated or your account has an overdue payment. | You can log on to the console to check the service activation status and your account balance. |
40010001 | Gateway:NAMESPACE_NOT_FOUND:RESTful url path illegal | The operation or parameter is not supported. | Check whether the parameters passed in the call are consistent with the requirements in the official documentation. You can compare them with the error message to identify and set the correct parameters. For example, if you are using a curl command to make a RESTful API request, check whether the URL you constructed is valid. |
40010003 | Gateway:DIRECTIVE_INVALID:[xxx] | A general-purpose client-side error code. | This error indicates that the client passed an incorrect parameter or instruction. Detailed error messages are available for different operations. You can refer to the corresponding documentation to set the parameters correctly. |
40010004 | Gateway:CLIENT_DISCONNECT:Client disconnected before task finished! | The client actively terminated the connection before the request was processed. | None. Alternatively, you can close the connection after the server responds. |
40010005 | Gateway:TASK_STATE_ERROR:Got stop directive while task is stopping! | The client sent a message instruction that is not currently supported. | Compare your code with the sample code in the official documentation to test and verify it. |
40020105 | Meta:APPKEY_NOT_EXIST:Appkey not exist! | A non-existent Appkey was used. | Confirm whether a non-existent Appkey was used. You can log on to the console and view the project configuration to find the Appkey. |
40020106 | Meta:APPKEY_UID_MISMATCH:Appkey and user mismatch! | The Appkey and token passed in the call were not created by the same Alibaba Cloud account UID. This causes a mismatch. | Check whether you are using resources from two different accounts. Do not use an Appkey from Account A with a token generated from Account B. |
403 | Forbidden | The token is invalid. For example, the token does not exist or has expired. | Set a valid token. Tokens have an expiration period. You must obtain a new token before the current one expires. |
41000003 | MetaInfo doesn't have end point info | Failed to retrieve the routing information for this Appkey. | Check whether you are using resources from two different accounts. Do not use an Appkey from Account A with a token generated from Account B. |
41010101 | UNSUPPORTED_SAMPLE_RATE | The sample rate is not supported. | Real-time speech recognition currently supports only audio with a sample rate of 8000 Hz or 16000 Hz. |
41040201 | Realtime:GET_CLIENT_DATA_TIMEOUT:Client data does not send continuously! | Failed to retrieve data from the client due to a timeout. | When you call real-time speech recognition, the client must send data at a real-time rate and close the connection promptly after the data is sent. |
50000000 | GRPC_ERROR:Grpc error! | An exception caused by factors such as machine load or network issues. This error usually occurs randomly. | You can retry the call to resolve the issue. |
50000001 | GRPC_ERROR:Grpc error! | An exception caused by factors such as machine load or network issues. This error usually occurs randomly. | You can retry the call to resolve the issue. |
52010001 | GRPC_ERROR:Grpc error! | An exception caused by factors such as machine load or network issues. This error usually occurs randomly. | You can retry the call to resolve the issue. |
Short sentence recognition error codes
Status code | Status message | Cause | Solution |
40000000 | Gateway:CLIENT_ERROR:Empty audio data! | No audio data. | You can refer to the public cloud sample code and send audio data with the request. |
40000004 | Gateway:IDLE_TIMEOUT:Websocket session is idle for too long time | After a connection is established, the server returns this error message if no data is sent for more than 10 seconds. | After you establish a connection, you must maintain interaction with the server. For example, you can continuously send the audio stream while it is being captured. Close the connection promptly after the audio is sent. |
40010002 | Gateway:DIRECTIVE_NOT_SUPPORTED:Directive'SpeechRecognizer.EnhanceRecognition'isnotsupported! | A message instruction that is not supported by the server was sent. | Compare your code with the sample code in the official documentation to test and verify it. |
40010003 | Gateway:DIRECTIVE_INVALID:Too many items for ‘vocabulary'!(173) | Too many hotwords were set. | You can refer to the API documentation to set the parameters correctly. |
40270002 | NO_VALID_AUDIO_ERROR | The audio is invalid. | No valid text was recognized from the audio. |
41010104 | TOO_LONG_SPEECH | The duration of the sent audio exceeds the limit. This error occurs only with the short sentence recognition operation. | Short sentence recognition supports audio up to 60 seconds long. If the audio is longer than 60 seconds, you must call the real-time speech recognition operation. |
41010105 | SILENT_SPEECH | The data contains only silence or noise, so no valid speech can be detected. | None. |
Short sentence recognition/Real-time speech recognition/Flash audio file recognition
Configuration or parameter errors
Status code
Status message
Cause
Solution
240999
DEFAULT_ERROR
Internal default error.
Internal unspecified error.
240001
NUI_CONFIG_INVALID
Configuration file error.
Configuration file error. Confirm that the resource file exists in the specified resource path. For Android, refer to the code sample and use the copyAssets interface.
240002
ILLEGAL_PARAM
Invalid parameter.
Confirm that the passed format is correct, including field types and value range limits.
For example, enable_voice_detection must be set to the boolean value true, not 1 or the string "true".
240003
ILLEGAL_INIT_PARAM
Invalid initialization parameter.
Confirm whether the initialization parameter format is incorrect or if a required field is missing.
240004
NECESSARY_PARAM_LACK
A required parameter is missing.
Confirm the required parameters for the operation call.
240005
NULL_PARAM_ERROR
The parameter is null.
Confirm whether the parameter is null.
240006
NULL_LISTENER_ERROR
The event callback is not defined.
Confirm that the callback event is correctly assigned.
240007
NULL_DIALOG_ERROR
No valid dialog instance. This usually occurs during an internal state error.
Confirm that the state is correct before calling the operation. You can use the cancel operation to restore the idle state.
240008
NULL_ENGINE_ERROR
No valid engine instance. Check whether initialization was successful.
Confirm whether initialization was successful.
240009
ILLEGAL_DATA
The passed audio data address or length is invalid.
Confirm the passed data length value.
SDK status errors
Status code
Status message
Cause
Solution
240010
ILLEGAL_REENTRANT
An SDK operation was called after exiting.
This can be ignored if it does not affect functionality.
240011
SDK_NOT_INIT
The SDK is not initialized correctly.
Confirm that the initialization returns a correct value before you call other operations.
240012
SDK_ALREADY_INIT
The SDK initialization operation was called repeatedly.
Confirm the initialization call logic.
240013
DIALOG_INVALID_STATE
Internal dialog state error.
Read the SDK flowchart to confirm whether the operation was called in an incorrect state.
240014
STATE_INVALID
SDK internal state error.
Read the SDK flowchart to confirm whether the operation was called in an incorrect state.
240015
ILLEGAL_FUNC_CALL
The operation cannot be called in this mode.
Confirm whether the operation call is reasonable.
System call errors
Status code
Status message
Cause
Solution
240020
MEM_ALLOC_ERROR
Memory allocation error.
Check for insufficient memory.
240021
FILE_ACCESS_FAIL
File access error.
Check whether read and write permissions are granted for the file.
240022
CREATE_DIR_ERROR
Error creating directory.
Check for write permissions.
SDK internal call errors
Status code
Status message
Cause
Solution
240030
CREATE_NUI_ERROR
Engine creation failed.
Failed to create the instance, usually due to insufficient system resources.
240031
TEXT_DIALOG_START_FAIL
Failed to initiate text understanding.
Text-to-semantic understanding failed. Check the network connection or whether information such as the URL and token is valid.
240032
TEXT_CANCEL_START_FAIL
Failed to cancel text understanding.
This can be ignored.
240033
WUW_DUPLICATE
Duplicate dynamic wake-up word.
This can be ignored.
Local engine call errors
Status code
Status message
Cause
Solution
240040
CEI_INIT_FAIL
Local engine initialization failed.
Confirm whether the local engine's model is valid and whether the directory is readable and writable.
Audio errors
Status code
Status message
Cause
Solution
240051
UPDATE_AUDIO_ERROR
Error pushing audio, usually because the input audio length is greater than the required audio length.
Confirm whether the length of the pushed audio is invalid.
240052
MIC_ERROR
Failed to get audio for 2 consecutive seconds.
Confirm whether audio of the required length is correctly provided in the audio data callback.
Network errors
Status code
Status message
Cause
Solution
240060
CREATE_DA_REQUEST_ERROR
Failed to create a dialog assistant instance.
This can be ignored.
240061
START_DA_REQUEST_ERROR
Failed to initiate a dialog assistant request.
This can be ignored.
240062
DEFAULT_NLS_ERROR
A server-side error occurred.
NoteThis error also contains the content of the server-side response.
For more information, see Server-side error codes to further locate the issue.
240063
SSL_ERROR
Error creating SSL instance.
Ignore if it occurs randomly.
240064
SSL_CONNECT_FAILED
SSL connection failed.
Connection exception. Check whether the service URL or local network connection is normal.
240065
HTTP_CONNECT_FAILED
HTTP connection failed.
Service connection error. Check the log file for the HTTP return value to confirm the cause.
240066
DNS_FAILED
DNS resolution failed.
Check whether the local network and DNS service are normal.
240067
CONNECT_FAILED
Socket connection failed.
Check the network connection.
240068
SERVER_NOT_ACCESS
The server is inaccessible.
Check whether the token has expired or the URL is correct.
240069
SOCKET_CLOSED
The socket is closed.
Ignore if it occurs randomly.
240070
AUTH_FAILED
Authentication failed.
Check whether you have provided the correct ak_secret, ak_id, app_key, sdk_code, and device_id. Also, confirm that you have a sufficient quota.
240071
HTTPDNS_FAILED
Failed to connect using the IP address passed by the client.
If you are accessing by directly passing an IP address, confirm whether the IP address is accessible.
240072
HTTP_SEND_FAILED
HTTP send failed for file transcription.
Confirm that the network connection is normal.
240073
HTTP_RECEIVE_FAILED
HTTP receive failed for file transcription.
Confirm that the network connection is normal.
240074
HTTP_RESPONSE_ERROR
Failed to parse received content for file transcription.
The content returned by the server is incorrect.
240075
HTTP_SERVER_ERROR
File transcription service error.
For more information, see Server-side error codes to further locate the issue.