1. 接口说明

拍照速算识别基于深度学习的端到端识别技术，自动识别图片中的速算题并智能批改，返回标准LaTeX公式及批改结果。覆盖K12教育范围内15种题型，支持口算、竖式、方程、脱式计算等，详细请参照 速算题型 。支持的场景有印刷体、手写体、拍照场景。

该能力是通过HTTP API的方式给开发者提供一个通用的接口。HTTP API适用于一次性交互数据传输的AI服务场景，比如上传图片识别其中的文字等；相较于SDK，API具有轻量、跨语言的特点。另外，请注意该接口使用的HTTP API协议不支持跨域。

2. 接口Demo

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

3. 接口要求

集成拍照速算识别API时，需按照以下要求。

4. 接口调用流程

· 通过接口密钥基于hamc-sha256计算签名，将签名以及其他参数放在Http Request Header中。详见下方 鉴权认证 。

· 将请求参数以及图片数据放在Http Request Body中。详见下方 请求参数 。

· 向服务器端发送Http请求后，接收服务器端的返回结果。

4.1. 鉴权认证

在调用业务接口时，须对HTTP请求进行签名，服务端通过签名来识别用户并验证其合法性。

4.1.1. 鉴权方法

在Http Request Header中配置以下鉴权参数用于授权认证，其中签名信息放在请求头Authorization中。Header示例：

Content-Type:application/json
Accept:application/json,version=1.0
Host:rest-api.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"

鉴权参数：

· date参数生成规则：

date必须是UTC+0或GMT时区，RFC1123格式(Mon, 02 Jan 2006 15:04:05 GMT)。服务端会对Date进行时钟偏移检查，最大允许300秒的偏差，超出偏差的请求都将被拒绝。

· Authorization参数生成格式：

Authorization: api_key="your_key", algorithm="hmac-sha256", headers="host date request-line digest", signature="$signature"
示例：Authorization: api_key="a68af9b44ceaa8e1c1f53313dc6bd766", algorithm="hmac-sha256", headers="host date request-line digest", signature="Qdns+0diwvG9Jm0sPmVyF+hr+3dZTSEQO5kbzOtL0b4="

其中 api_key 是在控制台获取的APIKey（创建WebAPI平台应用并添加拍照速算识别服务后即可查看，为32位字符串。）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://rest-api.xfyun.cn/v2/itr请求的body为：{"common":{"app_id":"xxxxxxxx"},"business":{"ent":"math-arith","aue":"raw"},"data":{"image":"/9j/4AAQSkZJRgABAQAAAQABA…="}}则signature生成步骤如下：

1）对请求body进行SHA256计算，把计算结果进行Base64编码后的字符串写在"SHA-256="后，即字段digest的值

digest: SHA-256=Base64(SHA256(请求body))
例:digest: SHA-256=MGNjNThlMTU3ZWNmYjU4YTlhNTAwNDI5NWE4NTBmNWM5ZTMwMmM5OGZiNzE2ODY4ZjM2ZTQxYmNjMzkzZjIwYQ==

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

host: rest-api.xfyun.cn
date: Mon, 18 Mar 2019 09:02:18 GMT
POST /v2/itr HTTP/1.1
digest: SHA-256=MGNjNThlMTU3ZWNmYjU4YTlhNTAwNDI5NWE4NTBmNWM5ZTMwMmM5OGZiNzE2ODY4ZjM2ZTQxYmNjMzkzZjIwYQ==

3）使用hmac-sha256算法结合apiSecret（向平台申请的APISecret）对signature_origin签名，获得签名后的摘要signature_sha

signature_sha=hmac-sha256(signature_origin,$apiSecret)

4）使用base64编码对signature_sha进行编码，获得最终的signature

signature=base64(signature_sha)

4.1.2. 鉴权示例(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)
}

4.1.3. 鉴权结果

如果认证成功，会返回HTTP 101状态码，表示协议升级成功；如果认证失败，则根据不同错误类型返回不同HTTP Code状态码，同时携带错误描述信息，详细错误说明如下：

认证失败返回示例：

HTTP/1.1 403 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"
}

4.2. 请求参数

在调用业务接口时，都需要在 Http Request Body 中配置以下参数，请求数据均为json字符串。

注： base64编码后大小会增加约1/3请求参数示例：

{       
   "common":{
       "app_id":"xxxxxxxx"
   },
   "business":{
       "ent":"math-arith",
       "aue" :"raw"
   },
   "data":{
    "image":"/9j/4AAQSkZJRgABAQAAAQABAAD/2..."    
   }
}

4.3. 返回参数

data字段具体信息

注： 其中加粗部分为获取速算题识别结果、区域和批改正误信息的关键字段。

返回参数示例：

{
    "code": 0,
    "message": "",
    "sid": "itr0001d1af@gz16990297366463e902",
    "data": {
        "ITRResult": {
            "attr_exception": 0,
            "category": "math_phfw_arith",
            "multi_line_info": {
                "imp_line_info": [{
                    "imp_line_rect": {
                        "left_up_point_x": 156,
                        "left_up_point_y": 183,
                        "right_down_point_x": 416,
                        "right_down_point_y": 259
                    },
                    "rec_rejection": 0,
                    "strict_score": 0,
                    "total_score": 1
                }, 
                ......
                {
                    "imp_line_rect": {
                        "left_up_point_x": 634,
                        "left_up_point_y": 1303,
                        "right_down_point_x": 897,
                        "right_down_point_y": 1395
                    },
                    "rec_rejection": 0,
                    "strict_score": 0,
                    "total_score": 1
                }]
            },
            "recog_result": [{
                "line_char_result": null,
                "line_word_result": [{
                    "beg_pos": [0],
                    "beg_pos_x": [0],
                    "beg_pos_y": [0],
                    "end_pos": [258],
                    "end_pos_x": [258],
                    "end_pos_y": [74],
                    "word_content": ["3 7 - 8 = 2 9"],
                    "word_gwpp": [0.9989326596260071]
                }, 
                ......
                {
                    "beg_pos": [0],
                    "beg_pos_x": [0],
                    "beg_pos_y": [0],
                    "end_pos": [262],
                    "end_pos_x": [262],
                    "end_pos_y": [91],
                    "word_content": ["7 2 - 8 = 6 4"],
                    "word_gwpp": [0.9990690350532532]
                }]
            }],
            "version": "3.6.0.1022"
        }
    }
}

5. 错误码

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

6. 速算题型

No.	题型名称	题型示例
1	四则混合运算
2	带题标号的四则混合运算
3	已知结果求运算因子
4	填写“<” “>” “=”
5	填最大数、最小数
6	约等于估算
7	带余除数法
8	相邻数
9	分数四则运算
10	单位换算
11	竖式加减法
12	竖式乘除法
13	脱式运算
14	解方程
15	求平方

7. 调用示例

拍照速算识别demo python2语言

拍照速算识别demo java语言

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

8. 图片样例

拍照速算识别 图片样例 JPG文件

拍照速算识别 图片样例 PNG文件

拍照速算识别 图片样例 BMP文件

注： 如果测试过程中，发现图片符合要求但却不能识别，有可能是由于图片的真实格式和文件后缀不符，请通过图片的二进制流的头文件确认图片真实格式，不符合要求需要进行格式转换。

Copyright © iflytek.com 2018 all right reserved，powered by Gitbook该文件修订时间：2019-05-07 07:12:51