# 机器翻译niutrans API 文档

# 接口说明

机器翻译2.0，基于小牛翻译自主研发的多语种机器翻译引擎，已经支持包括英、日、韩、法、西、俄等100多种语言，详细请参照 语种列表 。通过调用该接口，将源语种文字转化为目标语种文字。可在 这里 体验效果。
该能力是通过HTTP API的方式给开发者提供一个通用的接口。HTTP API适用于一次性交互数据传输的AI服务场景，相较于SDK，API具有轻量、跨语言的特点。另外，请注意该接口使用的HTTP API协议不支持跨域。

注： 原老版本 机器翻译1.0（ http://openapi.openspeech.cn/webapi/its.do ）的老用户，烦请尽快使用最新的机器翻译2.0接口。机器翻译1.0我们会在近几个月内渐渐停止维护，为了您的服务稳定，请马上切换。

# 接口Demo

示例demo 请点击 这里 下载。
目前仅提供部分开发语言的demo，其他语言请参照下方接口文档进行开发。
也欢迎热心的开发者到 讯飞开放平台社区 分享你们的demo。

# 接口要求

集成机器翻译2.0 时，需按照以下要求。

# 接口调用流程

• 通过接口密钥基于hamc-sha256计算签名，将签名以及其他参数放在Http Request Header中。详见下方 鉴权认证 。
• 将请求参数以及图片数据放在Http Request Body中，以POST表单的形式提交，详见下方 请求参数 。
• 向服务器端发送Http请求后，接收服务器端的返回结果。

# 白名单

默认关闭IP白名单，即该服务不限制调用IP。
在调用该业务接口时

• 若关闭IP白名单，接口认为IP不限，不会校验IP。
• 若打开IP白名单，则服务端会检查调用方IP是否在讯飞开放平台配置的IP白名单中，对于没有配置到白名单中的IP发来的请求，服务端会拒绝服务。

IP白名单规则

• 在 控制台-相应服务的IP白名单处编辑，保存后五分钟左右生效。
• 不同Appid的不同服务都需要分别设置IP白名单。
• IP白名单需设置为外网IP，请勿设置局域网IP；
• 如果握手阶段返回{"message":"Your IP address is not allowed"}，则表示由于IP白名单配置有误或还未生效，服务端拒绝服务。

# 鉴权认证

在调用业务接口时，须对HTTP请求进行签名，服务端通过签名来识别用户并验证其合法性。

# 鉴权方法

在Http Request Header中配置以下鉴权参数用于授权认证，其中签名信息放在请求头Authorization中。
Header示例：

    Content-Type:application/json
    Accept:application/json,version=1.0
    Host:ntrans.xfyun.cn
    Date:Mon, 18 Mar 2019 08:32:07 GMT
    Digest:SHA-256=MGNjNThlMTU3ZWNmYjU4YTlhNTAwNDI5NWE4NTBmNWM5ZTMwMmM5OGZiNzE2ODY4ZjM2ZTQxYmNjMzkzZjIwYQ==
    Authorization:api_key="your_key", algorithm="hmac-sha256", headers="host date request-line digest", signature="$signature"

鉴权参数：

• date参数生成规则：

date必须是UTC+0或GMT时区，RFC1123格式(Tue, 30 Jul 2019 08:39:29 GMT)。
服务端会对Date进行时钟偏移检查，最大允许300秒的偏差，超出偏差的请求都将被拒绝。

• Authorization参数生成格式：

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

其中 api_key 是在控制台获取的APIKey（在控制台的拍照速算识别页面可查看，为32位字符串。）,这里以api_key="apikeyXXXXXXXXXXXXXXXXXXXXXXXXXX"为例
algorithm 是加密算法（仅支持hmac-sha256），headers 是参与签名的参数。
signature 是使用加密算法对参与签名的参数签名后并使用base64编码的字符串，详见下方。

• signature参数生成规则：

signature原始字段由 host，date，request-line，digest四个参数按照格式拼接成
拼接的格式为(\n为换行符，’:’后面有一个空格)： host: $host\ndate: $date\n$request-line\ndigest: $digest

例如，请求的url为：https://ntrans.xfyun.cn/v2/ots<br>
请求的body为：{"common":{"app_id":"5dXXXXXX"},"business":{"from":"cn","to":"en"},"data":{"text":"5Lit5Y2O5Lq65rCR5YWx5ZKM5Zu95LqOMTk0OeW5tOaIkOeriw=="}}

则signature生成步骤如下：

1）对请求body进行SHA256计算，把计算结果进行Base64编码后的字符串写在"SHA-256="后，即字段digest的值

    digest: SHA-256=Base64(SHA256(请求body))
    例:digest: SHA-256=zUoH6Uf3m5KWEV4aaH7nNFQRCpJG5NWh5RUKa41mGRo=

2）构建signature原始字段（signature_origin）

    host: ntrans.xfyun.cn
    date: Tue, 30 Jul 2019 08:39:29 GMT
    POST /v2/ots HTTP/1.1
    digest: SHA-256=zUoH6Uf3m5KWEV4aaH7nNFQRCpJG5NWh5RUKa41mGRo=

3）使用hmac-sha256算法结合apiSecret对signature_origin签名，获得签名后的摘要signature_sha apiSecret在控制台的拍照速算识别页面可查看，这里以apisecretXXXXXXXXXXXXXXXXXXXXXXX为例。

    signature_sha=hmac-sha256(signature_origin,$apiSecret)

4）使用base64编码对signature_sha进行编码，获得最终的signature

    signature=base64(signature_sha)
    例：wsjJ7v3nlsQcxLoeyB81MAGEN7NS31lxgw6z9VzHGwg=

# 鉴权示例(golang)

    package main
    import (
        "crypto/hmac"
        "crypto/sha256"
        "encoding/base64"
        "fmt"
        "time"
        "github.com/valyala/fasthttp"
    )
    const (
        // 支持的算法
        Algorithm = "hmac-sha256"
        // 版本协议
        HttpProto = "HTTP/1.1"
        // 假定的secret
        Secret = "12345"
    )
    func assemblyRequestHeader(req *fasthttp.Request, apiKey, host, uri string, body []byte) {
        req.Header.Set("Content-Type", "application/json")
        // 设置请求头 其中Host Date 必须有
        req.Header.Set("Host", host)
        // date必须是utc时区，且不能和服务器时间相差300s
        currentTime := time.Now().UTC().Format(time.RFC1123)
        req.Header.Set("Date", currentTime)
        // 对body进行sha256签名,生成digest头部，POST请求必须对body验证
        digest := "SHA-256=" + signBody(body)
        req.Header.Set("Digest", digest)
        // 根据请求头部内容，生成签名
        sign := generateSignature(host, currentTime,"POST", uri, HttpProto, digest,Secret)
        // 组装Authorization头部
        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 {
        // 不是request-line的话，则以header名称,后跟ASCII冒号:和ASCII空格，再附加header值
        var signatureStr string
        if len(host) != 0 {
            signatureStr = "host: " + host + "\n"
        }
        signatureStr += "date: " + date + "\n"
        // 如果是request-line的话，则以 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 {
        // 进行sha256签名
        sha := sha256.New()
        sha.Write(data)
        encodeData := sha.Sum(nil)
        // 经过base64转换
        return base64.StdEncoding.EncodeToString(encodeData)
    }

# 鉴权结果

如果鉴权失败，则根据不同错误类型返回不同HTTP Code状态码，同时携带错误描述信息，详细错误说明如下：

认证失败返回示例：

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"
}

# 请求参数

在调用业务接口时，都需要在 Http Request Body 中配置以下参数，请求数据均为json字符串。

请求参数示例：

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

# 返回参数

翻译结果在data字段的result字段中。
result字段具体信息如下：

返回参数示例：

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

# 错误码

备注：如出现下述列表中没有的错误码，可到 这里 查询。

# 语种列表

可在 这里 在线体验效果。

# 调用示例

机器翻译2.0 demo python3语言

机器翻译2.0 demo java语言

机器翻译2.0 demo nodejs语言

机器翻译2.0 demo php语言

机器翻译2.0 demo go语言

注： 其他开发语言请参照 接口调用流程 进行开发，也欢迎热心的开发者到 讯飞开放平台社区 分享你们的demo。

# 常见问题

# 机器翻译的主要功能是什么？

答：支持文本到文本的机器翻译。

# 机器翻译支持哪些语种？

答：目前支持包括英、日、韩、法、西、俄等100多种语言，详细的语种可见语种列表。

# 机器翻译支持什么应用平台？

答：目前仅支持webapi接口。

# 机器翻译是否可以私有云部署？

答：可以的，建议您登录讯飞开放平台，进入机器翻译页面，点击私有云部署的“立即申请”按钮，进行资料填写，商务人员会在1-3个工作日内与您详细洽谈。

# 机器翻译如何购买？

答：可在主页在线购买，点击购买

# 是否支持离线翻译？

答：暂不支持离线翻译。