机器翻译 API 文档

接口说明

机器翻译，基于讯飞自主研发的机器翻译引擎，已经支持包括英、日、法、西、俄等10多种语言(其中维语、藏语暂不对外提供)，效果更优质，已在讯飞翻译机上应用并取得优异成绩，详细请参照语种列表。通过调用该接口，将源语种文字转化为目标语种文字。
该能力是通过HTTP API的方式给开发者提供一个通用的接口。HTTP API适用于一次性交互数据传输的AI服务场景，相较于SDK，API具有轻量、跨语言的特点。另外，请注意该接口使用的HTTP API协议不支持跨域。

接口Demo

示例demo 请点击这里下载。
目前仅提供部分开发语言的demo，其他语言请参照下方接口文档进行开发。
也欢迎热心的开发者到讯飞开放平台社区分享你们的demo。

接口要求

集成机器翻译时，需按照以下要求。

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

接口调用流程

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

白名单

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

请求参数

在调用业务接口时，都需要在 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编码要求编码后大小不超过 1024 bytes（约256个汉字）。注： 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": "its....",
  "data": {
    "result": {
      "from": "cn",
      "to": "en",
      "trans_result": {
        "dst": "Hello World ",
        "src": "你好世界"
      }
    }
  }
}

错误码

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

HTTP Code	说明	错误描述信息
10106	非法的消息内容	ErrorContentInvalid
10700	连接引擎失败	ErrorConnectFail

语种列表

语种	参数
汉语普通话	cn
英语	en
彝语	ii
广东话	yue
日语	ja
俄语	ru
法语	fr
西班牙语	es
阿拉伯语	ar
维语	暂不开放
藏语	暂不开放

调用示例

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

常见问题

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

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

机器翻译支持哪些语种？

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

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

答：目前仅支持webapi接口。

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

答: 单次文本长度不得超过256字符。一个汉字、英文字母、标点符号等，均计为一个字符

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

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

机器翻译如何购买？

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

在这篇文章中：

# 机器翻译 API 文档

# 接口说明

# 接口Demo

# 接口要求

# 接口调用流程

# 白名单

# 鉴权认证

# 鉴权方法

# 鉴权示例(golang)

# 鉴权结果

# 请求参数

# 返回参数

# 错误码

# 语种列表

# 调用示例

# 常见问题

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

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

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

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

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

# 机器翻译如何购买？