tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Documentation

CreateRecTask

Last updated: 2024-12-12 15:06:28

1. API Description

Domain name for API request: asr.intl.tencentcloudapi.com.

This API can be used to recognize audio content with a long duration in recording files. If you want to use ASR with UI, visit [the trial console] (https://console.tencentcloud.com/asr/demonstrate). For product pricing, see [Billing Overview (Online Version)] (https://www.tencentcloud.com/document/product/1093/35686?from_cn_redirect=1)

  • Default frequency limit: 20 requests/second. This limit only applies to submitted requests but not the response time.
    Response time: The API adopts asynchronous callback and does not return results in real time. Recognition results will be returned within 3 hours at most. ** In most cases, audio with a duration of 1 hour can be recognized in 1 to 3 minutes. ** Note: The response time does not include the audio download time and will not apply to scenarios where recordings with a total audio duration of over 1,000 hours or over 20,000 requests are submitted within 30 minutes.
  • Audio formats: WAV, MP3, M4A, FLV, MP4, WMA, 3GP, AMR, AAC, OGG (Opus), and FLAC.
  • Supported languages: See the description of ** EngineModelType ** in this document or go to [Product Features] (https://www.tencentcloud.com/document/product/1093/35682?from_cn_redirect=1) for details.
  • Audio submission method: This API supports ** audio URLs and local audio files **. It is recommended to use [Tencent Cloud COS] (https://www.tencentcloud.com/document/product/436/38484?from_cn_redirect=1) to store audio files, generate URLs, and submit requests. This method does not incur public network or downstream traffic fees but can speed up task processing. (Set the public read and private write permissions for COS buckets or URLs to be externally accessible.)
  • Audio restrictions: For a single URL, the audio duration cannot exceed 5 hours, and the file size cannot exceed 1 GB. For a local audio file, the file size cannot exceed 5 MB.
  • Obtain recognition results: Results can be obtained through ** callback or polling **. See [Result Query] (https://www.tencentcloud.com/document/product/1093/37822?from_cn_redirect=1) for details.
  • Recognition result retention period: Recognition results are retained on the server for 24 hours.
  • For the signature method, see the content related to the signature method v3 in [Public Parameters] (https://www.tencentcloud.com/document/api/1093/35640?from_cn_redirect=1).

A maximum of 20 requests can be initiated per second for this API.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common Params. The value used for this API: CreateRecTask.
Version Yes String Common Params. The value used for this API: 2019-06-14.
Region No String Common Params. This parameter is not required.
EngineModelType Yes String Engine model type.
Each recognition engine adopts a specific billing plan. Engines marked with "large model version" adopt the large model billing plan. For product billing instructions, [click here] (https://www.tencentcloud.com/document/product/1093/35686?from_cn_redirect=1).


Note: If you want to recognize telecommunication audio but find that a 16k engine is required, you can use a 16k engine as described below for recognition. However, ** the 16k engines are not trained for recognizing telecommunication audio. Therefore, the recognition results cannot be guaranteed. You need to check whether the recognition results can be used.

Engines for general scenarios:
 Note: Use 16k engines for scenarios other than telecommunication.
16k_zh_large: ** Engine (large model version) for Mandarin, Chinese dialects, and English. This engine supports recognizing audio in Chinese, English, and [various Chinese dialects] (https://www.tencentcloud.com/document/product/1093/35682?from_cn_redirect=1). It has a large number of parameters, enhanced performance, and greatly improved recognition accuracy for low-quality audio with loud noise, too much echo, low voice volume, or faint voices. [Click here] (https://console.tencentcloud.com/asr/demonstrate) to compare the recognition performance of the 16k_zh engine and this one.
** 16k_multi_lang: ** Engine (large model version) for multiple languages. This engine supports recognizing audio in English, Japanese, Korean, Arabic, Filipino, French, Hindi, Indonesian, Malay, Portuguese, Spanish, Thai, Turkish, Vietnamese, and German (sentence-level or paragraph-level).
** 16k_zh-PY: ** Engine for Chinese, English, and Cantonese. The engine supports recognizing audio in Mandarin, English, and Cantonese at the same time.
** 16k_ms: ** Engine for Malay.
** 16k_id: ** Engine for Indonesian.
** 16k_th: ** Engine for Thai.
ChannelNum Yes Integer Number of recognition channels.
1: Mono. (16k engines only support mono. ** Do no t** set to stereo.)
2: Stereo. (Stereo is supported only for 8k engines, and the two channels should correspond to the respective communication parties.)

Note:
16k engines: Only support mono. ** ChannelNum should be set to 1 **.
8k engines: Support both mono and stereo. ** It is recommended to set ChannelNum to 2 (indicating stereo) **. Stereo can physically distinguish speakers to avoid recognition mistakes caused by overlapping speech. It can provide the best speaker separation and recognition effects. Once stereo is set, the speakers are automatically separated. ** You do not need to enable the speaker separation feature . You can use the default values for related parameters ( SpeakerDiarization and SpeakerNumber **). For speakerId in the returned ResultDetail, the value 0 represents the left channel, and the value 1 represents the right channel.
ResTextFormat Yes Integer Format of the returned recognition result.
0: The basic recognition result (containing only valid voice timestamps but no word-level [detailed recognition result] (https://www.tencentcloud.com/document/api/1093/37824?from_cn_redirect=1#SentenceDetail)).
1: The basic recognition result and word-level [detailed recognition result] (https://www.tencentcloud.com/document/api/1093/37824?from_cn_redirect=1#SentenceDetail) (containing word-level timestamps and speech speed value but ** no punctuation **).
2: The basic recognition result and word-level [detailed recognition result] (https://www.tencentcloud.com/document/api/1093/37824?from_cn_redirect=1#SentenceDetail) (containing word-level timestamps, speech speed value, and ** punctuation **).
3: The basic recognition result and word-level [detailed recognition result] (https://www.tencentcloud.com/document/api/1093/37824?from_cn_redirect=1#SentenceDetail) (containing word-level timestamps, speech speed value, and ** punctuation **). The recognition results are segmented by punctuation. ** This format applies to subtitle scenarios **.
4: ** [Value-added paid feature] ** The basic recognition result and word-level [detailed recognition result] (https://www.tencentcloud.com/document/api/1093/37824?from_cn_redirect=1#SentenceDetail) (containing word-level timestamps, speech speed value, and ** punctuation **). The recognition results are segmented by NLP semantics. ** This format applies to scenarios such as meeting and court record transcription ** and is supported only for 8k_zh and 16k_zh engines.
5: ** [Value-added paid feature] ** Basic recognition result and word-level [detailed recognition result] (https://www.tencentcloud.com/document/api/1093/37824?from_cn_redirect=1#SentenceDetail) (containing word-level timestamps, speech speed value, and ** punctuation ). The oral-to-written transcription result is also output, which has excluded modal particles and consecutive identical words, optimized expressions, and corrected speech mistakes. ** This format applies to scenarios of generating minutes for online and offline meetings and is supported only for 8k_zh and 16k_zh engines.

Notes:
If this parameter is set to 4, make sure that a [semantics-based segmentation resource package] (https://www.tencentcloud.com/document/product/1093/35686?from_cn_redirect=1#97ae4aa0-29a0-4066-9f07-ccaf8856a16b) is purchased for your account or that your account has enabled post-payment. ** If post-payment is enabled and this parameter is set to 4, [automatic billing] (https://www.tencentcloud.com/document/product/1093/35686?from_cn_redirect=1#d912167d-ffd5-41a9-8b1c-2e89845a6852) will apply **.
If this parameter is set to 5, make sure that an [oral-to-written resource package] (https://www.tencentcloud.com/document/product/1093/35686?from_cn_redirect=1#97ae4aa0-29a0-4066-9f07-ccaf8856a16b) is purchased for your account or that your account has enabled post-payment. ** If post-payment is enabled and this parameter is set to 5, [automatic billing] (https://www.tencentcloud.com/document/product/1093/35686?from_cn_redirect=1#d912167d-ffd5-41a9-8b1c-2e89845a6852) will apply **.
SourceType Yes Integer Audio source.
0: Audio URL.
1: Local audio file (body of the POST request).
Data No String Audio file Base64 code.
** This parameter is required if SourceType is set to 1. Otherwise, it can be left blank. **

Note: The audio data size cannot exceed 5 MB.
DataLen No Integer Data length (before Base64 encoding).
Url No String Audio URL. (The audio should be downloadable via a public network browser.)
** This parameter is required if SourceType is set to 0. Otherwise, it can be left blank. **

Notes:
1. Make sure that the total audio duration of recording files does not exceed 5 hours. Otherwise, recognition may fail.
2. Pay attention to file download to avoid download failure.
CallbackUrl No String Callback URL

User-defined service URL for receiving recognition results.
For the callback format and content, see [Callback Description] (https://www.tencentcloud.com/document/product/1093/52632?from_cn_redirect=1).

Notes:

- If you use the polling method to obtain recognition results, this parameter is not required.
- It is recommended to include your business ID and other information in the callback URL for handling business logic.
SpeakerDiarization No Integer Whether to enable speaker separation.
0: Disable.
1: Enable. (This value is supported only for the following engines: 8k_zh, 16k_zh, 16k_ms, 16k_en, 16k_id, 16k_zh_large, and 16k_zh_dialect. ChannelNum should be set to 1.)
The default value is 0.

Note:
If an 8k engine is used and ChannelNum is set to 2 (stereo), use the default values for corresponding parameters as stated in the ** ChannelNum ** parameter description.
SpeakerNumber No Integer Number of speakers to be separated.
** Speaker separation must be enabled. Otherwise, this parameter does not take effect. ** Value range: 0-10.
0: Automatic separation. (Up to 20 speakers can be separated.)
1-10: Specify the number of speakers.
The default value is 0.
HotwordId No String This service is not available.
CustomizationId No String This service is not available.
EmotionRecognition No Integer This service is not available.
EmotionalEnergy No Integer Emotional energy value.
The value is the result of dividing the sound volume in dB by 10. Value range: [1,10]. The higher the value, the stronger the emotion.
0: Disable.
1: Enable.
The default value is 0.
ConvertNumMode No Integer Intelligent conversion into Arabic numerals (supported only for engines for recognizing audio in Mandarin).
0: Do not convert, but directly output Chinese numerals.
1: Intelligently convert into Arabic numerals based on the scenario.
3: Enable conversion for math-related letters.
The default value is 1.
FilterDirty No Integer Dirty word filtering (supported only for engines for recognizing audio in Mandarin).
0: Do not filter out dirty words.
1: Filter out dirty words.
2: Replace dirty words with *.
The default value is 0.
FilterPunc No Integer Punctuation filtering (supported only for engines for recognizing audio in Mandarin).
0: Do not filter out punctuation.
1: Filter out sentence-ending punctuation.
2: Filter out all punctuation.
The default value is 0.
FilterModal No Integer Modal particle filtering (supported only for engines for recognizing audio in Mandarin).
0: Do not filter out modal particles.
1: Filter out specified modal particles.
2: Filter out all modal particles.
The default value is 0.
SentenceMaxLength No Integer The maximum number of characters per line (supported only for engines for recognizing audio in Mandarin). A punctuation mark is added if this limit is reached.
** This parameter can control the maximum number of characters per line, which applies to subtitle generation scenarios. ** Value range: [6,40].
0: Disable this feature.
The default value is 0.

Note: To enable this feature, ResTextFormat should be set to 3. The recognition result can be obtained from FinalSentence by parsing the list in the returned ResultDetail.
Extra No String Additional parameter. ** (This parameter is meaningless. Ignore it.) **
HotwordList No String Temporary term list. This parameter is used to improve the recognition accuracy.

- Restrictions for individual terms: The format is "term|weight". Each term can contain no more than 30 characters (or 10 Chinese characters. The weight can be in the range of [1-11] or 100. For example, "Tencent Cloud|5" or "ASR|11".

- Restrictions for the temporary term list: Multiple terms are separated by commas. The list can contain up to 128 terms. For example, "Tencent Cloud|10, Audio Recognition|5, ASR|11".

- Difference between hotword_id (term list) and hotword_list (temporary term list):

- hotword_id: Term list. You need to create a term list in the console or by using the API first and obtain the term list ID.

- hotword_list: Temporary term list. You can directly enter the ID of the temporary term list each time you initiate a request. The temporary term list is not retained on the cloud. This parameter applies to users with a massive number of terms.

Notes:

- If both hotword_id and hotword_list are specified, hotword_list will take effect first.

- When the weight of a term is set to 11, this term becomes a super term. It is recommended that the weight is set to 11 only for critical and necessary terms. The overall accuracy will be affected if the weight is set to 11 for too many terms.

- When the weight of a term is set to 100, the term enhancement feature is enabled to replace homophones of this term. (This feature is supported only for 8k_zh and 16k_zh engines.) For example, if you configure "mizhi 1|100", the recognized word "mizhi 2", which is a homophone of "mizhi 2", will be forcibly replaced with "mizhi 2". It is recommended that you enable this feature based on the actual needs. You can set the weight to 100 for only critical and necessary terms. The overall accuracy will be affected if the weight is set to 100 for too many terms.
KeyWordLibIdList.N No Array of String List of keyword IDs for recognition. This parameter is left blank by default, indicating that no keyword is recognized. You can enter up to 10 IDs.

3. Output Parameters

Parameter Name Type Description
Data Task Returned result of the recording recognition request, containing the task ID required for querying the result.
** Note: The task ID is valid for 24 hours, and duplicate task IDs of different dates may exist. Do not use task ID as the unique ID in your business system. **
RequestId String The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

4. Example

Example1 Calling the API by using an audio URL

Request the recording recognition service by using an audio URL (SourceType set to 0). The engine is 16k_zh (EngineModelType set to 16k_zh), and the audio format is WAV (sampling rate: 16 kHz; channel mode: mono).

Input Example

POST / HTTP/1.1
Host: asr.intl.tencentcloudapi.com
Content-Type: application/json; charset=utf-8
X-TC-Version: 2019-06-14
X-TC-Region: ap-shanghai
X-TC-Action: CreateRecTask
X-TC-Timestamp: 1599142560
Authorization: TC3-HMAC-SHA256 Credential=xxx/2020-09-03/asr/tc3_request, SignedHeaders=content-type;host, Signature=524ed61a4a71de417f4fa41249dcb428a0c51013890f24f3492068ca7cd16953
<Common request parameters>

{
    "Url": "http://test.cos.ap-guangzhou.myqcloud.com/test.wav",
    "ChannelNum": 1,
    "EngineModelType": "16k_zh",
    "ResTextFormat": 0,
    "SourceType": 0
}

Output Example

{
    "Response": {
        "RequestId": "3c140219-cfe9-470e-b241-907877d6fb03",
        "Data": {
            "TaskId": 1393265
        }
    }
}

Example2 Calling the API by uploading the audio data

Request the recording recognition service by uploading the audio data (SourceType set to 1). The engine is 16k_zh (EngineModelType set to 16k_zh), and the audio format is WAV (sampling rate: 16 kHz; channel mode: mono).

Input Example

POST / HTTP/1.1
Host: asr.intl.tencentcloudapi.com
Content-Type: application/json; charset=utf-8
X-TC-Version: 2019-06-14
X-TC-Region: ap-shanghai
X-TC-Action: CreateRecTask
X-TC-Timestamp: 1599142560
Authorization: TC3-HMAC-SHA256 Credential=xxx/2020-09-03/asr/tc3_request, SignedHeaders=content-type;host, Signature=524ed61a4a71de417f4fa41249dcb428a0c51013890f24f3492068ca7cd16953
<Common request parameters>

{
    "ChannelNum": 1,
    "EngineModelType": "16k_zh",
    "ResTextFormat": 0,
    "Data": "eGNmYXNkZmFzZmFzZGZhc2RmCg==",
    "SourceType": 1
}

Output Example

{
    "Response": {
        "RequestId": "3c140219-cfe9-470e-b241-907877d6fb03",
        "Data": {
            "TaskId": 1396665
        }
    }
}

5. Developer Resources

SDK

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

Command Line Interface

6. Error Code

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

Error Code Description
AuthFailure.InvalidAuthorization Authentication error occurred.
FailedOperation.CheckAuthInfoFailed Authentication error occurred.
FailedOperation.ErrorDownFile Failed to download the audio file.
FailedOperation.ErrorRecognize Recognition failed.
FailedOperation.ServiceIsolate Services are stopped due to overdue payments. Top up your Tencent Cloud account first.
FailedOperation.UserHasNoAmount The resource package is used up. Purchase a new one or enable post-payment.
FailedOperation.UserHasNoFreeAmount The resource package is used up. Enable post-payment or purchase a new resource package.
FailedOperation.UserNotRegistered The service is not enabled. Enable it in the Tencent Cloud ASR console.
InternalError.ErrorDownFile Failed to download the audio file.
InternalError.FailAccessDatabase Failed to access the database.
InternalError.FailAccessRedis Failed to access Redis.
InvalidParameter Parameter error.
InvalidParameterValue Invalid parameter value.
MissingParameter Parameters are missing
RequestLimitExceeded.UinLimitExceeded Requests are sent too frequently.
UnknownParameter Unknown parameter.
Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
Privacy PolicyLegalCookie Policy