# API Document for Machine Translation

# Description of the Interface

Machine Translation, based on the machine translation engine independently developed by iFLYTEK, has been able to support more than 10 languages like English, Japanese, French, Spanish and Russian (including Uighur and Tibetan which are supported but not externally available at present), presenting a high translation quality. It has been applied on the iFLYTEK Translator, and achieved excellent results. Please refer to[List of Languages](#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 AI 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.

Currently only Coversion between Simplified Chinese and Japanese, Korean, Vietnamese, Thai are supported in Machine Translation Beta Version. Please stay tuned.

# Interface Demos

Interface Demos Please click here 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.

Content Description
Transmission Mode http[s] (https is strongly recommended for improving the security)
Request URL http[s]: //its-api-sg.xf-yun.com/v2/its
Note: The server IP is not fixed. To ensure the stability of your interface, please call the interface by using the domain name instead of by specifying the IP.
Request Line POST /v2/its HTTP/1.1
Interface Authentication Signature mechanism, refer to[Interface Authentication](#Interface Authentication)
Character Encoding UTF-8
Response Format Unified JSON format
Development Language Any language which allows to make HTTP requests for iFLYTEK cloud services.
Scope of Application Any operating system except browsers for which the interface should be called through the backend because cross-domain is not supported.
Text Length The length of a single text should not exceed 256 characters.
Each of a Chinese character, an English letter, a punctuation mark, etc. is counted as one character.
Text Size The size after base64-encoded should not exceed 1024 bytes (about 256 Chinese characters)
Text Language Supports more than 10 languages. Refer to [List of Languages](#List of Languages)for details.

# 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 configured by the iFLYTEK Open Platform. 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:itrans.xfyun.cn
    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:

Parameter Type Required Description Example
Host string Yes Request host itrans.xfyun.cn
Date string Yes Current timestamp, in RFC1123 format ("EEE, dd MMM yyyy HH:mm:ss z") Wed, 20 Nov 2019 03:14:25 GMT
Digest string Yes Encrypted request body
SHA-256=Base64(SHA256(request body))
Refer to [Request Parameters](#Request Parameters)
SHA-256=2iwDpX6....
Authorization string Yes Information related to the signature encoded with base64 (the signature is based on hamc-sha256 calculation.) Refer to the content below
  • 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 the APIKey obtained in the console (which is a 32-bit string, and can be viewed on the machine translation page of the console), 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://its-api-sg.xf-yun.com/v2/its<br>”<br>
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(请求body))
    Example:digest: SHA-256=2iwDpX6yAoQAeeAhT4yi3Tx9XRaWvAAvn3L8Ip6fdpA=

2)Construct the original field of signature (signature_origin)

    host: itrans.xfyun.cn
    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.

HTTP Code Description Error Message Solution
401 Request parameters of authorization are not available {“message”:”Unauthorized”} Check if authorization parameters are available. Refer to [Detailed Rules for Generation of Authorization Parameters](#Authorization Parameters)
401 The resolution of signature parameters fails. {“message”:”HMAC signature cannot be verified”} Check if all signature parameters are available and correct, and if the copied api_key is correct.
401 The signature authentication fails. {“message”:”HMAC signature does not match”} There are many possible reasons for failure of signature authentication.
1. Check if api_key and api_secret are correct.
2. Check whether the parameters, i.e. host, date and request-line for calculation of signature are concatenated according to protocol requirements.
3. Check if the base64 length of signature is normal (normally 44 bytes).
403 The authentication of clock skew fails. {“message”:”HMAC signature cannot be verified, a valid date or x-date header is required for HMAC Authentication”} Check if the server time is standard. This error is reported when the deviation is more than 5 minutes.

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.

Parameter Name Type Required Description
common object Yes Used to upload common parameters
common.app_id string Yes APPID information applied from the platform
business object Yes Used to upload business parameters
business.from string Yes Source language
business.to string Yes Target language
data object Yes Used to upload text to be translated
data.text bytes Yes Text data, UTF-8 character set, base64-encoded
The size is required not to be more than 1024 bytes after encoding (about 256 Chinese characters).
Note: The size will be increased by about 1/3 after base64-encoded.

Examples of request parameters:

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

# Returned Parameters

Parameter Name Type Description
sid string Current session id
code int Returned code, 0 means success, and any other code means failure. Refer to[Error Codes](#Error Codes)for details.
message string Description message
data object Translation result. See the following for details.
If an interface error is reported (the code is not 0), this field will not be available.

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

Parameter Type Description
from string Source language
to string Target language
trans_result object Translation result
trans_result.src string Source text
trans_result.dst string Target text

Example of returned parameters:

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

# Error Codes

HTTP Code Description Error Message
10106 Invalid message content ErrorContentInvalid
10700 Engine connection failed ErrorConnectFail

# List of Languages

Language Parameter
Mandarin Chinese cn
English en
Yi language ii
Cantonese yue
Japanese ja
Russian ru
French fr
Spanish es
Arabic ar
Uighur Not externally available at present
Tibetan Not externally available at present

# Demos

Machine translation demo python3 (opens new window)

Machine translation demo java (opens new window)

# 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.

# Contributing to the Documentation

Is something missing/incorrect? Please let us know by contacting openplatform@iflytek.com. If you know how to fix it straight away, don’t hesitate to create a request (opens new window) to help us improve our document.