1、接口描述
针对图片中的身份证,进行OCR检测,返回检测到的姓名、身份证号码等信息。
2、请求方法
POST
3、接口要求
- 图片格式限制:目前仅支持 jpg、jpeg、png、bmp 等常见格式
- 图片大小限制:图片单张大小不超过 10MB,批量请求单次不超过 50张
- 图片尺寸限制:图片像素尺寸应大于 32x32,小于 5000x5000
4、URI
/v1/aiop/api/2f3os7qq79xc/IdentityCard/ocr/v1/idcard.json
5、请求参数
请求头header参数
参数 |
是否必填 |
参数类型 |
说明 |
示例 |
下级对象 |
Content-Type |
是 |
String |
json 格式 |
application/json |
|
appkey |
是 |
String |
平台应用appkey |
562b89493b1a40e1b97ea05e50dd8170 |
|
ctyun-eop-request-id |
是 |
String |
用户请求 id,由用户构造,用户可以通过 uuid 等方法自行生成唯一字符串,用于日志请求追踪。 详见文档:Python3调用示例 |
33dfa732-b27b-464f-b15a-21ed6845afd5 |
|
eop-date |
是 |
String |
请求时间,由用户构造,形如 yyyymmddTHHMMSSZ。 详见文档:Python3调用示例 |
20211221T163014Z |
|
host |
是 |
String |
终端节点域名,固定字段 |
ai-global.ctapi.ctyun.cn |
|
Eop-Authorization |
是 |
String |
由天翼云官网 accessKey 和 securityKey 经签名后生成,参与签名生成的字段包括天翼云官网 accessKey 、securityKey、平台应用的appkey(非必须),用户请求 id(非必须),请求时间,终端节点域名(非必须)以及请求体内容。 签名逻辑详见文档:认证鉴权和Python3调用示例 |
|
|
请求体body参数
参数 |
是否必填 |
参数类型 |
说明 |
示例 |
下级对象 |
data |
是 |
List |
一张或多张图像Base64编码字符串构成的list。注意:图片需要使用常规safe base64编码方式,不包含前缀 "data:img/jpg;base64," |
_9j_4AAQSkZJRg... |
|
6、请求代码示例
Curl -X POST
"https://ai-global.ctapi.ctyun.cn/v1/aiop/api/2f3os7qq79xc/IdentityCard/ocr/v1/idcard.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":["_9j_4AAQSkZJRg..."]}'
7、返回值说明
请求成功返回响应参数
参数 |
是否必填 |
参数类型 |
说明 |
示例 |
下级对象 |
statusCode |
是 |
Int |
请求响应状态码,返回 0 表示成功,返回错误代码参考下面的错误代码列表 |
0 |
|
message |
是 |
Object |
请求信息结构体,message["success"]代表请求list中的成功数量,message["fail"]代表请求list中的失败数量 |
|
message |
returnObj |
是 |
List |
识别的结果,按照列表形式排列,每个元素为图片对应的鉴定结果键值对,元素排序按照传入顺序排列,元素中包括身份证正反面信息,以及姓名、性别、身份证号码等信息 |
|
returnObj |
表message
参数 |
是否必填 |
参数类型 |
说明 |
示例 |
下级对象 |
success |
否 |
Int |
成功标识 |
1 |
|
fail |
否 |
Int |
错误标识 |
0 |
|
表returnObj
参数 |
是否必填 |
参数类型 |
说明 |
示例 |
下级对象 |
note |
是 |
String |
身份的正面或反面信息,国徽面为正面:front,人像面为反面:back |
back |
|
detail |
是 |
Object |
返回结果键值集合,包含姓名、性别、身份证号码等信 |
|
detail |
idcard_face |
是 |
String |
此API无法截取人像面身份证的人像子图,此字段固定为'no face' |
no face |
|
demo_image |
是 |
String |
无效字段(可忽略) |
demo_image |
|
risk |
是 |
String |
此API无法对身份证复印件进行判断,此字段固定为'normal' |
normal |
|
表detail
参数 |
是否必填 |
参数类型 |
说明 |
示例 |
下级对象 |
name |
是 |
String |
姓名 |
陈XX |
|
sex |
是 |
String |
性别 |
男 |
|
nation |
是 |
String |
民族 |
汉 |
|
birthday |
是 |
String |
出生日期 |
1995XX25 |
|
idn |
是 |
String |
身份证号 |
3101001995XX25XX16 |
|
addr |
是 |
String |
住址 |
上海市XX区XX路1号 |
|
org |
是 |
String |
签发机关 |
上海市公安局XX分局 |
|
validperiod |
是 |
String |
有效期限 |
2007.07.27-2027.07.27 |
|
请求失败返回响应参数
参数 |
是否必填 |
参数类型 |
说明 |
示例 |
下级对象 |
statusCode |
是 |
Int |
错误码,放置API对应的错误码 |
4004 |
|
message |
是 |
String/Object |
请求失败时返回值为'error'或{'success':0,'fail':1} |
error |
message |
details |
否 |
String |
返回对应的错误描述 |
data字段图片数据不是list格式 |
|
returnObj |
否 |
List |
返回对应的错误编码和错误信息 |
|
returnObj |
error |
是 |
String |
返回对应的错误码 |
AI_OP_4004 |
|
表returnObj
参数 |
是否必填 |
参数类型 |
说明 |
示例 |
下级对象 |
err_code |
是 |
Int |
错误码 |
4008 |
|
err_msg |
是 |
String |
错误信息 |
base64数据处理异常 |
|
8、返回值示例
请求成功返回值示例
{
"statusCode": 0,
"message": {"success" : 1, "fail" : 0},
"returnObj": [{
"note": "front",
"detail": {
"name": "",
"sex": "",
"nation": "",
"birthday": "",
"idn": "",
"addr": "",
"org": "兰州市公安局城关分局",
"validperiod": "2007.07.27-2027.07.27"
},
"idcard_face": "no face",
"demo_image": "demo_image",
"risk": "normal"
}]
}
请求失败返回值示例
示例1:
{
"statusCode": 4004,
"message": "error",
"details": "data字段图片数据不是list格式",
"error":"AI_OP_4004"
}
示例2:处理失败返回值示例
{
'statusCode': 0,
'message': {'success': 0, 'fail': 1},
'returnObj': [{'err_code': 4008, 'err_msg': 'base64数据处理异常'}]
}
9、状态码
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_4012 |
请求方法错误,请使用POST请求 |
请求方法错误,请使用POST请求 |
AI_OP_4013 |
无效的请求路径,请确保请求路径正确 |
无效的请求路径,请确保请求路径正确 |
AI_OP_5000 |
OCR服务接口异常,请联系管理员 |
OCR服务接口异常,请联系管理员 |
11、base64 编码规则:使用常规的 safe base64 编码方式
- python 中推荐使用
base64.urlsafe_b64encode()
函数进行编码
- java 中推荐使用
BASE64.getUrlEncoder().encodeToString()
函数进行编码