# Online TTS WebAPI Document

# Description of the Interface

The stream interface for Online TTS converts text information into acoustic information, and provides a number of distinctive speakers (acoustic library) for you to choose from. This function is a common interface provided to developers through Websocket API. Websocket API can achieve streaming, applicable to service scenarios that require streaming data transmission. Compared to SDK, API is featured as lightweight and cross-language; compared to the HTTP API, the Websocket API protocol has the advantage of natively supporting cross-domain.

Available Voices

We provide a variety of different voices in multiple languages for TTS service.

• If a minority language is used, unicode encoding must be used and tte = unicode (unicode is utf16 little endian encoding) should be set for uploading text encoding;

• Only after the minority language speaker is enabled at the console first, can the minority language synthesis be achieved, otherwise, the error 11200 will be reported.

# Interface Demo

Please click here to download At present, only the demos for some development languages are provided. For other languages, please carry out the development referring to the interface document below.

# Requirements for the Interface

The following requirements should be met if the stream API for speech synthesis online is integrated.

# Interface Calling Flow

• Calculate the signature based on hmac-sha256 through the interface key, and send the Websocket protocol handshake request to the server-side. Refer to [Interface Authentication](#Interface Authentication) below for details.

• After the handshake succeeds, the client can upload and receive data simultaneously through the Websocket connection. After the data is completely uploaded, the client should upload the end-of-data marker once. Refer to [Interface Data Transmitting and Receiving](#Interface Data Transmitting and Receiving) below.

• Disconnect the Websocket connection after receiving all the returned indicators of the results from the server-side.

*Note: Observe the following cautions when using Websocket

1. The websocket-version supported by the server-side is 13. Ensure the framework used by the client supports this version.

2. The type of all frames returned by the server-side is TextMessage, which corresponds to opcode = 1 in the protocol frame of the native websocket. Please ensure that the frame type parsed by the client must be this type. Otherwise, try to upgrade the client frame version or replace the technical framework.

3. If there is a framing problem, namely, a json data packet is returned to the client by multiple frames, causing the client's failure in parsing the json. In most cases, this is because the client's framework has a problem in parsing the websocket protocol. Therefore, try to upgrade the framework version first, or replace the technical framework in the event of this problem.

4. If it is necessary to close the connection after the client session is over, try to ensure that the error code sent to the server-side is the error code 1000 of websocket (ignore this requirement if the client framework is not provided with an interface for sending the error code upon closing of the session).

# Whitelist

The IP whitelist is disabled by default, which means this service does not restrict from calling IP. When calling this business interface:

• If the IP whitelist is disabled, the IP is considered as unrestricted for the interface, and it will not be checked.

• If the IP whitelist is enabled, the server-side will check if the caller's IP is included in the IP whitelist. For the requests from an IP that is not configured in the whitelist, the server-side will reject to provide services.

Rules for IP Whitelist

• Perform edit at console-IP whitelist for the corresponding service, and the edited content will become valid about five minutes after saved.

• The IP whitelists should be set separately for different services of different APPIDs.

• The IP whitelist should be set to Internet IP instead of LAN IP

• If {"message":"Your IP address is not allowed"} is returned during the handshake phase, it indicates that the server refuses to provide the service because the IP whitelist is set incorrectly or is still invalid.

# Interface Authentication

In the handshake phase, the requester is required to sign the request, and the server-side verifies the validity of the request through the signature.

# Authentication Method

By adding authentication-related parameters after the request URL. Sample url：

ws://eu-central-1.aicloudapi.com/v2/tts?authorization=aG1hYyB1c2VybmFtZT0iZGE0ZjMyOWUyZmQwMGQ1NjE4NjVjNjRkZjU3NDNiMjAiLCBhbGdvcml0aG09ImhtYWMtc2hhMjU2IiwgaGVhZGVycz0iaG9zdCBkYXRlIHJlcXVlc3QtbGluZSIsIHNpZ25hdHVyZT0ic1RtbzRobDBMdmRLWTRLRjltcGJKV0htRFFzNC8xZ2ZPdUgwZnBZbVdnbz0i&date=Thu%2C%2001%20Aug%202019%2001%3A53%3A21%20GMT&host=eu-central-1.aicloudapi.com

Authentication Parameters:

· Rules for Generation of date Parameters

date must be based on UTC+0 or GMT time zone, in RFC1123 format (Thu, 01 Aug 2019 1:53:21 AM GMT).
The server-side will check the clock skew for Date, allowing the maximum deviation of 300 seconds. Once such value is exceeded, the request will be rejected.

· Rules for Generation of authorization Parameters

1）Get the interface keys APIKey and APISecret.

2）The format of the parameter authorization before encoded with base64(authorization_origin) is as follows.

api_key="$api_key",algorithm="hmac-sha256",headers="host date
request-line",signature="$signature"

Where, api_key is the APIKey got from the console, algorithm is an encryption algorithm (supports hmac-sha256 only), and headers are the parameters involved in signature. signature is a string obtained by signing the parameter participating in signature using the encryption algorithm and encoding it with base64. See below for details.

*Note: headers are the parameters participating in signature. Please note that they are fixed parameter names ("host date request-line"), instead of the values of these parameters.

3）The rules for the original field of signature (signature_origin) are as follows:

The original field of signature is composed of three parameters, i.e. host, date and request-line which are concatenated in a certain format. The concatenation format is (\n is a new line character, ':' is followed by a space):

host: $host\ndate: $date\n$request-line

Suppose

request url = ws://eu-central-1.aicloudapi.com/v2/tts
date = Thu, 01 Aug 2019 01:53:21 GMT

Then, the original field of signature (signature_origin) is:

host: eu-central-1.aicloudapi.com
date: Thu, 01 Aug 2019 01:53:21 GMT
GET /v2/tts HTTP/1.1

4）Sign the signature_origin using the hmac-sha256 algorithm in combination with apiSecret, to obtain the signed summary, i.e. signature_sha.

signature_sha=hmac-sha256(signature_origin,$apiSecret)

Where, apiSecret is the APISecret got from the console.

5）Encode the signature_sha with base64 to get the final signature.

signature=base64(signature_sha)

Suppose

APISecret = secretxxxxxxxx2df7900c09xxxxxxxx
date = Thu, 01 Aug 2019 01:53:21 GMT

Then, the signature is

signature=sTmo4hl0LvdKY4KF9mpbJWHmDQs4/1gfOuH0fpYmWgo=

6）According to the above information, concatenate the string of authorization before it is encoded with base64（authorization_origin）. See the example below.

api_key="keyxxxxxxxx8ee279348519exxxxxxxx", algorithm="hmac-sha256",
headers="host date request-line",
signature="sTmo4hl0LvdKY4KF9mpbJWHmDQs4/1gfOuH0fpYmWgo="

*Note: headers are the parameters participating in signature. Please note that they are fixed parameter names ("host date request-line"), instead of the values of these parameters.

7）Finally, encode the authorization_origin with base64 to get the authorization parameter.

authorization = base64(authorization_origin)
Example:
authorization=aG1hYyB1c2VybmFtZT0iZGE0ZjMyOWUyZmQwMGQ1NjE4NjVjNjRkZjU3NDNiMjAiLCBhbGdvcml0aG09ImhtYWMtc2hhMjU2IiwgaGVhZGVycz0iaG9zdCBkYXRlIHJlcXVlc3QtbGluZSIsIHNpZ25hdHVyZT0ic1RtbzRobDBMdmRLWTRLRjltcGJKV0htRFFzNC8xZ2ZPdUgwZnBZbVdnbz0i

# Examples of Authentication (golang)

 //@hosturl :  like  ws://eu-central-1.aicloudapi.com/v2/tts
    //@apikey : apiKey
    //@apiSecret : apiSecret
    func assembleAuthUrl(hosturl string, apiKey, apiSecret string) string {
        ul, err := url.Parse(hosturl)
        if err != nil {
            fmt.Println(err)
        }
        //Signing Date:
        date := time.Now().UTC().Format(time.RFC1123)
        //fields participating in signature: host ,date and request-line
        signString := []string{"host: " + ul.Host, "date: " + date, "GET " + ul.Path + " HTTP/1.1"}
        //String consisting of concatenated signatures
        sgin := strings.Join(signString, "\n")
        //Signature results
        sha := HmacWithShaTobase64("hmac-sha256", sgin, apiSecret)
        //Construct request parameters,and urlencoding is not required now
        authUrl := fmt.Sprintf("api_key=\"%s\", algorithm=\"%s\", headers=\"%s\", signature=\"%s\"", apiKey,
            "hmac-sha256", "host date request-line", sha)
        //Encode the request parameters with base64
        authorization:= base64.StdEncoding.EncodeToString([]byte(authUrl))
        v := url.Values{}
        v.Add("host", ul.Host)
        v.Add("date", date)
        v.Add("authorization", authorization)
        //Add the encoded string url encode after url
        callurl := hosturl + "?" + v.Encode()
        return callurl
    }

# Authentication Results

If the handshake succeeds, an HTTP 101 status code will be returned, indicating that the protocol upgrade is successful; if the authentication fails, different HTTP Code status codes will be returned, depending on the type of errors, along with error messages. See the detailed description of errors in the table below.

Example of returned messages upon failure of handshake:

HTTP/1.1 401 Forbidden
Date: Thu, 06 Dec 2018 07:55:16 GMT
Content-Length: 116
Content-Type: text/plain; charset=utf-8
{
	"message": "HMAC signature does not match"
}

# Interface Data Transmitting and Receiving

After the handshake succeed, the connection between the client and the server-side will be established, through which, the client can simultaneously upload and receive data.

The client only sends text data and parameters once per session, and when the server-side has a recognition result, it will push the result to the client. When the engine's data is completely synthesized, an end-of-data marker will be returned, specifically as follows:

{
  "data":{
      ....#other parameters
      "status":2
  }  
}

# Request Parameters

All the request data is json string.

# Description of Common Parameters (common)

# Description of Business Parameters (business)

# Description of Business Parameters (data)

Examples of request parameters:

  		{  
            "common":{
                "app_id":"123456"
            },
        	"business":{
        	     "vcn":"xiaoyan",
        	     "aue":"raw",
        	     "speed":"50"
        	},
        	"data":{
        	    "status":2,
                "encoding":"gbk",
                "text":"exSI6ICJlbiIsCgkgICAgInBvc2l0aW9uIjogImZhbHNlIgoJf..."    
        	}
        }

Example of end-of-data-upload marker：

	{
    	"data":{
      		"status":2
    	}
    }

Description of Returned Parameters：

Examples of Returned Parameters

    {
        "code":0,
        "message":"success",
        "sid":"ttsxxxxxxxxxxx",
        "data":{
            "audio":"QAfe..........",
            "ced":"14",
            "status":2
        }
    }

# Notes

1. The server-side may return a frame with empty data, and the error code is 0. The client can directly ignore this type of frames which are not parsed.
2. The frames returned by the synthesis has a large length, and the server-side may return a message to the client by multiple websocket frames. In this case, the client should joint these frames. Of course, this logic has been achieved in most of frameworks, but there may still be some frameworks in which this logic is not made, resulting in failure to parse.
3. The synthesized audio is a meaningless audio, which is mostly because the character encoding format used by the client is not consistent with the parameters. Please make sure that the value passed by tte is consistent with the text encoding format.
4. The synthesized audio effect is not the desired effect. This can be solved by changing the speaker, (some speakers requires permission!)
5. Unicode encoding must be used for the texts in minority languages, and tte = Unicode.

# Error Code

# Demos

API demo java

API demo python3

API demo go

API demo nodejs

API demo C#

# Q&A

# 11200 authorization error is reported for WebAPI online synthesis？

Answer: This problem is generally caused by the use of an unauthorized speaker. Please go to the console to check if the speaker is not added or the authorization has expired. Besides, if the total synthesis interaction exceeds the upper limit, the error 11200 is also be reported.

# Audio formats supported by WebAPI online synthesis to save？

Answer: It supports to save audios in pcm, mp3 and speex format.

# What is the limit for the bytes in the online speech synthesis?

Answer: The WebAPI interface is limited to transfer 8000 bytes at a time. For the ultra-long text, it is segmented as per paragraph, and multiple synthesis requests are made.