# 机器翻译niutrans API 文档

# 接口说明

内容 说明
传输方式 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个汉字)
文本语言 支持454多种语种,详细请参照 语种列表

# 白名单

默认关闭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) 在线体验效果。

# 语言参数对照表

语种 参数 语种 参数 语种 参数 语种 参数
阿尔巴尼亚语 sq 阿拉伯语 ar 阿姆哈拉语 am 阿丘雅语 acu
阿瓜鲁纳语 agr 阿卡瓦伊语 ake 阿穆斯戈语 amu 阿塞拜疆语 az
爱尔兰语 ga 爱沙尼亚语 et 埃维语 ee 奥吉布瓦语 ojb
奥罗莫语 om 奥利亚语 or 奥赛梯语 os 阿雅安伊富高语 ifb
艾马拉语 aym 阿卡特克语 knj 安蒂波洛伊富高语 ify 阿奇语 acr
安拜语 amk 奥罗科语 bdu 阿多拉语 adh 阿格尼桑维语 any
阿舍宁卡语 cpb 埃菲克语 efi 阿乔利语 ach 埃桑语 ish
埃多语 bin 阿卢尔语 alz 阿亚库乔克丘亚语 quy 奥克语 oc
阿斯图里亚斯语 ast 阿拉贡语 an 阿法尔语 aa 阿尔及利亚阿拉伯语 arq
阿布哈兹语 ab 巴布亚皮钦语 tpi 巴拉萨纳语 bsn 巴什基尔语 ba
巴斯克语 eu 白俄罗斯语 be 白苗文 mww 柏柏尔语 ber
保加利亚语 bg 冰岛语 is 比斯拉马语 bi 别姆巴语 bem
波兰语 pl 波斯尼亚语 bs 波斯语 fa 波塔瓦托米语 pot
布列塔尼语 br 波孔奇语 poh 班巴拉语 bam 北部马姆语 map
巴里巴语 bba 博科巴鲁语 bus 布萨语 bqp 波拉语 bnp
巴里亚语 bch 班通安隆语 bno 班迪亚勒语 bqj 巴卡语 bdh
邦邦语 ptu 巴里语 bfa 布阿尔考钦语 cbl 北部格雷博语 gbo
巴萨语 bas 布卢语 bum 邦阿西楠语 pag 鲍勒语 bci
比亚克语 bhw 巴塔克卡罗语 btx 波纳佩语 pon 伯利兹克里奥尔语 bzj
巴拉圭瓜拉尼语 gug 北部普埃布拉纳瓦特语 ncj 巴西葡萄牙语 pt-BR 邦板牙语 pam
北索托语 nso 北萨米语 se 查莫罗语 cha 楚瓦什语 cv
茨瓦纳语 tn 聪加语 ts 车臣语 che 查克玛语 ccp
茨鲁语 cdf 茨瓦语 tsc 楚瓦博语 chw 鞑靼语 tt
丹麦语 da 德语 de 德顿语 tet 迪维希语 dv
丁卡语 dik 迪尤拉语 dyu 迪塔马利语 tbz 达迪比语 mps
蒂穆贡-穆鲁特语 tih 东部卡加延-阿格塔语 duo 丹美语 ada 杜阿拉语 dua
帝力德顿语 tdt 德鲁语 dhv 蒂夫语 tiv 多巴巴塔克语 bbc
地峡萨波特克语 zai 低地德语 nds 道本语 toki 俄语 ru
恩都卡语 djk 恩舍特语 enx 恩泽马语 nzi 恩加朱语 nij
恩科里语 nyn 恩道语 ndc 恩敦加语 ndo 法语 fr
法罗语 fo 菲律宾语 fil 斐济语 fj 芬兰语 fi
法兰钦语 cfm 法拉法拉语 gur 佛得角克里奥尔语 kea 丰语 fon
弗留利语 fur 法兰克-普罗旺斯语 frp 梵语 sa 高棉语 km
盖丘亚语 quw 刚果语 kg 弗里西语 fy 格鲁吉亚语 jy
古吉拉特语 gu 瓜哈哈拉语 gub 果发语 gof 格森语 xsm
格巴亚语 krs 龚语 guw 刚果斯瓦希里语 swc 圭米语 gym
瓜拉尼语 gn 格陵兰语 kl 高原马达加斯加语 plt 古英语 ang
哈萨克语 ka 哈萨克语(西里尔) kk 海地克里奥尔语 ht 韩语 ko
豪萨语 ha 荷兰语 nl 黑山语 me 哈卡钦语 cnh
胡里语 hui 亥比语 hlb 赫雷罗语 her 胡帕语 hup
吉尔吉斯语 ky 基切语 quc 加莱拉语 gbi 加利西亚语 gl
加泰罗尼亚语 ca 捷克语 cs 基里巴斯语 gil 景颇语 kac
加语 gaa 基库尤语 kik 金邦杜语 kmb 加利富纳语 cab
加拿大法语 fr-CA 卡拜尔语 kab 卡韦卡尔语 cjp 卡克奇克尔语 cak
卡纳达语 kn 凯克其语 kek 坎帕语 cni 科普特语 cop
科奇语 kbh 科西嘉语 co 克雷塔罗奥托米语 otq 克罗地亚语 hr
库尔德语(库尔曼奇语) ku 库尔德语(索拉尼语) ckb 库阿努阿语 ksd 库斯科克丘亚语 quz
卡平阿马朗伊语 kpg 克里米亚鞑靼语 crh 卡尔梅克卫拉特语 xal 克利科语 kbo
卡库瓦语 keo 喀克其奎语 cki 卡乌龙语 pss 库隆语 kle
卡纳尔高地-基丘亚语 qxr 库克群岛毛利语 rar 卡比耶语 kbp 卡姆巴语 kam
卡昂多语 kqn 喀麦隆皮钦语 wes 宽亚玛语 kua 克林贡语 tlh
卡努里语 kr 康沃尔语 kw 卡舒比语 csb 卢旺达语 rw
拉丁语 la 拉脱维亚语 lv 老挝语 lo 隆迪语 rn
立陶宛语 lt 林加拉语 ln 卢干达语 lg 卢克帕语 dop
卢森堡语 lb 罗马尼亚语 ro 罗姆语 rmn 隆韦语 ngl
罗维那语 rug 勒期语 lsi 临高语 ond 罗子语 loz
卢巴开赛语 lua 卢巴-加丹加语 lub 隆打语 lun 卢乌德语 rnd
卢瓦来语 lue 林堡语 li 逻辑语 jbo 马尔加什语 mg
马耳他语 mt 马恩岛语 gv 马拉地语 mr 马拉雅拉姆语 ml
马来语 ms 马里语 mhr 马姆语 mam 马其顿语 mk
毛利语 mi 蒙古语 mo 蒙古语(西里尔) mn 缅甸语 my
孟加拉语 bn 曼尼普尔语 mni 摩图语 meu 马绍尔语 mah
马拉瑙语 mrw 马勒语 mdy 马都拉语 mad 莫西语 mos
穆图凡语 muv 米佐语 lus 毛里求斯克里奥尔语 mfe 姆班杜语 umb
马普切语 arn 米斯特克语 mxv 马库阿语 vmw 曼代灵西马隆贡语 bts
曼布韦-龙古语 mgr 门诺低地德语 pdt 米兰达语 mwl 迈蒂利语 mai
马来语克里奥尔语 crp 纳瓦特尔语 nhg 南非荷兰语 af 南非科萨语 xh
南非祖鲁语 zu 尼泊尔语 ne 挪威语 no 南阿塞拜疆语 azb
南玻利维亚克丘亚语 quh 弄巴湾语 lnd 尼日利亚富拉语 fuv 努曼干语 nop
纳特尼语 ntm 尼亚库萨语 nyy 纽埃语 niu 尼亚斯语 nia
涅姆巴语 nba 尼荣圭语 nyu 纳瓦霍语 nav 尼亚内卡语 nyk
尼日利亚皮钦语 pcm 南恩德贝莱语 nr 帕皮阿门托语 pap 派特语 pck
旁遮普语 pa 葡萄牙语 pt 普什图语 ps 佩勒-阿塔语 ata
皮京语 pis 帕潘特拉托托纳克语 top 齐切瓦语 ny 契维语 tw
切诺基语 chr 奇南特克语 chq 齐马内语 cas 乔奎语 cjk
乔皮语 cce 丘克语 chk 钦博拉索高地克丘亚语 qug 恰蒂斯加尔语 hne
日语 ja 瑞典语 sv 萨摩亚语 sm 塞尔维亚语 sr
塞舌尔克里奥尔语 crs 塞索托语 st 桑戈语 sg 僧伽罗语 si
山地马里语 mrj 世界语 eo 舒阿尔语 jiv 斯洛伐克语 sk
斯洛文尼亚语 sl 斯瓦希里语 sw 苏格兰盖尔语 gd 索马里语 so
苏奥语 swp 桑贝里吉语 ssx 萨鲍特语 spy 圣马特奥德马尔-瓦维语 huv
斯哈语 jmc 萨拉马坎语 srm 桑格语 sxn 塞纳语 seh
圣萨尔瓦多刚果语 kwy 松格语 sop 索西语 tzo 斯高克伦语 ksw
苏格兰语(低地苏格兰语) sco 书面挪威语 nb 撒丁语 sc 掸语 shn
塞尔维亚-克罗地亚语 sh 斯威士语 ss 上索布语 hsb 塔吉克语 tg
塔希提语 ty 泰卢固语 te 泰米尔语 ta 泰语 th
汤加语 to 提格雷语 tig 图阿雷格语 tmh 土耳其语 tr
土库曼语 tk 坦普尔马语 tpm 特丁钦语 ctd 图瓦语 tyv
图马伊鲁穆语 iou 腾内特语 tex 通加格语 lcm 特索语 teo
图瓦卢语 tvl 特特拉语 tll 他加禄语 tgl 通布卡语 tum
托霍拉瓦尔语 toj 土柔语 ttj 瓦拉莫语 wal 瓦瑞语 war
文达语 ve 沃洛夫语 wol 乌德穆尔特语 udm 乌尔都语 ur
乌克兰语 uk 乌兹别克语 uz 乌玛语 ppk 乌斯潘坦语 usp
瓦利语 wlx 佤语 prk 瓦吉语 wsk 瓦里斯语 wrs
文约语 vun 威尔士语 cy 瓦利斯语 wls 乌尔霍博语 urh
瓦乌特拉马萨特克语 mau 瓦尤语 guc 瓦隆语 wa 西班牙语 es
希伯来语 he 希尔哈语 shi 希腊语 el 夏威夷语 haw
信德语 sd 匈牙利语 hu 修纳语 sn 宿务语 ceb
叙利亚语 syc 夏威夷克里奥尔英语 hwc 希里莫图语 hmo 西部拉威语 lcp
锡达莫语 sid 西布基农马诺布语 mbb 西皮沃语 shp 西罗伊语 ssd
西部玻利维亚瓜拉尼语 gnw 西部克耶语 kyu 希利盖农语 hil 新挪威语 nn
下索布语 dsb 新通用语 lfn 西方国际语 ie 亚美尼亚语 hy
雅加达语 jac 亚齐语 ace 伊博语 ig 意大利语 it
意第绪语 yi 印地语 hi 印尼巽他语 su 印尼语 id
印尼爪哇语 jv 英语 en 尤卡坦玛雅语 yua 约鲁巴语 yo
越南语 vi 粤语 yue 伊卡语 ikk 伊兹语 izz
约姆语 pil 雅比姆语 jae 永贡语 yon 邕北壮语 zyb
伊普马语 byr 伊索科语 iso 伊班语 iba 伊洛卡诺语 ilo
伊巴纳格语 ibg 雅浦语 yap 因巴布拉高地克丘亚语 qvi 伊多语 io
因特语 ia 哲尔马语 dje 中文(简体) zh 中文(繁体) cht
宗喀语 dz 中部伊富高语 ifa 佐通钦语 czt 中部杜顺语 dtp
中比科尔语 bcl 泽塔尔语 tzh 赞德语 zne 中部普埃布拉纳瓦特语 ncx
中部瓦斯特克纳瓦特语 nch 中古法语 frm

# 常见问题

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

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

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

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

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

答:目前仅支持webapi接口。

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

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

# 机器翻译如何购买?

答:可在主页在线购买,点击购买 (opens new window)

# 是否支持离线翻译?

答:暂不支持离线翻译。

在线咨询
体验中心