# API Document for Machine Translation

# Description of the Interface

Machine Translation, based on the optimized machine translation engine，presenting a high translation quality. Please refer to List of Languages for details. By calling this interface, the text in source language can be converted into the text in target language. This function provides developers with a common interface through HTTP API. HTTP API is applicable to service scenarios with primary interactive data transmission. Compared with SDK, API is featured as light weight and cross-language. In addition, note that the HTTP API protocol used for this interface does not support cross-domain.

# Interface Demos

Please click here to download demos.
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 machine translation is integrated.

# Interface Calling Flow

• Calculate the signature based on hamc-sha256 through the interface key, and put the signature and other parameters in HTTP Request Header. Refer to [Interface Authentication](#Interface Authentication) below for details.

• Put the request parameters and image data in Http Request Body and submit them in POST form. Refer to [Request Parameters](#Request Parameters)below for details.

• Receive the result returned from the server-side after the HTTP request is sent to the server-side.

# 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 whether the caller's IP is included in the IP whitelist. For the requests from IPs that are not configured in the whitelist, the server-side will reject to provide the service.

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 WAN IP instead of LAN IP.

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

# Authentication

When calling the business interface, the HTTP request must be signed, and the server-side identifies the user through the signature and authenticates its legality.

# Authentication Method

Http Request Configure the following authentication parameters in HTTP Request Header for the authentication of authorization, where the signature information is put in the request header's Authorization. Example of request header:

Content-Type:application/json
Accept:application/json,version=1.0
Host:eu-central-1.aicloudapi.com/v2/its
Date:Wed, 20 Nov 2019 03:14:25 GMT
Digest:SHA-256=2iwDpX6yAoQAeeAhT4yi3Tx9XRaWvAAvn3L8Ip6fdpA=
Authorization:api_key="your_key", algorithm="hmac-sha256",
headers="host date request-line digest", signature="$signature"

# Authentication Parameters

• Date parameter generation rules:

Date must be based on UTC+0 or GMT time zone, in RFC1123 format (Wed, 20 Nov 2019 03:14:25 GMT). The server-side will check the clock skew for the Date, allowing the maximum deviation of 300 seconds. Once such value is exceeded, the request will be rejected.

• Authorization parameter generation format:

Authorization: api_key=\"your_key\", algorithm=\"hmac-sha256",
headers="host date request-line digest", signature="$signature"

Example：Authorization: api_key="apikeyXXXXXXXXXXXXXXXXXXXXXXXXXX",
algorithm="hmac-sha256", headers="host date request-line digest",
signature="XwMFU8JKrxdDeVLpplLua9Rjcv/IlaS5tWbmXg0eM80="

Where, api_key is a 32-bit string. api_key="apikeyXXXXXXXXXXXXXXXXXXXXXXXXXX" is taken as an example here. Algorithm is an encryption algorithm (supports hmac-sha256 only), and headers are the parameters involved in signature.
Signature is a string which is base64-encoded after using the encryption algorithm to sign the parameters participating in signature, see below for details.

• Signature parameter generation rules:

The signature' original field is composed of four parameters: host, date, request-line and digest 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\ndigest: $digest

For example, if the requesting url is
"https://eu-central-1.aicloudapi.com/v2/its"

The requesting body should be:
{"common":{"app_id":"5dXXXXXX"},"business":{"from":"cn","to":"en"},"data":{"text":"5Lit5Y2O5Lq65rCR5YWx5ZKM5Zu95LqOMTk0OeW5tOaIkOeriw=="}}

Then, the steps to generate signature are as follows:

1. Perform SHA256 calculation on body, write the string obtained after the calculation result is Base64-encoded behind "SHA-256=", which is namely the value of the field "digest".

digest: SHA-256=Base64(SHA256(request body))
Example:digest: SHA-256=2iwDpX6yAoQAeeAhT4yi3Tx9XRaWvAAvn3L8Ip6fdpA=

2）Construct the original field of signature (signature_origin)

host:eu-central-1.aicloudapi.com 
date: Wed, 20 Nov 2019 03:14:25 GMT
POST /v2/its HTTP/1.1
digest: SHA-256=2iwDpX6yAoQAeeAhT4yi3Tx9XRaWvAAvn3L8Ip6fdpA=

3）Sign the "signature_origin" using hmac-sha256 algorithm in combination with apiSecret. The signed summary "signature_sha apiSecret" can be viewed in the machine translation page of the console. "apisecretXXXXXXXXXXXXXXXXXXXXXXX" is taken as an example here.

signature_sha=hmac-sha256(signature_origin,$apiSecret)

4）Encode "signature_sha" with base64, to obtain the final signature.

signature=base64(signature_sha)

Example：d4kHthlsRTE/YAjFnuJiNs1u/cXOmSI4fAvKwLawQ+8=

# Examples of Authentication (golang)

package main
    import (
        "crypto/hmac"
        "crypto/sha256"
        "encoding/base64"
        "fmt"
        "time"
        "github.com/valyala/fasthttp"
    )
    const (
        // Supported algorithm
        Algorithm = "hmac-sha256"
        // Version protocol
        HttpProto = "HTTP/1.1"
        // Supposed secret
        Secret = "12345"
    )
    func assemblyRequestHeader(req *fasthttp.Request, apiKey, host, uri string, body []byte) {
        req.Header.Set("Content-Type", "application/json")
        // Set the request header, where, Host Date must have:
        req.Header.Set("Host", host)
        // date must be based on utc time zone, and the deviation between it and the service time  should not exceed 300s
        currentTime := time.Now().UTC().Format(time.RFC1123)
        req.Header.Set("Date", currentTime)
        // Perform  sha256 signature on body to generate digest header. body must be authenticated for POST requests.
        digest := "SHA-256=" + signBody(body)
        req.Header.Set("Digest", digest)
        // Signature is generated according to the content of request header.
        sign := generateSignature(host, currentTime,"POST", uri, HttpProto, digest,Secret)
        // Assemble Authorization header
        authHeader := fmt.Sprintf(`api_key="%s", algorithm="%s", headers="host date request-line digest", signature="%s"`, apiKey, Algorithm, sign)
        req.Header.Set("Authorization", authHeader)
    }
    func generateSignature(host, date, httpMethod, requestUri, httpProto, digest string, secret string) string {
        // If it is not request-line, the  header name should be followed by ASCII colon: and ASCII space, and header value
        var signatureStr string
        if len(host) != 0 {
            signatureStr = "host: " + host + "\n"
        }
        signatureStr += "date: " + date + "\n"
        // If it is request-line, use  http_method request_uri http_proto
        signatureStr += httpMethod + " " + requestUri + " " + httpProto + "\n"
        signatureStr += "digest: " + digest
        return hmacsign(signatureStr, secret)
    }
    func hmacsign(data, secret string) string {
        mac := hmac.New(sha256.New, []byte(secret))
        mac.Write([]byte(data))
        encodeData := mac.Sum(nil)
        return base64.StdEncoding.EncodeToString(encodeData)
    }
    func signBody(data []byte) string {
        // Perform sha256 signature
        sha := sha256.New()
        sha.Write(data)
        encodeData := sha.Sum(nil)
        // Through base64 conversion
        return base64.StdEncoding.EncodeToString(encodeData)
    }

Authentication Results

If the authentication is successful, an HTTP 200 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 authentication:

HTTP/1.1 401 Forbidden
Date: Wed, 20 Nov 2019 03:14:25 GMT
Content-Length: 116
Content-Type: text/plain; charset=utf-8
{
	"message": "HMAC signature does not match"
}

# Request Parameters

When calling the business interface, it is required to configure the following parameters in HTTP Request Body, and all the request data is json string.

Examples of request parameters:

    {
        "common":{
            "app_id":"xxxxxxxx"
        },
        "business":{
            "from":"cn",
            "to" :"en"
        },
        "data":{
            "text":"5LuK5aSp5aSp5rCU5oCO5LmI5qC377yf"
        }
    }

# Returned Parameters

The translation result is in the "result" field of the "data" field. The "result" field contains the following information:

Example of returned parameters:

{
  "code": 0,
  "message": "success",
  "sid": "its....",
  "data": {
    "result": {
      "from": "cn",
      "to": "en",
      "trans_result": {
        "dst": "Hello World ",
        "src": "你好世界"
      }
    }
  }
}

# Error Codes

# List of Languages

# Demos

Machine translation demo java

Machine translation demo python3

Machine translation demo go

Machine translation demo nodejs

Machine translation demo C#

# Q&A

# What are the main functions of machine translation?

Answer: It supports the text-to-text machine translation.

# What application platforms does machine translation support?

Answer: It only supports the WebAPI interface at present.