机器翻译niutrans API

接口说明

• 机器翻译2.0，基于小牛翻译自主研发的多语种机器翻译引擎，已经支持包括英、日、韩、法、西、俄等100多种语言，详细请参照 语种列表 。通过调用该接口，将源语种文字转化为目标语种文字。可在 这里 体验效果。
  注： 原老版本 机器翻译1.0（ http://openapi.openspeech.cn/webapi/its.do ）的老用户，烦请尽快使用最新的机器翻译2.0接口。机器翻译1.0我们会在近几个月内渐渐停止维护，为了您的服务稳定，请马上切换。
• 部分接口demo如下，其他开发语言请参照 接口调用流程 进行开发，也欢迎热心的开发者到 讯飞开放平台社区 分享你们的demo。
  机器翻译2.0 demo python3语言
  机器翻译2.0 demo java语言
  机器翻译2.0 demo nodejs语言
  机器翻译2.0 demo php语言
  机器翻译2.0 demo go语言
• 集成机器翻译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多种语种，详细请参照 语种列表

#白名单

默认关闭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"

鉴权参数：

参数	类型	必须	说明	示例
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
请求的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 Code	说明	错误描述信息	解决方法
401	缺少authorization参数	{“message”:”Unauthorized”}	检查是否有authorization参数，详情见authorization参数详细生成规则
401	签名参数解析失败	{“message”:”HMAC signature cannot be verified”}	检查签名的各个参数是否有缺失是否正确，特别确认下复制的api_key是否正确
401	签名校验失败	{“message”:”HMAC signature does not match”}	签名验证失败，可能原因有很多。 1. 检查api_key,api_secret 是否正确。 2.检查计算签名的参数host，date，request-line是否按照协议要求拼接。 3. 检查signature签名的base64长度是否正常(正常44个字节)。
403	时钟偏移校验失败	{“message”:”HMAC signature cannot be verified, a valid date or x-date header is required for HMAC Authentication”}	检查服务器时间是否标准，相差5分钟以上会报此错误
403	IP白名单校验失败	{"message":"Your IP address is not allowed"}	可在控制台关闭IP白名单，或者检查IP白名单设置的IP地址是否为本机外网IP地址

认证失败返回示例：

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

语种列表

可在 这里 在线体验效果。

语种	参数	语种	参数	语种	参数
中文(简体)	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

#常见问题

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

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

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

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

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

答：目前仅支持webapi接口。

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

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

#机器翻译如何购买？

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

#是否支持离线翻译？

答：暂不支持离线翻译。

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

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