setting alipay wechat success appmanage dollor user cart order workorder logout left1 left2 app unfree free chart coupon note copy pencil price-tag database cog bin list link plus minus codepen 审核 cross table search user-tie eye github cancel-circle checkmark icon-upload icon-smartphon icon-auth-user icon-arroba-symbol icon-check-pass icon-red-cross icon-pwd-key icon-used icon-expired android appleinc tux windows8 java webAPI mail vip

    # 机器翻译 API 文档

    # 接口说明

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

    # 接口Demo

    示例demo 请点击 这里 下载。
    目前仅提供部分开发语言的demo,其他语言请参照下方接口文档进行开发。
    也欢迎热心的开发者到 讯飞开放平台社区 (opens new window) 分享你们的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": "你好世界"
          }
        }
      }
    }
    

    # 错误码

    备注:如出现下述列表中没有的错误码,可到 这里 (opens new window) 查询。

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

    # 语种列表

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

    # 调用示例

    机器翻译 demo python3语言 (opens new window)

    机器翻译 demo java语言 (opens new window)

    机器翻译 demo nodejs语言 (opens new window)

    机器翻译 demo php语言 (opens new window)

    机器翻译 demo go语言 (opens new window)

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

    # 常见问题

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

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

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

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

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

    答:目前仅支持webapi接口。

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

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

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

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

    # 机器翻译如何购买?

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