# 机器翻译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 时,需按照以下要求。

内容 说明
传输方式 http[s] (为提高安全性,强烈推荐https)
请求地址 http[s]: //ntrans.xfyun.cn/v2/ots
注:服务器IP不固定,为保证您的接口稳定,请勿通过指定IP的方式调用接口,使用域名方式调用
请求行 POST /v2/ots HTTP/1.1
接口鉴权 签名机制,详情请参照下方接口鉴权
字符编码 UTF-8
响应格式 统一采用JSON格式
开发语言 任意,只要可以向讯飞云服务发起HTTP请求的均可
适用范围 任意操作系统,但因不支持跨域不适用于浏览器,请在后端调用接口
文本长度 单次文本长度不得超过5000字符
一个汉字、英文字母、标点符号等,均计为一个字符
文本大小 base64编码后大小不得超过 20000 bytes(约5000个汉字)
文本语言 支持100多种语种,详细请参照 语种列表

# 接口调用流程

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

# 白名单

在调用该业务接口时

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

IP白名单规则

  • 在 控制台-相应服务页面-IP白名单处编辑,保存后五分钟左右生效。
  • 不同Appid的不同服务都需要分别设置IP白名单。
  • 每个IP白名单最多可设置5个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"

鉴权参数:

参数 类型 必须 说明 示例
Host string 请求主机 ntrans.xfyun.cn
Date string 当前时间戳,RFC1123格式("EEE, dd MMM yyyy HH:mm:ss z") Tue, 30 Jul 2019 08:39:29 GMT
Digest string 加密请求body
SHA-256=Base64(SHA256(请求body))
body请参考下方请求参数
SHA-256=MGNjNThl....
Authorization string 使用base64编码的签名相关信息(签名基于hamc-sha256计算) 参考下方

  • 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 200状态码,表示协议升级成功;如果认证失败,则根据不同错误类型返回不同HTTP Code状态码,同时携带错误描述信息,详细错误说明如下:

HTTP Code 说明 错误描述信息
401 缺少authorization参数 {"message":"Unauthorized"}
403 时钟偏移校验失败 {"message":"HMAC signature cannot be verified, a valid date or x-date header is required for HMAC Authentication"}
403 签名参数解析失败 {"message":"HMAC signature cannot be verified"}
403 签名校验失败 {"message":"HMAC signature does not match"}

认证失败返回示例:

HTTP/1.1 403 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 object 用于上传公共参数
common.app_id string 在平台申请的appid信息
business object 用于上传业务参数
business.from string 源语种
business.to string 目标语种
data object 用于上传待翻译文本
data.text bytes 文本数据,UTF-8字符集,base64编码
要求编码后大小不超过 20000 bytes(约5000个汉字)。
注: base64编码后大小会增加约1/3。

请求参数示例:

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

# 返回参数

参数名 类型 描述
sid string 本次会话id
code int 返回码,0表示成功,其它表示异常,详情请参考错误码
message string 描述信息
data object 翻译结果,详见下方
若接口报错(code不为0),则无该字段

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

参数 类型 说明
from string 源语种
to string 目标语种
trans_result object 翻译结果
trans_result.src string 源文本
trans_result.dst string 目标文本

返回参数示例:

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

# 错误码

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

错误码 说明 处理方式
10324 Sid生成失败 联系技术人员
10106 非法的参数 检查参数是否正确上传
10107 非法参数值 检查参数值是否在取值范围内
10109 非法的data 检查发送的文本是否合法
10114 超时 检查网络是否通畅
10160 json解析异常 检查参数是否正确发送了body,或者没有发送body
10161 解码错误 检查发送的数据是否按照规范正确编码
10313 appId为空 检查appid是否未正确上传
11210 appId不匹配 检查appid和key是否匹配

# 语种列表

可在 这里 在线体验效果。

语种 参数 语种 参数 语种 参数
中文(简体) cn 海地克里奥尔语 ht 普什图语 ps
中文(繁体) cht 匈牙利语 hu 隆迪语 rn
英语 en 亚美尼亚语 hy 罗马尼亚语 ro
日语 ja 印尼语 id 卢旺达语 rw
韩语 ko 伊博语 ig 信德语 sd
俄语 ru 冰岛语 is 桑戈语 sg
法语 fr 意大利语 it 僧伽罗语 si
西班牙语 es 印尼爪哇语 jv 斯洛伐克语 sk
阿拉伯语 ar 格鲁吉亚语 jy 斯洛文尼亚语 sl
葡萄牙语 pt 哈萨克语 ka 萨摩亚语 sm
南非荷兰语 af 凯克其语 kek 修纳语 sn
阿姆哈拉语 am 刚果语 kg 索马里语 so
阿塞拜疆语 az 哈萨克语(西里尔) kk 阿尔巴尼亚语 sq
巴什基尔语 ba 高棉语 km 塞尔维亚语 sr
白俄罗斯语 be 卡纳达语 kn 塞索托语 st
别姆巴语 bem 库尔德语 ku 印尼巽他语 su
保加利亚语 bg 吉尔吉斯语 ky 瑞典语 sv
比斯拉马语 bi 拉丁语 la 斯瓦希里语 sw
孟加拉语 bn 卢森堡语 lb 泰米尔语 ta
波斯尼亚语 bs 卢干达语 lg 泰卢固语 te
加泰罗尼亚语 ca 林加拉语 ln 塔吉克语 tg
宿务语 ceb 老挝语 lo 茨瓦纳语 tn
科西嘉语 co 立陶宛语 lt 泰语 th
塞舌尔克里奥尔语 crs 拉脱维亚语 lv 藏语 ti
捷克语 cs 马尔加什语 mg 提格雷语 tig
威尔士语 cy 马里语 mhr 土库曼语 tk
丹麦语 da 毛利语 mi 汤加语 to
德语 de 马其顿语 mk 巴布亚皮钦语 tpi
埃维语 ee 马拉雅拉姆语 ml 土耳其语 tr
希腊语 el 蒙古语(西里尔) mn 聪加语 ts
世界语 eo 马拉地语 mr 鞑靼语 tt
爱沙尼亚语 et 山地马里语 mrj 契维语 tw
巴斯克语 eu 马来语 ms 塔希提语 ty
波斯语 fa 马耳他语 mt 乌德穆尔特语 udm
芬兰语 fi 白苗文 mww 乌克兰语 uk
菲律宾语 fil 缅甸语 my 乌尔都语 ur
斐济语 fj 博克马尔语 nb 维吾尔语 uy
弗里西语 fy 尼泊尔语 ne 乌兹别克语 uz
爱尔兰语 ga 荷兰语 nl 越南语 vi
苏格兰盖尔语 gd 挪威语 no 瓦瑞语 war
加利西亚 gl 齐切瓦语 ny 南非科萨语 xh
古吉拉特语 gu 奥罗莫语 om 意第绪语 yi
豪萨语 ha 奥赛梯语 os 约鲁巴语 yo
夏威夷语 haw 克雷塔罗奥托米语 otq 尤卡坦玛雅语 yua
希伯来语 he 旁遮普语 pa 广东话 yue
印地语 hi 帕皮阿门托语 pap 南非祖鲁语 zu
克罗地亚语 hr 波兰语 pl

# 调用示例

机器翻译2.0 demo python3语言

机器翻译2.0 demo java语言

机器翻译2.0 demo nodejs语言

机器翻译2.0 demo php语言

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

# 常见问题

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

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

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

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

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

答:目前仅支持webapi接口。

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

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

# 机器翻译如何购买?

答:可在主页在线购买,点击购买