This is a real-time TTS API. Note that it differs from the TencentCloud API in aspects such as parameter style and error codes.
This service uses the WebSocket protocol to synthesize the requested text into audio and synchronously returns the synthesized audio data along with related text information, achieving a "streaming synthesis and playback" effect.
Before using this API, you need to activate the TTS service and go to the API Key Management page to create a key, which generates an AppID, SecretID, and SecretKey. These credentials are used to generate a signature during API calls, and the signature is used for API authentication.
API Requirements
When integrating the real-time TTS API, you must comply with the following requirements.
Content
Description
Voice types
Supports synthesis of Mandarin Chinese, English, and dialects. For voice IDs, see the Voice List page. You can set the corresponding voice ID via the VoiceType API parameter.
Supported Scenarios
General, customer service, emotional, reading, news, and so on. For details, see the Voice List page.
Signature-based authentication mechanism. For details, see Signature Generation.
Response format
Audio information is returned as raw binary data via binary-type frames.
text information is returned as JSON-format data (such as status codes, timestamps, and so on) via text-type frames.
Concurrency limit
By default, a single account is limited to 20 concurrent streams (shared with the real-time TTS API).
If you need to increase the concurrency limit, contact your business manager for consultation.
API Call Process
The API call process is divided into two phases: the handshake phase and the synthesis phase. In both phases, the backend returns a text message, which is a JSON-serialized string. The format is described as follows:
Field Name
Type
Description
code
Integer
The status code. 0 indicates normal, and a non-zero value indicates that an error has occurred.
message
String
Error description. It displays the specific cause of the error when an error occurs. This text may be frequently updated or changed as business evolves or user experience is optimized.
session_id
String
The unique ID of the audio stream. It is generated by the client during the handshake phase and assigned to the call parameters.
request_id
String
The unique ID of the audio stream. It is automatically generated by the server during the handshake phase.
message_id
String
The unique ID of this message.
result
Result
The latest TTS text result.
final
Integer
When this field returns 1, it indicates that the text synthesis is complete. Upon receiving this, the client must actively close the WebSocket connection.
The format of the Result struct for the synthesis output is as follows:
Field Name
Type
Description
subtitles
Subtitle Array
The word list for the current passage, with the Subtitle struct format as follows:
Text: A String-type field containing the content of the character.
BeginTime: An Integer-type field indicating the start time of the character within the entire audio stream.
EndTime: An Integer-type field indicating the end time of the character within the entire audio stream.
BeginIndex: An Integer-type field indicating the start position of the character within the entire text, starting from 0.
EndIndex: An Integer-type field indicating the end position of the character within the entire text, starting from 0.
Phoneme: A String-type field containing the phoneme of the character. (Note: This field may return null, indicating that no valid value can be obtained.)
Handshake Phase
Request Format
During the handshake phase, the client actively initiates a WebSocket connection request. The request URL format is as follows:
Replace `<appid>` with the AppID of your Tencent Cloud registered account. You can obtain the AppID from the API Key Management page. The format of {request_parameters} is as follows:
key1=value2&key2=value2...(Both keys and values must be URL-encoded)
Parameter description:
Parameter Name
Required
Type
Description
Action
Yes
String
The name of the API to call. Value: TextToStreamAudioWS.
AppId
Yes
Integer
The AppId of the account. Ensure that the data type of this field is int.
AccountArea
No
Integer
International account identifier. Value:
0: Indicates a domestic account (default).
1: Indicates an international account.
SecretId
Yes
String
The SecretId of your Tencent Cloud account. You can obtain it on the API Key Management page.
Timestamp
Yes
Integer
The current UNIX timestamp, which records the time when the API request is initiated. For example, 1529223702. If it differs too much from the current time, a signature expiration error will occur.
Expired
Yes
Integer
The validity period of the signature. It is a value that conforms to the UNIX Epoch timestamp specification, measured in seconds. Expired must be greater than Timestamp, and (Expired - Timestamp) must be less than 90 days.
SessionId
Yes
String
The globally unique identifier for TTS. One WebSocket connection corresponds to one identifier. It is generated by the user (UUID is recommended) and can be up to 128 bits in length.
Text
Yes
String
The source text for speech synthesis. The length is uniformly calculated based on UTF-8 encoding. Chinese text supports a maximum of 600 Chinese characters (full-width punctuation marks count as one character). English text supports a maximum of 1800 letters (half-width punctuation marks count as one letter).
VoiceType
No
Integer
Voice ID. For the complete list of voice IDs, see Voice List.
Attention:
If you are using the one-sentence version of VRS, enter the fixed value "200000000".
FastVoiceType
No
String
The voice ID for one-shot VRS. Required when a one-shot VRS voice is used.
Volume
No
Float
The volume level. Its range is [-10, 10], which corresponds to the actual volume. The default value is 0, representing the normal volume level. A larger value indicates a higher volume.
Speed
No
Float
Speech rate. Range: [-2, 6], corresponding to different speech rates:
-2: Indicates 0.6 times.
-1: Indicates 0.8 times.
0: Indicates 1.0 times (default).
1: Indicates 1.2 times.
2: Indicates 1.5 times.
6: Indicates 2.5 times.
If you need a more granular speech rate, you can keep two decimal places, for example, 0.5/1.25/2.81, and so on.
For the conversion between parameter values and actual speech rates, see the code sample.
SampleRate
No
Integer
Audio sample rate
16000: 16k (default)
8000:8k
Codec
Yes
String
Returned audio format
pcm: Returns binary pcm audio.
mp3: Returns binary mp3 audio.
EnableSubtitle
No
Boolean
Whether to enable the timestamp feature. The default value is false.
SegmentRate
No
Integer
Sentence segmentation sensitivity threshold. Value range: [0,1,2]. Default value: 0.
A larger value makes sentence segmentation less likely to occur, and the model tends to segment sentences only based on punctuation marks. It is recommended not to adjust this parameter arbitrarily, as doing so may affect the synthesis quality.
Signature
Yes
String
API signature parameter
Signature Generation
1. Sort all parameters except Signature in lexicographic order, and then concatenate them to obtain the request parameters as follows:
Action=TextToStreamAudioWS&AppId=130046****&Codec=pcm&EnableSubtitle=True&Expired=1688697305&SampleRate=16000&SecretId=*****XcaKs2w4vZw5zTCrHRM7dOwre9*****&SessionId=b78ae3ba-1ba5-11ee-a106-768645a5c72a&Speed=0&Text=Welcome to Tencent Cloud Real-time TTS&Timestamp=1688610905&VoiceType=101001&Volume=0
Then, concatenate the request method and the domain address to obtain the signature original text. The format of the signature original text is as follows:
GETtts.cloud.tencent.com/stream_ws?Action=TextToStreamAudioWS&AppId=130046****&Codec=pcm&EnableSubtitle=True&Expired=1688697305&SampleRate=16000&SecretId=*****XcaKs2w4vZw5zTCrHRM7dOwre9*****&SessionId=b78ae3ba-1ba5-11ee-a106-768645a5c72a&Speed=0&Text=Welcome to Tencent Cloud Real-time TTS&Timestamp=1688610905&VoiceType=101001&Volume=0
2. Encrypt the signature original text using the SecretKey with HMAC-SHA1, and then perform base64 encoding. For example, for the signature original text from the previous step, SecretKey=*****SkqpeHgqmSz*****, encrypt it using the HMAC-SHA1 algorithm and then perform base64 encoding:
Base64Encode(HmacSha1("GETtts.cloud.tencent.com/stream_ws?Action=TextToStreamAudioWS&AppId=130046****&Codec=pcm&EnableSubtitle=True&Expired=1688697305&SampleRate=16000&SecretId=*****XcaKs2w4vZw5zTCrHRM7dOwre9*****&SessionId=b78ae3ba-1ba5-11ee-a106-768645a5c72a&Speed=0&Text=Welcome to Tencent Cloud Real-time TTS&Timestamp=1688610905&VoiceType=101001&Volume=0", "*****SkqpeHgqmSz*****"))
The Signature value obtained is:
U6O4dLlz3mgj6ONKUkO/0g4u5pk=
3. After URL-encoding the Signature value (URL encoding is mandatory, and the encoding function must support encoding special characters such as + and =; otherwise, authentication failures may occur intermittently), concatenate it to obtain the URL as follows:
wss://tts.cloud.tencent.com/stream_ws?Action=TextToStreamAudioWS&AppId=130046****&Codec=pcm&EnableSubtitle=True&Expired=1688697305&SampleRate=16000&SecretId=*****XcaKs2w4vZw5zTCrHRM7dOwre9*****&SessionId=b78ae3ba-1ba5-11ee-a106-768645a5c72a&Speed=0&Text=Welcome to Tencent Cloud Real-time TTS&Timestamp=1688610905&VoiceType=101001&Volume=0&Signature=4Lv%2Bk6y6v5VRT/iBFPU%2BGyfeiy0%3D
4. URL-encode the Text value using urlencode, and replace the original text value with it:
After the client initiates a connection request, the backend establishes the connection and performs signature verification. If the verification succeeds, the backend returns a confirmation message with a code value of 0, indicating a successful handshake. If the verification fails, the backend returns a message with a non-zero code value and disconnects the connection.
After a successful handshake, the process enters the synthesis phase, where the client receives the synthesized binary audio data and text data (such as timestamps).
Receives a message
The client must synchronously receive the binary audio data and text data returned by the backend. An example of the text data is as follows:
After the backend finishes synthesizing all audio data, it finally returns a message with the final value set to 1. Upon receiving this message, the client must actively disconnect the WebSocket connection.
