このページは現在英語版のみで提供されており、日本語版も近日中に提供される予定です。ご利用いただきありがとうございます。
Feedback

リアルタイム音声認識

API Description

This API leverages the WebSocket protocol to deliver real-time speech recognition for audio streams. Recognition results are returned synchronously, enabling instant transcription as audio is received.

API Requirements

Follow these requirements when integrating the real-time speech recognition API.
Item
Description
Supported Languages
Including zh (Chinese), en (English), yue (Cantonese), ar (Arabic), de (German), fr (French), es (Spanish), pt (Portuguese), id (Indonesian), it (Italian), ko (Korean), ru (Russian), th (Thai), vi (Vietnamese), ja (Japanese), tr (Turkish), hi (Hindi), ms (Malay), nl (Dutch), sv (Swedish), da (Danish), fi (Finnish), pl (Polish), cs (Czech), fil (Filipino), fa (Persian), el (Greek), ro (Romanian), hu (Hungarian), and mk (Macedonian).
Supported Industries
General purpose.
Audio Properties
Sample rate: 16,000Hz or 8,000Hz;
Sample precision: 16 bits;
Channel: Mono.
Audio Format
PCM.
Request Protocol
WSS protocol.
Request URL
wss://asr-intl.cloud-rtc.com/asr/v2/<appid>?{request parameters}. TRTC authentication information (SdkAppId and UserSig) may be supplied either through a WebSocket header or through URL query parameters. You may choose either one.
Response Format
JSON.
Data Transmission
Transmit a data packet every 40ms, each containing 40ms of audio (1:1 real-time rate). PCM size: 640 bytes for 8k sample rate, 1280 bytes for 16k sample rate. If the interval between audio packets exceeds 15 seconds, and the backend will return an error and disconnect the session.
Concurrency Limit
Default concurrency limit per account is 200 streams.
Note:
Under the same SDKAppID, all real-time speech recognition scenarios—including direct TTS access, AI Conversation, and AI Transcription/Translation—share a single concurrency pool. This means the total number of concurrent streams across all types cannot exceed the account's upper limit. One-Sentence Recognition and Audio File Recognition are calculated independently and do not consume the real-time recognition concurrency quota. If you require higher concurrency, please Contact Us.

Business Flow Diagram



API Call Flow

The API call flow consists of two stages: handshake and recognition. During both stages, the backend returns a text message containing a JSON serialized string. The format is described as follows:
Field Name
Type
Description
code
Integer
Status code: 0 indicates success, non-zero indicates an error.
message
String
Error description.
voice_id
String
Globally unique identifier for the audio stream. Each WebSocket connection uses a distinct identifier. Users must generate this value (UUID recommended), up to 128 characters.
Note:
Generate a new voice_id for every WebSocket connection. If recognition or the connection is interrupted (e.g., connection failure, normal end, error code returned), the voice_id becomes invalid. To restart recognition, use a new voice_id.
message_id
String
Unique ID for this message.
result
Result
Latest speech recognition result.
final
Integer
A value of 1 indicates that recognition for the entire audio stream is complete.
The Result structure for recognition results is as follows:
Field Name
Type
Description
slice_type
Integer
Recognition result type:
0: Start of a segment;
1: Segment in progress; voice_text_str is a partial result (subject to change);
2: Segment ended; voice_text_str is a final result (will not change). Depending on audio transmission, possible slice_type sequences during recognition are:
0-1-2: Segment start, in progress (may return multiple 1 values), end;
0-2: Segment start, end;
2: Directly returns a complete segment result.
index
Integer
Segment index within the audio stream, starting from 0 and incrementing for each segment.
start_time
Integer
Start time of the segment in the audio stream.
end_time
Integer
End time of the segment in the audio stream.
voice_text_str
String
Transcribed text for the segment, encoded in UTF-8.
language
String
The recognized language type of the segment in the audio stream.For example:zh.
word_size
Integer
Number of words in the segment (word_list array length equals word_size).
word_list
Word Array
Current word list for the utterance. The Word structure is as follows:
word: String, the word content.
start_time: Integer, the start time of the word in the complete audio stream.
end_time: Integer, the end time of the word in the complete audio stream.
stable_flag: Integer, indicates whether the word is stable.
0 indicates that the word may change during subsequent recognition;
1 indicates that the word will not change during subsequent recognition.
speaker_id: Available when real-time speaker diarization is enabled.
-1: Unknown speaker.
>0: Speaker ID.
speaker_name: Identifier of the registered voiceprint speaker.
speaker_segments
SpeakerSegment Array
Returned when real-time speaker diarization is enabled. Indicates the speaker segment results for the current utterance.
speaker_id: Integer, speaker ID.
-1 indicates an unknown speaker;
>0 indicates a speaker ID.
start_time: Integer, segment start time.
end_time: Integer, segment end time.
text: String, text content.
word_start: Integer, start index in the corresponding word_list.
word_end: Integer, end index in the corresponding word_list.
stable_flag: Integer, indicates whether the result is stable.
speaker_name: Identifier of the registered voiceprint speaker.

Handshake Stage

Request Format

During the handshake stage, the client initiates a WebSocket connection request. The request URL format is: Production environment wss://asr-intl.cloud-rtc.com/asr/v2/<appid>?{request parameters}.
SdkAppId and UserSig can be passed in either of the following two ways. Choose one of them:
Method 1 (recommended): Set them in the WebSocket header, with the fields shown in the table below:
key
Required
Value Description
X-TRTC-SdkAppId
Yes
TRTC Application ID. See Application Basic Information.
X-TRTC-UserSig
Yes
TRTC signature. For calculation and usage, see User Authentication. UserID equals the voice_id parameter in the URL.
Replace with your Tencent Cloud registered appid, which can be obtained from API Key Management. The {request parameters} format is:
key1=value1&key2=value2...

Method 2
: Pass them as query parameters in the request URL (sdkappid, usersig; see the parameter description below), for access scenarios such as browsers where the WebSocket header cannot be customized.
sdkappid=xxxxxxxxxxx&usersig=xxxxxxxxxxxxxxx
Parameter descriptions:
Parameter Name
Required
Type
Description
secretid
Yes
String
SecretKey for your Tencent Cloud account. Obtain via API Key Management.
timestamp
Yes
Integer
Current UNIX timestamp in seconds. If the difference from the current time is too large, a signature expiration error will occur. Example: 1745932688.
expired
Yes
Integer
Signature expiration time as UNIX timestamp in seconds. expired must be greater than timestamp and expired - timestamp must be less than 90 days.
nonce
Yes
Integer
Random positive integer, user-generated, up to 10 digits. Example: 8743357.
engine_model_type
Yes
String
Engine model type. Supported values:
bigmodel: large language model version.
language
No
String
When engine_model_type is set to bigmodel, you can specify the audio language. Supported languages include: zh (Chinese), en (English), yue (Cantonese), ar (Arabic), de (German), fr (French), es (Spanish), pt (Portuguese), id (Indonesian), it (Italian), ko (Korean), ru (Russian), th (Thai), vi (Vietnamese), ja (Japanese), tr (Turkish), hi (Hindi), ms (Malay), nl (Dutch), sv (Swedish), da (Danish), fi (Finnish), pl (Polish), cs (Czech), fil (Filipino), fa (Persian), el (Greek), ro (Romanian), hu (Hungarian), mk (Macedonian).
Example value: zh.
Note:
If this field is left empty, the model will automatically detect the language.
speaker_diarization
No
Integer
Configuration option for real-time speaker diarization.
0: Speaker diarization disabled.
1: Speaker diarization enabled.
3: Enables speaker diarization with speaker role verification. Must be used together with the voiceprint_ids parameter.
Default value: 0.
voiceprint_ids
No
String Array
Configuration option for real-time speaker voiceprint matching IDs. The values of this parameter are obtained through the Voiceprint Registration API. This parameter is an array and supports up to 32 voiceprints.
Example: ["550e8400-e29b-41d4-a716-446655440000", "550e8400-e29b-41d4-a716-446655440002"]
voice_id
Yes
String
Globally unique identifier for the audio stream. Each WebSocket connection uses a distinct identifier. Users must generate this value (UUID recommended), up to 128 characters.
Note:
Generate a new voice_id for every WebSocket connection. If recognition or the connection is interrupted (e.g., connection failure, normal end, error code returned), the voice_id becomes invalid. To restart recognition, use a new voice_id.
voice_format
No
Integer
Audio encoding type. Supported value: 1 (PCM).
needvad
No
Integer
0: Disable VAD;
1: Enable VAD. Default is 0.
To ensure recognition quality, if an audio segment exceeds 60 seconds, it will be forcibly segmented at 60s. For audio longer than 60s, enable VAD (voice activity detection) to improve segmentation.
noise_threshold
No
Float
Noise threshold. Default: 2.0. Valid range: [0.0, 4.0]. A larger value makes an audio segment more likely to be classified as noise; a smaller value makes it more likely to be classified as speech.
customization_id
No
String
Custom model ID. If set, the corresponding custom model will be applied.
filter_dirty
No
Integer
Profanity filter (currently supports Mandarin engine). Default is 0.
0: Do not filter;
1: Filter profanity;
2: Replace profanity with "\*".
filter_modal
No
Integer
Filler word filter (currently supports Mandarin engine). Default is 0.
0: No filter;
1: Partial filter;
2: Strict filter.
filter_punc
No
Integer
Sentence-ending period filter (currently supports Mandarin engine). Default is 0.
0: Do not filter;
1: Filter sentence-ending periods.
convert_num_mode
No
Integer
Intelligent conversion to Arabic numerals (currently supports Mandarin engine):
0: No conversion, output Chinese numerals;
1: Convert to Arabic numerals based on context. Default is 1.
word_info
No
Integer
Display word-level timestamps:
0: Do not display;
1: Display, excluding punctuation timestamps.
vad_silence_time
No
Integer
Silence threshold for sentence segmentation. If silence exceeds this value, it is treated as a segment break (mainly for intelligent customer service scenarios, requires needvad = 1). Range: 240–2000 (default 1000), unit: ms. Avoid adjusting this parameter arbitrarily, as it may affect recognition quality.
max_speak_time
No
Integer
Forced segmentation. Range: 5000–90000 ms, default 60000. If speech is continuous, this parameter forces segmentation (result becomes final, slice_type=2). For example, in game commentary scenarios, if the commentator speaks continuously and cannot be segmented, set this parameter to 10000 to receive slice_type=2 callbacks every 10 seconds.
signature
Yes
String
API signature parameter for compatibility with third-party services. If not applicable, use the same value as X-TRTC-UserSig.
sdkappid
No
String
The TRTC application ID, whose meaning is the same as the X-TRTC-SdkAppId in the header. Use this in place of the header approach, for scenarios such as browsers where the WebSocket header cannot be customized.
usersig
No
String
The TRTC signature, computed in the same way as the X-TRTC-UserSig in the header, where UserID equals the voice_id in this request. Use this in place of the header approach.

hotword_list

No
String
Temporary hotword list to improve recognition accuracy.
Single hotword format: "hotword|weight". Each hotword must not exceed 30 characters (or 10 Chinese characters). Supported weights: 1-11 or 100. For example: "Tencent|5" or "ASR|11".
Multiple hotwords must be separated by commas. A maximum of 128 hotwords is supported. For example: "hotword|10,Tencent|5,ASR|11".
Note:
A weight of 11 upgrades the hotword to a super hotword. Use this weight only for important terms that must take effect; configuring too many super hotwords may reduce overall recognition accuracy.
A weight of 100 enables enhanced homophone replacement. For example, if "site|100" is configured, recognition results such as "sight" or "cite", which share the same pronunciation, are forcibly replaced with "site". Use this setting only for important terms that must take effect; configuring too many such hotwords may reduce overall recognition accuracy.
Hotwords cannot contain spaces. For example, use "OpenAIAPI" rather than "OpenAI API".

input_sample_rate
No
String
Supports upsampling 8k PCM audio to 16k for recognition when the engine sample rate does not match, which can improve recognition accuracy. Only 8000 is supported. Note: This parameter applies only to PCM audio. If it is not provided, the engine sample rate is assumed to match the PCM audio sample rate.

Request Response

After the client initiates the connection request, the backend establishes the connection and performs signature verification. If verification succeeds, a confirmation message with code 0 is returned, indicating handshake success. If verification fails, a message with a non-zero code is returned and the connection is closed.
{
"code": 0,
"message": "success",
"voice_id": "faab2b17-ba43-4ea4-be58-a03180ba26dd"
}

Recognition Stage

Upload Data

During recognition, the client continuously uploads binary messages containing audio stream data to the backend. Send a data packet every 40ms, each containing 40ms of audio (1:1 real-time rate). PCM size: 640 bytes for 8k sample rate, 1280 bytes for 16k sample rate. If the interval between sending audio packets exceeds 6 seconds, the engine may fail, and the backend will return an error and disconnect the session.
After uploading the audio stream, the client must send a text message as shown below to notify the backend to end recognition.
{
"type": "end"
}

Receive Messages

While uploading data, the client must synchronously receive real-time recognition results returned by the backend. Example results:

{
"code": 0,
"message": "success",
"voice_id": "23c33398-4da0-4ba7-b0ec-7565b325301d",
"message_id": "756d2992-5a23-488a-b391-9c9c0c36bedf",
"result": {
"slice_type": 0,
"index": 0,
"start_time": 0,
"end_time": 6000,
"voice_text_str": "welcome to ASR.",
"language": "en",
"word_size": 0,
"word_list": []
}
}
After the backend completes recognition of all uploaded audio data, it returns a message with final value 1 and disconnects.
{
"code": 0,
"message": "success",
"voice_id": "faab2b17-ba43-4ea4-be58-a03180ba26dd",
"message_id": "8d9e6337-2c8a-49e2-aee9-9179d71ab7a8",
"final": 1
}
If an error occurs during recognition, the backend returns a message with a non-zero code and disconnects.
{
"code": 4008,
"message": "Backend recognition server audio fragment wait timeout",
"voice_id": "faab2b17-ba43-4ea4-be58-a03180ba26dd",
"message_id": "8d9e6337-2c8a-49e2-aee9-9179d71ab7a8"
}

Developer Resources

SDK

Tencent-RTC SDK for go: Github
Tencent-RTC SDK for python: Github
Tencent-RTC SDK for nodejs: Github
Tencent-RTC SDK for java: Github
Tencent-RTC SDK for rust: Github
Tencent-RTC SDK for cpp: Github

SDK Sample Code

Golang
Python
Node.js
Java
Rust
CPP

Error Codes

Value
Description
4000
Excessive audio data sent. Limit transmission to a maximum of 3 seconds of audio per second.
Note:
Real-time recognition provides instant transcription as you speak. The total audio duration sent per second should be 1 second.
4001
Invalid parameters. See message for details.
4002
Authentication failed. Verify that SdkAppId and UserSig are provided correctly in either the WebSocket headers or URL query parameters (at least one method is required), and that UserSig is valid and has not expired.
4003
AppID service not enabled. Please enable the service in the console.
4004
Resource Package exhausted. Please enable Pay-as-you-go or purchase a Resource Package.
4005
Account suspended due to insufficient balance. Please recharge promptly.
4006
Account concurrency limit exceeded.
4007
Audio decoding failed. Please check that the uploaded audio data format matches the call parameters.
4008
Client did not send audio data for more than 6 seconds.
4009
Client connection disconnected.
4010
Client uploaded unknown text message.
5000
Recognition failed due to high machine load or network jitter. Please initiate a new recognition.
Note:
This issue is typically occasional and can be ignored if infrequent. Simply initiate a new recognition.
5001
Recognition failed due to high machine load or network jitter. Please initiate a new recognition.
Note:
This issue is typically occasional and can be ignored if infrequent. Simply initiate a new recognition.
5002
Recognition failed due to high machine load or network jitter. Please initiate a new recognition.
Note:
This issue is typically occasional and can be ignored if infrequent. Simply initiate a new recognition.