API reference for recording file recognition - Intelligent Speech Interaction

Billing and service versions

Recording file recognition provides a trial edition and a commercial edition. For billing rules, see Billing.

For new integrations, explicitly set version="4.0" in the task parameters. This version uses the same camel-case fields for polling and callback results. For the legacy callback format, see Legacy version compatibility.

Limits

File requirements

WAV, MP3, M4A, WMA, AAC, OGG, AMR, and FLAC recording files are supported. The maximum file size is 512 MB. WAV and MP3 files support single-track and dual-track audio.

The language and sample rate of the audio must match the ASR model configured for the project. For model selection and supported models, see Languages and models.

Store the recording file on a file server that the service can access. Use a domain name rather than an IP address as the URL host. URLs must not contain spaces. Avoid Chinese characters in URLs.

We recommend storing files in Alibaba Cloud OSS. For public-read files, use an accessible file URL. For private files, use a presigned URL . For instructions, see Use presigned URLs to download or preview files.

For a self-hosted file server, ensure that the HTTP response header Content-Length matches the actual response body length.

Valid URL	Invalid URL
https://gw.alipayobjects.com/os/bmw-prod/0574ee2e-f494-45a5-820f-63aee583045a.wav	http://127.0.0.1/sample.wav D:\files\sample.wav

Request rates and task retention

The user-level QPS limit for recognition result queries is 100.

Requests that exceed the rate limits return Throttling.User. Set a polling interval to control the request rate.

Free users can recognize up to two hours of recording files per day.

After submission, tasks for free users complete within 24 hours, and tasks for paid users complete within six hours. Recognition results are retained on the server for 72 hours.

Important

These processing times do not apply to large batches, such as more than 500 hours of recordings submitted within half an hour. Contact a presales specialist for large-scale recognition requirements.

Workflow

Configure the ASR model for the project based on the language and sample rate of the audio.
Prepare a downloadable URL for the recording file.
Call SubmitTask by using a POST request and pass the task settings in the Task parameter. A successful submission returns the task ID in the top-level TaskId field of the JSON response.
Obtain the result: for polling, call GetTaskResult with this TaskId; for callbacks, set enable_callback=true and callback_url. The service sends the result to the callback URL by using POST when the task completes.

Interaction flow

The following diagram shows the interaction between the client and server. The task ID is returned in the TaskId field of the JSON response.

Client-server interaction flow for recording file recognition

API configuration

The service provides RPC-style POP APIs authenticated by AccessKey signatures. SubmitTask uses POST, and GetTaskResult uses GET. The product name used in SDK configuration is nls-filetrans. Configure the region, endpoint, and API date version as follows:

Region	regionId / endpointName	domain	API date version (Version)
Singapore	ap-southeast-1	filetrans.ap-southeast-1.aliyuncs.com	2019-08-23

The API date version Version configures the POP request. The lowercase version in the task parameters selects the recording file recognition service version.

Request parameters

Submit a task: SubmitTask

Serialize the following JSON object as a string and pass it as the Task parameter in a POST request. In this example, valid_times limits recognition to the specified interval. Omit this field to recognize the entire file.

Download the nls-sample-en-16k.wav sample and upload it to a location that the service can access over HTTP or HTTPS. Replace file_link in the following examples with the file URL.

{
    "appkey": "your-appkey",
    "file_link": "https://your-domain.example/nls-sample-en-16k.wav",
    "auto_split": false,
    "version": "4.0",
    "enable_words": false,
    "enable_sample_rate_adaptive": true,
    "valid_times": [
        {
            "begin_time": 0,
            "end_time": 3049,
            "channel_id": 0
        }
    ]
}

Task fields

Parameter	Type	Required	Description
appkey	String	Yes	The Appkey of the project. The ASR model configured for the project must match the language and sample rate of the audio.
file_link	String	Yes	The HTTP or HTTPS download URL of the recording file. The service must be able to download the file from this URL.
version	String	No	The service version used by the task. Default: 2.0. For new integrations, explicitly set this parameter to 4.0. For callback format compatibility, see Legacy version compatibility.
enable_words	Boolean	No	Specifies whether to return word information. Default: false. Set version to 4.0 to enable this feature.
enable_sample_rate_adaptive	Boolean	No	Specifies whether to automatically downsample audio with a sample rate above 16 kHz to 16 kHz. Default: false. Set version to 4.0 to enable this feature.
enable_callback	Boolean	No	Specifies whether to enable callbacks. Default: false.
callback_url	String	No	The callback URL. Required when enable_callback is true. HTTP and HTTPS are supported. Use a domain name rather than an IP address as the host. The callback service must accept POST requests.
auto_split	Boolean	No	Specifies whether to enable speaker diarization. ChannelId in each sentence identifies its speaker. The first speaker usually has ChannelId 0. This feature supports 8 kHz single-channel audio.
enable_unify_post	Boolean	No	Specifies whether to enable post-processing. Default: false. auto_split and enable_unify_post cannot both be true.
enable_inverse_text_normalization	Boolean	No	Specifies whether to enable inverse text normalization (ITN) to convert Chinese numerals to Arabic numerals. Default: false. To enable this feature, set version to 4.0 and enable_unify_post to true. ITN does not apply to word information.
enable_disfluency	Boolean	No	Specifies whether to enable disfluency removal. Default: false. To enable this feature, set version to 4.0 and enable_unify_post to true.
valid_times	List< ValidTime >	No	A list of valid time intervals. Only the specified audio segments are recognized. For the fields of each element, see ValidTime fields below.
max_end_silence	Integer	No	The maximum end-of-sentence silence. Default: 450 ms.
max_single_segment_time	Integer	No	The maximum duration of a sentence. Minimum: 10000 ms. Default: 20000 ms.
customization_id	String	No	The ID of the custom language model created by using the POP API. Omitted by default.
class_vocabulary_id	String	No	The ID of the class vocabulary. Omitted by default.
vocabulary_id	String	No	The ID of the general vocabulary. Omitted by default.

ValidTime fields

Each element of valid_times contains the following fields:

Parameter	Type	Required	Description
begin_time	Int	Yes	The start offset of the valid time range. Unit: milliseconds.
end_time	Int	Yes	The end offset of the valid time range. Unit: milliseconds.
channel_id	Int	Yes	The track index to which the valid time range applies. The index starts from 0.

Query a result: GetTaskResult

Pass the task ID returned by submission as the TaskId parameter in a GET request. Set the query interval according to the request rate limits.

Parameter	Type	Required	Description
TaskId	String	Yes	The recognition task ID.

Response parameters

The HTTP status indicates how the API request was processed. The task recognition status is reported by StatusCode and StatusText in the JSON response.

Submission response

A successful submission returns the following JSON:

{
        "TaskId": "4b56f0c4b7e611e88f34c33c2a60****",
        "RequestId": "E4B183CC-6CFE-411E-A547-D877F7BD****",
        "StatusText": "SUCCESS",
        "StatusCode": 21050000
}

Parameter	Type	Required	Description
TaskId	String	Yes	The recognition task ID.
RequestId	String	Yes	The request ID, used only for integration testing.
StatusCode	Int	Yes	The status code.
StatusText	String	Yes	The status description.

Query response

Succeeded

The following example shows the recognition result of the single-track English recording nls-sample-en-16k.wav.

{
    "TaskId": "7a200beed1f111f1a112b5efb07c****",
    "RequestId": "01A17CE9-B0EC-3FE4-B2EA-10C59979****",
    "StatusText": "SUCCESS",
    "BizDuration": 3049,
    "SolveTime": 1793097051064,
    "StatusCode": 21050000,
    "Result": {
        "Sentences": [
            {
                "EndTime": 1630,
                "SilenceDuration": 0,
                "BeginTime": 0,
                "Text": "today is monday",
                "ChannelId": 0,
                "SpeechRate": 73,
                "EmotionValue": 6.0
            },
            {
                "EndTime": 3030,
                "SilenceDuration": 0,
                "BeginTime": 1810,
                "Text": "the weather is nice",
                "ChannelId": 0,
                "SpeechRate": 147,
                "EmotionValue": 6.3
            }
        ]
    }
}

Queued

Recognition has not started. Wait before querying again.

{
        "TaskId": "c7274235b7e611e88f34c33c2a60****",
        "RequestId": "981AD922-0655-46B0-8C6A-5C836822****",
        "StatusText": "QUEUEING",
        "StatusCode": 21050002
}

Running

Recognition is in progress. Wait before querying again.

{
        "TaskId": "c7274235b7e611e88f34c33c2a60****",
        "RequestId": "8E908ED2-867F-457E-82BF-4756194A****",
        "StatusText": "RUNNING",
        "BizDuration": 0,
        "StatusCode": 21050001
}

Failed

The following example shows a file download failure. Use StatusCode and StatusText to handle the error.

{
        "TaskId": "4cf25b7eb7e711e88f34c33c2a60****",
        "RequestId": "098BF27C-4CBA-45FF-BD11-3F532F26****",
        "StatusText": "FILE_DOWNLOAD_FAILED",
        "BizDuration": 0,
        "SolveTime": 1536906469146,
        "StatusCode": 41050002
}

Response fields

Sentences and Words are contained in the Result object.

Parameter	Type	Required	Description
TaskId	String	Yes	The recognition task ID.
StatusCode	Int	Yes	The status code.
StatusText	String	Yes	The status description.
RequestId	String	Yes	The request ID, used for debugging.
Result	Object	No	The recognition result object returned when the task succeeds. Not included in queued, running, or failed task responses.
Sentences	List< SentenceResult >	No	The sentence results in Result, returned when StatusText is SUCCESS.
Words	List< WordResult >	No	The word information in Result. Returned when enable_words is true and version is 4.0.
BizDuration	Long	No	The duration of the recognized audio, in milliseconds.
SolveTime	Long	No	The Unix timestamp when recognition completes, in milliseconds. Not returned before the task completes.

Sentences fields

Parameter	Type	Required	Description
ChannelId	Int	Yes	The track ID of the sentence.
BeginTime	Int	Yes	The start offset of the sentence. Unit: milliseconds.
EndTime	Int	Yes	The end offset of the sentence. Unit: milliseconds.
Text	String	Yes	The recognized text of the sentence.
EmotionValue	Float	Yes	The emotion energy value, calculated as the volume in decibels divided by 10. Valid range: 1 to 10.
SilenceDuration	Int	Yes	The silence duration between this sentence and the previous sentence. Unit: seconds.
SpeechRate	Int	Yes	The average speech rate of the sentence. For Chinese, the unit is characters per minute. For English, the unit is words per minute.

Callback result

When enable_callback=true, callback_url, and version="4.0" are set, the service sends a POST request to the callback URL when the task completes. The recognition result fields are the same as those returned by polling:

{
    "Result": {
        "Sentences": [
            {
                "EndTime": 1630,
                "SilenceDuration": 0,
                "BeginTime": 0,
                "Text": "today is monday",
                "ChannelId": 0,
                "SpeechRate": 73,
                "EmotionValue": 6.0
            },
            {
                "EndTime": 3030,
                "SilenceDuration": 0,
                "BeginTime": 1810,
                "Text": "the weather is nice",
                "ChannelId": 0,
                "SpeechRate": 147,
                "EmotionValue": 6.3
            }
        ]
    },
    "TaskId": "36d01b244ad811e9952db7bb7ed2****",
    "StatusCode": 21050000,
    "StatusText": "SUCCESS",
    "RequestTime": 1553062810452,
    "SolveTime": 1553062810831,
    "BizDuration": 3049
}

RequestTime is the Unix timestamp of task submission, and SolveTime is the Unix timestamp when recognition completes. Both are in milliseconds.

Word information

When enable_words=true and version="4.0" are set, the result includes Words. Polling and callbacks return the same word information. The following example shows the result of the same English recording:

{
    "TaskId": "2e6a076bd1f111f1b005ad4b8dcd****",
    "RequestId": "01A17CE7-CD86-32AC-8F5A-AAFD425A****",
    "StatusText": "SUCCESS",
    "BizDuration": 3049,
    "SolveTime": 1793096926573,
    "StatusCode": 21050000,
    "Result": {
        "Words": [
            {
                "Word": "today",
                "EndTime": 600,
                "BeginTime": 270,
                "ChannelId": 0
            },
            {
                "Word": "is",
                "EndTime": 810,
                "BeginTime": 600,
                "ChannelId": 0
            },
            {
                "Word": "monday",
                "EndTime": 1080,
                "BeginTime": 810,
                "ChannelId": 0
            },
            {
                "Word": "the",
                "EndTime": 2020,
                "BeginTime": 1900,
                "ChannelId": 0
            },
            {
                "Word": "weather",
                "EndTime": 2290,
                "BeginTime": 2020,
                "ChannelId": 0
            },
            {
                "Word": "is",
                "EndTime": 2560,
                "BeginTime": 2290,
                "ChannelId": 0
            },
            {
                "Word": "nice",
                "EndTime": 2650,
                "BeginTime": 2560,
                "ChannelId": 0
            }
        ],
        "Sentences": [
            {
                "EndTime": 1630,
                "SilenceDuration": 0,
                "BeginTime": 0,
                "Text": "today is monday",
                "ChannelId": 0,
                "SpeechRate": 73,
                "EmotionValue": 6.0
            },
            {
                "EndTime": 3030,
                "SilenceDuration": 0,
                "BeginTime": 1810,
                "Text": "the weather is nice",
                "ChannelId": 0,
                "SpeechRate": 147,
                "EmotionValue": 6.3
            }
        ]
    }
}

Words fields

Parameter	Type	Required	Description
BeginTime	Int	Yes	The start time of the word. Unit: milliseconds.
EndTime	Int	Yes	The end time of the word. Unit: milliseconds.
ChannelId	Int	Yes	The track ID of the word.
Word	String	Yes	The word text.

Task status and error handling

StatusCode	StatusText	Description
21050000	SUCCESS	SubmitTask: the task was submitted successfully. GetTaskResult: recognition succeeded.
21050001	RUNNING	Recognition is in progress. Wait before querying again.
21050002	QUEUEING	The task is queued. Wait before querying again.
21050003	SUCCESS_WITH_NO_VALID_FRAGMENT	The task completed, but no valid speech segment was detected. Check whether the file contains valid speech.

Error codes

Status code	Status message	Cause and solution
41050001	USER_BIZDURATION_QUOTA_EXCEED	The daily recognition duration limit is exceeded. For larger workloads, contact sales at nls_support@service.aliyun.com.
41050002	FILE_DOWNLOAD_FAILED	The file could not be downloaded. Check the URL and whether the service can download the file.
41050003	FILE_CHECK_FAILED	The file format does not meet the requirements. Use a supported recording format.
41050004	FILE_TOO_LARGE	The file is too large. Check whether the recording file exceeds 512 MB.
41050005	FILE_NORMALIZE_FAILED	File normalization failed. Check whether the file is damaged and whether it can be played.
41050006	FILE_PARSE_FAILED	File parsing failed. Check whether the file is damaged and whether it can be played.
41050007	MKV_PARSE_FAILED	MKV parsing failed. Check whether the file is damaged and whether it can be played.
41050008	UNSUPPORTED_SAMPLE_RATE	The audio sample rate does not match the project model. Check whether the audio sample rate matches the ASR model configured for the project associated with the Appkey.
41050009	UNSUPPORTED_ASR_GROUP	The ASR group is unsupported. Check the Appkey and whether it belongs to the same account as the AccessKey used for signing.
41050010	FILE_TRANS_TASK_EXPIRED	TaskId does not exist or the task has expired. Check the task ID and result retention time.
41050011	REQUEST_INVALID_FILE_URL_VALUE	file_link is invalid. Check the file URL format and accessibility.
41050012	REQUEST_INVALID_CALLBACK_VALUE	callback_url is invalid. Provide a valid callback URL when callbacks are enabled.
41050013	REQUEST_PARAMETER_INVALID	The task parameters are invalid. Task must be a valid JSON string.
41050014	REQUEST_EMPTY_APPKEY_VALUE	appkey is empty. Specify the project Appkey.
41050015	REQUEST_APPKEY_UNREGISTERED	The Appkey is unregistered or does not match. Check the Appkey and whether it belongs to the same account as the AccessKey used for signing.
41050021	RAM_CHECK_FAILED	The RAM permission check failed. Grant the RAM user permission to call speech service APIs.
41050023	CONTENT_LENGTH_CHECK_FAILED	The HTTP response Content-Length does not match the actual file size. Correct the file server response header.
41050024	FILE_404_NOT_FOUND	The file to download does not exist. Check the file URL.
41050025	FILE_403_FORBIDDEN	The file cannot be downloaded due to insufficient permissions. Check whether you have permission to download the recording file.
41050026	FILE_SERVER_ERROR	The file server is unavailable. Check whether the file server is available.
51050000	INTERNAL_ERROR	An internal service error occurred. Occasional errors can be ignored. If the error occurs repeatedly, contact technical support.
51050001	VAD_FAILED	Voice activity detection failed. Occasional errors can be ignored. If the error occurs repeatedly, contact technical support.
51050002	RECOGNIZE_FAILED	Recognition failed. Occasional errors can be ignored. If the error occurs repeatedly, contact technical support.
51050003	RECOGNIZE_INTERRUPT	Recognition was interrupted. Occasional errors can be ignored. If the error occurs repeatedly, contact technical support.
51050004	OFFER_INTERRUPT	A queue write was interrupted. Occasional errors can be ignored. If the error occurs repeatedly, contact technical support.
51050005	FILE_TRANS_TIMEOUT	Task processing timed out. Occasional errors can be ignored. If the error occurs repeatedly, contact technical support.
51050006	FRAGMENT_FAILED	Audio segmentation failed. Occasional errors can be ignored. If the error occurs repeatedly, contact technical support.

Languages and models

Configure language and dialect models for the project. They cannot be selected through the task parameters of this API. Custom language models and hotwords are supported. For more information, see Language model customization and Hotwords.

On the All Projects page of the Intelligent Speech Interaction console, select the target project and open Project Settings. In Modify the configuration, use Select ASR Model to select a model matching the sample rate. Models with sample rates of 8 kHz or 16 kHz are available. Refer to the model options in the project configuration. For instructions, see Manage projects.

Legacy version compatibility

Callback results for tasks with version="2.0" use snake-case fields rather than the camel-case fields used by version 4.0. Applications that parse the legacy callback format must update their field parsing when upgrading to 4.0. The following example illustrates the legacy callback format:

{
    "result": [
        {
            "end_time": 1630,
            "silence_duration": 0,
            "begin_time": 0,
            "text": "today is monday",
            "channel_id": 0,
            "speech_rate": 73,
            "emotion_value": 6.0
        },
        {
            "end_time": 3030,
            "silence_duration": 0,
            "begin_time": 1810,
            "text": "the weather is nice",
            "channel_id": 0,
            "speech_rate": 147,
            "emotion_value": 6.3
        }
    ],
    "task_id": "3f5d4c0c399511e98dc025f34473****",
    "status_code": 21050000,
    "status_text": "SUCCESS",
    "request_time": 1551164878830,
    "solve_time": 1551164879230,
    "biz_duration": 3049
}