机器翻译 API 文档

接口说明

机器翻译，基于讯飞自主研发的机器翻译引擎，已经支持包括英、日、法、西、俄等70多种语言，效果更优质，已在讯飞翻译机上应用并取得优异成绩，详细请参照语种列表。通过调用该接口，将源语种文字转化为目标语种文字。
部分接口demo如下，其他开发语言请参照接口调用流程进行开发，也欢迎热心的开发者到讯飞开放平台社区分享你们的demo。
机器翻译 demo python3语言
 机器翻译 demo java语言
 机器翻译 demo nodejs语言
 机器翻译 demo php语言
 机器翻译 demo go语言
集成机器翻译时，需按照以下要求:

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

白名单

默认关闭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:itrans.xfyun.cn
Date:Wed, 20 Nov 2019 03:14:25 GMT
Digest:SHA-256=2iwDpX6yAoQAeeAhT4yi3Tx9XRaWvAAvn3L8Ip6fdpA=
Authorization:api_key="your_key", algorithm="hmac-sha256", headers="host date request-line digest", signature="$signature"

鉴权参数：

参数	类型	必须	说明	示例
Host	string	是	请求主机	itrans.xfyun.cn
Date	string	是	当前时间戳，RFC1123格式(`"EEE, dd MMM yyyy HH:mm:ss z"`)	`Wed, 20 Nov 2019 03:14:25 GMT`
Digest	string	是	加密请求body SHA-256=Base64(SHA256(请求body)) body请参考下方请求参数	`SHA-256=2iwDpX6....`
Authorization	string	是	使用base64编码的签名相关信息(签名基于hamc-sha256计算)	参考下方

date参数生成规则：

date必须是UTC+0或GMT时区，RFC1123格式(Wed, 20 Nov 2019 03:14:25 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://itrans.xfyun.cn/v2/its
请求的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=2iwDpX6yAoQAeeAhT4yi3Tx9XRaWvAAvn3L8Ip6fdpA=

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

host: itrans.xfyun.cn
date: Wed, 20 Nov 2019 03:14:25 GMT
POST /v2/its HTTP/1.1
digest: SHA-256=2iwDpX6yAoQAeeAhT4yi3Tx9XRaWvAAvn3L8Ip6fdpA=

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)
例：d4kHthlsRTE/YAjFnuJiNs1u/cXOmSI4fAvKwLawQ+8=

鉴权示例(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: Wed, 20 Nov 2019 03:14:25 GMT
Content-Length: 116
Content-Type: text/plain; charset=utf-8
{
    "message": "HMAC signature does not match"
}

请求参数

在调用业务接口时，都需要配置以下参数，请求数据均为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	是	源语种
business.to	string	是	目标语种
data	object	是	用于上传待翻译文本
data.text	bytes	是	文本数据，UTF-8字符集，base64编码要求编码后大小不超过 1024 bytes（约256个汉字）。注： base64编码后大小会增加约1/3。

返回参数

如出现错误码，可到这里查询。
返回参数示例：

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

返回参数说明：

参数名	类型	描述
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	目标文本

语种列表

语种	参数	语种	参数	语种	参数
汉语普通话	cn	波斯语	fa	僧伽罗语	si
英语	en	芬兰语	fi	斯洛伐克语	sk
彝语	ii	希伯来语	he	斯洛文尼亚语	sl
广东话	yue	印地语	hi	塞尔维亚语	sr
日语	ja	克罗地亚语	hr	巽他语	su
俄语	ru	匈牙利语	hu	瑞典语	sv
法语	fr	亚美尼亚语	hy	斯瓦希里语	sw
西班牙语	es	印尼语	id	泰米尔语	ta
阿拉伯语	ar	冰岛语	is	泰卢固语	te
意大利语	it	塔加路语（菲律宾）	tl	爪哇语	jv
土耳其语	tr	罗马尼亚语	ro	马来语	ms
越南语	vi	格鲁吉亚语	ka	乌克兰语	uk
泰语	th	高棉语	km	乌尔都语	ur
韩语	ko	老挝语	lo	南非祖鲁语	zu
德语	de	立陶宛语	lt	内蒙语	mn
哈萨克语	kka	拉脱维亚语	lv	缅甸语	my
南非荷兰语	af	马拉雅拉姆语	ml	外蒙语	nm
阿姆哈拉语	am	马拉地语	mr	普什图语	ps
阿塞拜疆语	az	博克马尔挪威语	nb	豪萨语	ha
孟加拉语	bn	尼泊尔语	ne	乌兹别克语	uz
加泰罗尼亚语	ca	荷兰语	nl	土库曼语	tk
捷克语	cs	波兰语	pl	塔吉克语	tg
丹麦语	da	葡萄牙语	pt	保加利亚语	bg
希腊语	el

常见问题

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

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

机器翻译支持哪些语种？

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

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

答：目前仅支持webapi接口。

机器翻译支持的文本长度是多少？

答: 单次文本长度不得超过4096字节。

是否支持源语种的自动识别？

答：目前不支持，后续会开放，新消息请关注平台动态。

机器翻译如何购买？

答：机器翻译产品页对应产品价格--->点击申请购买，填好相关信息，商务工作人员会及时与您联系。

在这篇文章中：

# 机器翻译 API 文档

# 接口说明

# 白名单

# 鉴权说明

# 鉴权示例(golang)

# 鉴权结果

# 请求参数

# 返回参数

# 语种列表

# 常见问题

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

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

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

# 机器翻译支持的文本长度是多少？

# 是否支持源语种的自动识别？

# 机器翻译如何购买？