1、接口描述
针对图片中的文字,进行OCR检测,返回检测到的文字内容及坐标信息。
2、请求方法
POST
3、接口要求
- 图片格式限制:图片格式支持 png、jpg、jpeg、bmp格式
- 图片大小限制:单张图片大小不超过 10MB, 批量请求单次不超过 50张
- 图片尺寸限制:图片像素尺寸应大于 32x32 ,小于 5000x5000
4、URI
/v1/aiop/api/2f3p1pnxpqm8/ocrdetect/ocr/v1/image.json
5、请求参数
请求头header参数(详细说明可参考API参考>如何调用API章节)
参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
---|---|---|---|---|---|
Content-Type | 是 | String | json 格式 | application/json | |
appkey | 是 | String | 诸葛 AI 应用 appkey | 562b89493b1a40e1b97ea05e50dd8170 | |
ctyun-eop-request-id | 是 | String | 用户请求 id,由用户构造,用户可以通过 uuid 等方法自行生成唯一字符串,用于日志请求追踪。 详见文档:API参考-如何调用API-Python3 调用示例 |
33dfa732-b27b-464f-b15a-21ed6845afd5 | |
eop-date | 是 | String | 请求时间,由用户构造,形如 yyyymmddTHHMMSSZ。 详见文档:API参考-如何调用API-Python3 调用示例 |
20211221T163014Z | |
host | 是 | String | 终端节点域名,固定字段 | ai-global.ctapi.ctyun.cn | |
Eop-Authorization | 是 | String | 由天翼云官网 accessKey 和 securityKey 经签名后生成,参与签名生成的字段包括天翼云官网 accessKey 、securityKey、诸葛AI平台的 appkey(非必须),用户请求 id(非必须),请求时间,终端节点域名(非必须)以及请求体内容。 签名逻辑详见文档:API参考-如何调用API-认证鉴权和Python3 调用示例 |
请求体body参数
参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
---|---|---|---|---|---|
data | 是 | List | 一张或多张图像Base64编码数据构成的list。注意:图片需要使用常规base64编码方式 | _9j_4AAQSkZJRg... |
6、请求代码示例
Curl -X POST "https://ai-global.ctapi.ctyun.cn/v1/aiop/api/2f3p1pnxpqm8/ocrdetect/ocr/v1/image.json"
-H "Content-Type: application/json"
-H "ctyun-eop-request-id:33dfa732-b27b-464f-b15a-21ed6845afd5"
-H "appkey:XXX"
-H "Eop-Authorization:XXX"
-H "eop-date:20211109T104641Z"
-H "host:ai-global.ctapi.ctyun.cn"
--data '{"data":["AAAAAAAAA...."]}'
7、返回值说明
请求成功返回响应参数
参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
---|---|---|---|---|---|
statusCode | 是 | Int | 请求响应状态码 | 0 | |
message | 是 | Object | 请求信息结构体,message["success"]代表请求list中的成功数量,message["fail"]代表请求list中的失败数量。 | success | |
returnObj | 是 | Object | 识别的结果,按照列表形式排列,每个元素为图片对应的鉴定结果键值对,元素排序按照传入顺序排列,元素中包括识别到的文本行数目,位置以及文本行内容 | returnObj |
表message
参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
---|---|---|---|---|---|
success | 否 | Int | 成功标识 | 1 | |
fail | 否 | Int | 错误标识 | 0 |
表returnObj
参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
---|---|---|---|---|---|
text_line | 否 | Int | 图片识别到的文字行数 | - | |
detail | 否 | Object | 按照列表形式排列,每个元素为图片中每一个识别到的文本行的具体信息,包含位置以及文本行内容 | - | detail |
表detail
参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
---|---|---|---|---|---|
name | 否 | String | 序号 | - | |
text | 否 | String | 识别到的文字 | - | |
box | 否 | List | 文字所在的坐标为8个浮点数构成的数组,8个浮点数依次分别表示左上、右上、右下、左下四个点的x坐标,y坐标。 | - |
请求失败返回响应参数
参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
---|---|---|---|---|---|
statusCode | 是 | Int | 错误码,参见本文档错误码说明部分 | 4003 | |
message | 是 | String/Object | 返回对应的可读消息,值为error | error | message |
details | 是 | String | 返回对应的错误信息 | 请求中未包data字段 | |
returnObj | 否 | Object | 返回对应的错误编码和错误信息 | returnObj |
表message
参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
---|---|---|---|---|---|
success | 否 | Int | 成功标识 | 0 | |
fail | 否 | Int | 错误标识 | 1 |
表returnObj
参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
---|---|---|---|---|---|
errorCode | 是 | String | 错误码 | 4008 | |
errorMessage | 是 | String | 错误信息 | base64数据处理异常 |
8、返回值示例
请求成功返回值示例
{
'statusCode': 0,
'message': {'success' : 1, 'fail' : 0},
'returnObj': [
{
'text_line': 2,
'detail': [
{
'name': '0',
'text': '社会主义核心价值观',
'box': [
43.3963039677,
157.3534469991,
610.5843128949,
169.5419591656,
609.1529514034,
236.1498488994,
41.9649424762,
223.9613367328
]
},
{
'name': '1',
'text': '富强、民主、文明、和谐',
'box': [
84.6885821036,
244.0079416001,
573.8530589198,
248.174096093,
573.4117596933,
299.9887625014,
84.2472828771,
295.8226080086
]
}
]
}
]
}
请求失败返回值示例
示例1:
{
"statusCode": 4003,
"message": "error",
"details": "请求中未包data字段",
"error":"AI_OP_4003"
}
示例2:处理失败返回值示例
{
'statusCode': 0,
'message': {'success': 0, 'fail': 1},
'returnObj': [{'err_code': 4008, 'err_msg': 'base64数据处理异常'}]
}
9、状态码
http状态码 | 描述 |
---|---|
200 | 表示请求成功。 |
10、错误码说明
4 位错误码。4 开头为业务错误码,5 开头为服务错误码。全局请求返回错误码请参考章节API概览>状态码
错误码 | 错误信息 | 错误描述 |
---|---|---|
AI_OP_4001 | 请求JSON处理异常 | 请求JSON处理异常 |
AI_OP_4002 | body传入不是字典 | body传入不是字典 |
AI_OP_4003 | 请求中未包data字段 | 请求中未包data字段 |
AI_OP_4004 | data字段图片数据不是list格式 | data字段图片数据不是list格式 |
AI_OP_4005 | 图片list内图片数量为0 | 图片list内图片数量为0 |
AI_OP_4006 | 图片list内图片数量超过50张 | 图片list内图片数量超过50张 |
AI_OP_4008 | base64数据处理异常 | base64数据处理异常 |
AI_OP_4009 | 请求文件格式不合法,仅支持 jpeg/png/jpg/bmp 格式 | 请求文件格式不合法,仅支持 jpeg/png/jpg/bmp 格式 |
AI_OP_4010 | 单张图片大小超过10M | 单张图片大小超过10M |
AI_OP_4011 | 图片尺寸不符合要求,分辨率长宽尺寸应不高于5000不低于32 | 图片尺寸不符合要求,分辨率长宽尺寸应不高于5000不低于32 |
AI_OP_5000 | OCR服务接口异常,请联系管理员 | OCR服务接口异常,请联系管理员 |
11、base64 编码规则:使用常规的 safe base64 编码方式
- python 中推荐使用
base64.urlsafe_b64encode()
函数进行编码。 - java 中推荐使用
BASE64.getUrlEncoder().encodeToString()
函数进行编码。