通用ocr功能说明文档
文档状态
| 文件标识： | TuringOS-OCR-V1.1.0 |
|---|---|
| 系统版本： | API |
| 作 者： | 刘秀丽 |
| 完成日期： | 2024年4月17日 |
文档修订记录
为便于后续文档维护，文档版本号将由三部分组成，第一个数字为主版本号，第二个数字为功能版本号，第三个数字为修订版本号：
| 修订日期 | 修订原因 | 修订人 |
|---|---|---|
| 2024.4.17 | 创建文档 | 刘秀丽 |
协议说明
1.加密说明
为保证接口的安全性和稳定性，需要对接口数据进行加/解密；
- 加/解密必须包含的信息：Secret（需通过图灵Biz平台 - 机器人信息页获取）；
- 需针对请求参数中的Data字段，进行AES加密处理，具体加密方式如下：
| 参数 | 说明 | 备注 |
|---|---|---|
| 加密模式 | CBC | - |
| 填充 | PKCS5Padding | - |
| 数据块 | 128位（密钥为16位） | - |
| 密码 | secret | 需要从图灵biz平台获取 |
| 偏移量 | secret | 需要从图灵biz平台获取 |
| 输出 | base64编码 | - |
| 字符集 | utf-8 | - |
加/解密参考网站：http://tool.chacuo.net/cryptaes
2.请求说明
2.1请求说明
集成websocket请求时，需按照以下要求：
| 内容 | 说明 |
|---|---|
| 传输方式 | ws[s] (若对数据通信有较高的安全要求，建议选择wss接入方式来访问图灵服务，由于ssl层验证预计会额外多花费40\~50ms的时间。) |
| 请求地址 | ws[s]://ws-api.turingapi.com/api/v2 |
| 字符编码 | UTF-8 |
| 响应格式 | json |
| 文本语言 | 中文 |
| 支持机器人类型 | webSocket接入（在图灵biz平台申请对应类型机器人） |
| 是否支持并发 | SOCKET不允许并发请求，即上一轮请求未完成(result-done)时不允许发送下一个请求 |
2.2 通用请求示例
当biz平台开启加密时，使用该初始化示例请求socket服务：
{
"key": "ed474dae62*********67050faea1788",
"timestamp": "150******7793",
"data": "加密后的内容"
}
请求参数说明
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| key | String | Y | biz平台设置机器人的apiKey |
| timestamp | String | Y | 时间戳 |
| data | JSON | Y | 配置信息，参考下方参数data字段说明 |
3.OCR接口说明
3.1 初始化参数
data加密前数据格式:
{
"deviceId": "1***3",
"requestType": [
1
],
"nlpRequest": {
"content": [{
"data": "23bf6bf2-f528-4449-9249-99fceebc194a",
"type": 1
}],
"clientInfo": {
"robotSkill": {
"50111": {
"parameters": {
"ocrMode": 0,
"debug": 1
}
}
},
"userInfo": {
"useCodes": [
50111
]
}
}
},
"binarysState": {
"openBinarysId": "23bf6bf2-f528-4449-9249-99fceebc194a"
}
}
data字段说明
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| deviceId | String | Y | 用户设备Id: 1. 长度小于等于32位。 2. 需由字母或数字组成，其他字符可能导致部分功能错误 |
| requestType | Array | Y | 该次请求需要请求的内容: 1:NLP |
| nlpRequest | Json | Y | 参考下边的content字段说明 |
| binarysState | Json | N | 二进制参数上传状态 |
content字段说明
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| type | int | N | type=1 -图片 |
| data | String | Y | 对应类型的二进制参数ID： 32位字符串(UUID) |
robotSkill-parameters
| ocrMode | N | int | 模型类型。(-1: 自动, 0:通用, 1:中文, 2:英文, 3:手写）, 默认为=-1 |
| debug | N | int | 是否输出debug, 默认=0, [0=不输出，1=输出] |
| save | N | int | 是否保存原图和labelme预标注, 默认=0, [0=不保存, 1=保存] |
userInfo-useCodes
| 参数 | 类型 | 说明 |
|---|---|---|
| useCodes | array | 指定功能code【50111】，当前功能只能输入一个 |
binarysState 字段说明
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
|---|---|---|---|---|
| openBinarysId | String | N | - | 将传输二进制数据的参数ID： 1. 该值与nlpRequest-content-data中的内容一致 2. 32位字符串(UUID) |
注意:
- WebSocket的二进制参数输入都需要初始化时在nlpRequest-content中按类型提前申明并将代表该二进制参数ID赋值给nlpRequest-content-data.
3.2 上传图片数据
初始化参数成功后，需上传图片二进制参数，具体说明如下：
3.2.1图片数据格式说明
- 上传图片需使用JPG格式（不支持其他格式）
- 图片大小建议在3M以内
3.3 上报图片结束标识
data加密前数据格式:
{
"binarysState":
{
"completeBinarysId": "23bf6bf2-f528-4449-9249-99fceebc194a"
}
}
请注意：该结束标识加密后，需放入data字段中，与apikey、timestamp一起请求，参考加密请求示例
binarysState 字段说明
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
|---|---|---|---|---|
| completeBinarysId | String | N | - | 完成传输的二进制数据的参数ID： 32位字符串(UUID) |
4、返回示例及参数说明
返回示例
{
"clientRequestId": "f3eb4f3d-1f8b-4e51-a58e-d6dfdde82a7d",
"code": 200,
"done": true,
"globalId": "235149861537932001",
"message": "success",
"nlpResponse":
{
"intent":
{
"code": 50111,
"operateState": 1010,
"parameters":
{
"result":
[
{
"text_raw": ".1",
"bbox":
[
[
6,
13
],
[
20,
13
],
[
20,
24
],
[
6,
24
]
],
"char":
[
{
".":
{
"confidence": 0.002048492431640625,
"location":
[
11,
18
]
}
},
{
"1":
{
"confidence": 0.97265625,
"location":
[
14,
18
]
}
}
],
"h": 10.0,
"text": ".1"
},
{
"text_raw": "int",
"bbox":
[
[
212,
10
],
[
232,
10
],
[
232,
26
],
[
212,
26
]
],
"char":
[
{
"i":
{
"confidence": 1.0,
"location":
[
217,
18
]
}
},
{
"n":
{
"confidence": 1.0,
"location":
[
222,
17
]
}
},
{
"t":
{
"confidence": 1.0,
"location":
[
226,
18
]
}
}
],
"h": 18.0,
"text": "int"
},
{
"text_raw": "AutoOCR(ocrMode:0-3融合,支持手写印刷)",
"bbox":
[
[
348,
10
],
[
639,
10
],
[
639,
26
],
[
348,
26
]
],
"char":
[
{
"A":
{
"confidence": 1.0,
"location":
[
360,
18
]
}
},
{
"u":
{
"confidence": 1.0,
"location":
[
366,
18
]
}
},
{
"t":
{
"confidence": 1.0,
"location":
[
371,
18
]
}
},
{
"o":
{
"confidence": 0.998046875,
"location":
[
380,
18
]
}
},
{
"O":
{
"confidence": 0.80322265625,
"location":
[
388,
18
]
}
},
{
"C":
{
"confidence": 1.0,
"location":
[
397,
18
]
}
},
{
"R":
{
"confidence": 1.0,
"location":
[
406,
18
]
}
},
{
"(":
{
"confidence": 1.0,
"location":
[
420,
19
]
}
},
{
"o":
{
"confidence": 1.0,
"location":
[
429,
19
]
}
},
{
"c":
{
"confidence": 0.99951171875,
"location":
[
434,
19
]
}
},
{
"r":
{
"confidence": 1.0,
"location":
[
440,
19
]
}
},
{
"M":
{
"confidence": 0.99951171875,
"location":
[
449,
18
]
}
},
{
"o":
{
"confidence": 1.0,
"location":
[
457,
18
]
}
},
{
"d":
{
"confidence": 1.0,
"location":
[
466,
18
]
}
},
{
"e":
{
"confidence": 1.0,
"location":
[
472,
18
]
}
},
{
":":
{
"confidence": 1.0,
"location":
[
480,
18
]
}
},
{
"0":
{
"confidence": 0.8515625,
"location":
[
494,
18
]
}
},
{
"-":
{
"confidence": 0.9990234375,
"location":
[
500,
17
]
}
},
{
"3":
{
"confidence": 1.0,
"location":
[
506,
17
]
}
},
{
" ":
{
"confidence": 1.0,
"location":
[
506,
17
]
}
},
{
"融":
{
"confidence": 1.0,
"location":
[
520,
17
]
}
},
{
"合":
{
"confidence": 1.0,
"location":
[
532,
17
]
}
},
{
",":
{
"confidence": 1.0,
"location":
[
540,
17
]
}
},
{
"支":
{
"confidence": 1.0,
"location":
[
549,
17
]
}
},
{
"持":
{
"confidence": 1.0,
"location":
[
566,
17
]
}
},
{
"手":
{
"confidence": 1.0,
"location":
[
580,
17
]
}
},
{
"写":
{
"confidence": 1.0,
"location":
[
595,
17
]
}
},
{
"印":
{
"confidence": 1.0,
"location":
[
609,
18
]
}
},
{
"刷":
{
"confidence": 1.0,
"location":
[
623,
18
]
}
},
{
")":
{
"confidence": 1.0,
"location":
[
632,
18
]
}
}
],
"h": 10.214285714285714,
"text": "AutoOCR(ocrMode:0-3 融合,支持手写印刷)"
},
{
"text_raw": "o",
"bbox":
[
[
6,
51
],
[
16,
51
],
[
16,
63
],
[
6,
63
]
],
"char":
[
{
"o":
{
"confidence": 0.9150390625,
"location":
[
11,
57
]
}
}
],
"h": 13.0,
"text": "o"
},
{
"text_raw": "int",
"bbox":
[
[
212,
49
],
[
233,
49
],
[
233,
64
],
[
212,
64
]
],
"char":
[
{
"i":
{
"confidence": 1.0,
"location":
[
217,
56
]
}
},
{
"n":
{
"confidence": 1.0,
"location":
[
221,
56
]
}
},
{
"t":
{
"confidence": 1.0,
"location":
[
225,
56
]
}
}
],
"h": 14.0,
"text": "int"
},
{
"text_raw": "通用印刷OCR(支持中文,英文)",
"bbox":
[
[
348,
48
],
[
550,
48
],
[
550,
64
],
[
348,
64
]
],
"char":
[
{
"通":
{
"confidence": 1.0,
"location":
[
365,
56
]
}
},
{
"用":
{
"confidence": 1.0,
"location":
[
379,
56
]
}
},
{
"印":
{
"confidence": 1.0,
"location":
[
393,
56
]
}
},
{
"刷":
{
"confidence": 1.0,
"location":
[
408,
56
]
}
},
{
"O":
{
"confidence": 0.9951171875,
"location":
[
416,
56
]
}
},
{
"C":
{
"confidence": 1.0,
"location":
[
425,
56
]
}
},
{
"R":
{
"confidence": 1.0,
"location":
[
433,
56
]
}
},
{
"(":
{
"confidence": 1.0,
"location":
[
447,
56
]
}
},
{
"支":
{
"confidence": 1.0,
"location":
[
458,
56
]
}
},
{
"持":
{
"confidence": 1.0,
"location":
[
475,
56
]
}
},
{
"中":
{
"confidence": 1.0,
"location":
[
489,
56
]
}
},
{
"文":
{
"confidence": 1.0,
"location":
[
501,
56
]
}
},
{
",":
{
"confidence": 1.0,
"location":
[
509,
56
]
}
},
{
"英":
{
"confidence": 1.0,
"location":
[
520,
56
]
}
},
{
"文":
{
"confidence": 1.0,
"location":
[
535,
56
]
}
},
{
")":
{
"confidence": 1.0,
"location":
[
543,
56
]
}
}
],
"h": 11.3,
"text": "通用印刷OCR(支持中文,英文)"
}
],
"info":
{
"imageDebugUrl": "http://algorithm-cv-data.oss-cn-beijing.aliyuncs.com/turing_cv_server_debug/ocr_service/debug/ocr_debug_235149861537932001_2024-04-17-02-08-17.jpg",
"moduleT":
{
"server":
{
"total": 0.185,
"decode": 0.011,
"upload2OSS": 0.01,
"ocr": 0.164
},
"modelTime":
{
"rec": 0.104,
"lm": 0.005,
"det": 0.04
}
},
"imageInfo":
{
"shape":
[
853,
78
],
"rec_num": 6
}
}
}
},
"results":
[]
}
}
参数说明
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| code | int | Y | 状态code；参考状态code列表 |
| globalId | String | Y | 请求唯一标识 |
| message | String | Y | code对应的说明；参考状态code列表 |
| nlpResponse | Json | N | nlp相关回复信息；参考nlpResopnse参数说明 |
nlpResponse参数说明
nlpResponse - intent-code参数说明
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| code | int | Y | 输出技能code |
intent-operateState 参数说明
| 参数 | 类型 |
|---|---|
| 1010 | 正常结果返回 |
| 1000 | 状态码 |
| 1001 | 请求参数错误 |
| 1002 | 请求接口错误 |
parameters 参数说明
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
|---|---|---|---|---|
| warnMsg | String | N | - | 异常信息 |
| result | json | Y | - | ocr识别结果集，参考result说明 |
| info | json | N | - | 图片相关信息，参考info参数说明 |
result参数说明
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
|---|---|---|---|---|
| text | String | Y | - | str OCR识别结果 |
| text_raw | String | Y | - | 原始CRNN预测结果 |
| bbox | json | Y | - | 文字框的位置，从左上角到右下角顺序排序 |
| char | json | Y | - | 每个字符的信息text 和位置信息 参考char参数说明 |
| h | float | Y | - | 当前文字框的高度 |
char参数说明
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
|---|---|---|---|---|
| location | json | Y | - | 字符在原图的位置（location[0]=x, location[1]=y） |
| confidence | float | Y | - | 字符的置信度 |
info参数说明
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
|---|---|---|---|---|
| imageInfo | json | Y | - | 图像相关信息 参考imageInfo说明 |
| imageSaveUrl | String | N | - | 保存的原图 save=1时返回 |
| imageLabelUrl | String | N | - | 保存的debug图debug=1时返回 |
| moduleT | json | Y | - | 模型相关，毫秒，0代表没走此模块 参考moduleT 说明 |
imageInfo参数说明
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
|---|---|---|---|---|
| shape | json | Y | - | 输入图像的宽高 |
| rec_num | init | Y | - | 文字区域检测出的识别图条数 |
moduleT-modelTime参数说明
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
|---|---|---|---|---|
| det | float | Y | - | 文字区域检测模块 |
| rec | float | Y | - | 文字区域识别模块 |
| lm | float | Y | - | 解码和纠错模块 |
moduleT-server参数说明
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
|---|---|---|---|---|
| decode | float | Y | - | 图像解码时间 |
| ocr | float | Y | - | OCR整体时间 = sum(modelTime) |
| upload2OSS | float | Y | - | 上传oss时间（异步进行） |
| total | float | Y | - | 一个请求整体时间 |
附录
状态code列表
| code | 说明 |
|---|---|
| 200 | 正确结果返回 |
| 210 | 参数初始化成功，请收到该标识后上传二进制数据(如果需要) |
| 220 | 参数上传完成，正在请求nlp/tts |
| 300 | 无效数据:二进制参数已完成传输，不要发送该数据 |
| 4004 | 机器人类型非法 |
| 4005 | apikey信息错误 |
| 4006 | deviceId信息错误 |
| 4007 | 解密失败，您的加密逻辑存在异常 |
| 4008 | 数据内容格式错误 |
| 4009 | 机器人被禁用 |
| 4010 | 试用期已过 |
| 4011 | 系统不支持二进制参数 |
| 4012 | 今天我们已经聊了很多啦，明天再来找我聊天吧。 |
| 4013 | 这一小时的对话次数已经超过我的极限啦，让我休息一下，待会再聊 |
| 4014 | 这一分钟里我们已经聊了很多啦，休息，休息一下吧 |
| 4015 | 二进制参数错误，请确定binarysId是否对应 |
| 4016 | 单次交互时间过长，请查看文档！ |
| 4017 | 二进制参数错误，有重复binarysId！ |
| 4018 | 二进制参数输入状态异常 |
| 4019 | 二进制参数处理时间超时/第三方引擎参数错误 |
| 4022 | 二进制传输内容过大！ |
| 4023 | 单次交互同类型的二进制参数只允许输入一个 |
| 4025 | 上传数据失败，请稍后~ |
| 4026 | nlp/tts请求内容过长 |
| 4027 | 请求类型不能为空 |
| 4028 | 丢弃任务：同一用户不允许同时处理一个以上的ASR请求 |
| 4030 | NLP调用次数耗尽 |
| 4100 | 服务正在升级 请稍后再试 |
| 4101 | 请求没有正确初始化！ |
| 4102 | 长时间未请求业务,关闭连接 |
| 4200 | robot信息异常 |
| 4201 | nlp/tts处理异常 |
| 5002 | 未上传任何二进制数据 |