# 机器翻译niutrans API 文档
# 接口说明
机器翻译2.0,基于小牛翻译自主研发的多语种机器翻译引擎,已经支持包括英、日、韩、法、西、俄等100多种语言,详细请参照 语种列表 。通过调用该接口,将源语种文字转化为目标语种文字。可在 这里 (opens new window) 体验效果。
注: 原老版本 机器翻译1.0( http://openapi.openspeech.cn/webapi/its.do )的老用户,烦请尽快使用最新的机器翻译2.0接口。机器翻译1.0我们会在近几个月内渐渐停止维护,为了您的服务稳定,请马上切换。部分接口demo如下,其他开发语言请参照 接口调用流程 进行开发,也欢迎热心的开发者到 讯飞开放平台社区 (opens new window) 分享你们的demo。
机器翻译2.0 demo python3语言 (opens new window)
机器翻译2.0 demo java语言 (opens new window)
机器翻译2.0 demo nodejs语言 (opens new window)
机器翻译2.0 demo php语言 (opens new window)
机器翻译2.0 demo go语言 (opens new window)集成机器翻译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"
}
# 请求参数
在调用业务接口时,都需要在 Http Request Body 中配置以下参数,请求数据均为json字符串。
请求参数示例:
{
"common":{
"app_id":"xxxxxxxx"
},
"business":{
"from":"cn",
"to" :"en"
},
"data":{
"text":"5LuK5aSp5aSp5rCU5oCO5LmI5qC377yf"
}
}
请求参数说明:
参数名 | 类型 | 必传 | 描述 |
---|---|---|---|
common | object | 是 | 用于上传公共参数 |
common.app_id | string | 是 | 在平台申请的appid信息 |
business | object | 是 | 用于上传业务参数 |
business.from | string | 是 | 源语种 可以指定语种参数,也可以指定auto自动识别源语种 注:目前自动识别语种(auto)的效果,对长文本及非同语系的文本较为理想,对短文本及同语系的效果还在逐步优化中,请根据您的实际需求场景使用。 |
business.to | string | 是 | 目标语种 |
business.infmt | string | 否 | 当上传文本格式为xml时,开启该参数可保留xml符号,可选值:xml |
data | object | 是 | 用于上传待翻译文本 |
data.text | bytes | 是 | 文本数据,UTF-8字符集,base64编码 要求编码后大小不超过 20000 bytes(约5000个汉字)。 注: base64编码后大小会增加约1/3。 |
# 返回结果
如出现错误码,可到 这里 (opens new window) 查询。
返回参数示例:
{
"code": 0,
"message": "success",
"sid": "ots....",
"data": {
"result": {
"from": "cn",
"to": "en",
"trans_result": {
"dst": "Hello World ",
"src": "你好世界"
}
}
}
}
返回参数说明:
参数名 | 类型 | 描述 |
---|---|---|
sid | string | 本次会话id |
code | int | 返回码,0表示成功,其它表示异常,详情请参考错误码 (opens new window)。 |
message | string | 描述信息 |
data | object | 翻译结果,详见下方 若接口报错(code不为0),则无该字段 |
翻译结果在data字段的result字段中。
result字段具体信息如下:
参数 | 类型 | 说明 |
---|---|---|
from | string | 源语种,如果请求设置auto则自动返回识别到的源语种参数 |
to | string | 目标语种 |
trans_result | object | 翻译结果 |
trans_result.src | string | 源文本 |
trans_result.dst | string | 目标文本 |
# 语种列表
可在 这里 (opens new window) 在线体验效果。
语种 | 参数 | 语种 | 参数 | 语种 | 参数 |
---|---|---|---|---|---|
中文(简体) | 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个工作日内与您详细洽谈。
# 机器翻译如何购买?
答:可在主页在线购买,点击购买 (opens new window)
# 是否支持离线翻译?
答:暂不支持离线翻译。