机器翻译 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字符。一个汉字、英文字母、标点符号等,均计为一个字符
是否支持源语种的自动识别?
答:目前不支持,后续会开放,新消息请关注平台动态。
机器翻译如何购买?
答:机器翻译产品页对应产品价格--->点击申请购买,填好相关信息,商务工作人员会及时与您联系。