接入文档
证件OCR识别
身份证识别增强版接入
API接入
API接入
# 描述
检测和识别中华人民共和国第二代身份证。
# 调用URL
https://api.megvii.com/faceid/v5/ocridcard
注意：在生产环境中，请使用HTTPS的通信方式。HTTP方式的通信属于不安全链路，存在安全风险，请勿在生产环境中使用。在生产环境中使用HTTP方式的，将无法得到服务可靠性保障。
# 调用方法
POST 注意：用form-data格式请求
参数
| 必选/可选 | 参数名 | 类型 | 参数说明 |
| 必选 | api_key | String | 用于验证客户身份的API key，对于每一个客户此字段不会变更，相当于用户名 |
| api_secret | String | 用于验证客户身份的API secret，对于每一个客户可以申请变更此字段，相当于密码 | |
| image | File |
一个图片，二进制文件，需要用Post Multipart/Form-Data的方式上传
注：图片的文件大小小于10MB。支持的图片最小是200x200像素，最大是8000x8000像素 |
|
| 可选 | return_portrait | int |
设定是否返回身份证上的人像（仅当传入的身份证人像面图片，且识别到人脸才会返回，若没有识别到人脸，则不返回）
|
| encryption_type | int |
设定是否开启传输数据加密
|
|
| warn_config | String |
用于设置告警类型，以下可选字段均为json格式字符串，bool类型，默认false不返回：
screen身份证翻拍告警 temporary_id_photo 临时身份证告警 edited 身份证疑似存在PS痕迹告警 { "legality": {"photocopy": true,"screen": false,"temporary_id_photo ": false,"edited ": false}, "logic": false, "quality": false, "completeness": false, "field": false } |
|
| mobilize_type | int |
设定调用API类型
|
# 返回值说明
| 返回值条件 | 字段 | 类型 | 说明 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 不区分正反面，都会返回右列的值 | request_id | String | 用于区分每一次请求的唯一的字符串。除非发生404（API_NOT_FOUND )或 403 （AUTHORIZATION_ERROR）错误，此字段必定返回 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| result | Int |
识别的结果信息：
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| side | Int |
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 传入的身份证图片为人像面时，返回对应的字段 | name | Dict | 姓名。该字段为字典类型，相关的结构体信息请参照下面的“字段的结构体信息”表格 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| gender | Dict | 性别（男/女）。该字段为字典类型，相关的结构体信息请参照下面的“字段的结构体信息”表格 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| nationality | Dict | 民族（汉字）。该字段为字典类型，相关的结构体信息请参照下面的“字段的结构体信息”表格 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| birth_year | Dict | 出生年份。该字段为字典类型，相关的结构体信息请参照下面的“字段的结构体信息”表格 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| birth_month | Dict | 出生月数。该字段为字典类型，相关的结构体信息请参照下面的“字段的结构体信息”表格 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| birth_day | Dict | 出生日。该字段为字典类型，相关的结构体信息请参照下面的“字段的结构体信息”表格 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| idcard_number | Dict | 身份证号。该字段为字典类型，相关的结构体信息请参照下面的“字段的结构体信息”表格 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| address | Dict | 住址。该字段为字典类型，相关的结构体信息请参照下面的“字段的结构体信息”表格 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| portrait | Dict | 身份证图片上的头像图片，仅在return_portrait参数设定为1时返回，头像照片采用JPG格式的base64表示 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 传入的身份证图片为国徽面时，返回对应的字段 | issued_by | Dict | 签发机关。该字段为字典类型，相关的结构体信息请参照下面的“字段的结构体信息”表格 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| valid_date_start | Dict | 有效日期的起始时间，表示方法为8位数字，如：20150302 。该字段为字典类型，相关的结构体信息请参照下面的“字段的结构体信息”表格 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| valid_date_end | Dict | 有效日期的结束时间，表示方法为8位数字或者汉字，如：20250302 、长期。该字段为字典类型，相关的结构体信息请参照下面的“字段的结构体信息”表格 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 不区分正反面，都会返回右列的值 | warninfos | jsonObject |
告警信息。
告警类别可以同时出现一个或多个；
同类告警可以出现一个或多个； 扩展信息，不请求则不返回warninfos字段； { "legality": [ 1, 2, 3 ], "logic": [ 1, 2, 3 ], "completeness": [ 1 ], "quality": [ "name", "gender", "nationality", "..." ], "field": [ "name", "gender", "nationality", "..." ] } legality 分类告警
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| completeness | Int |
表示身份证图片的完整性，平整性
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| card_rect | Dict |
返回图片里面，身份证卡片的四点坐标，坐标的开始位置为图片左上角，具体返回示例如下：
"rt"{ "y":43, "x":927 } //右上角坐标 "lt"{ "y":33, "x":58 } //左上角坐标 "lb"{ "y":586, "x":59 } //左下角坐标 "rb"{ "y":580, "x":920 } //右下角坐标 注：当字段的区域没有识别出来的时候，各个坐标点的x和y均返回为0 |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| error | String | 发生错误后，会返回对应的错误码，具体见下面 ERROR 错误信息 |
# 字段的结构体信息
| +result | String | 表示字段识别出来的内容，若没有识别到，则返回空字符串 |
| +quality | Float |
表示该区域是否存在质量问题（存在影响识别的光斑、阴影、遮挡、污渍等）。取［0，1］区间实数，3位有效数字
注：
|
| +rect | Dict |
返回字典结构，里面包含该字段区域的四点坐标，具体返回示例如下：
"rt"{ "y":43, "x":927 } //右上角坐标 "lt"{ "y":33, "x":58 } //左上角坐标 "lb"{ "y":586, "x":59 } //左下角坐标 "rb"{ "y":580, "x":920 } //右下角坐标 注：当字段的区域没有识别出来的时候，各个坐标点的x和y均返回为0 |
| +logic | Int |
表示该字段是否存在逻辑问题。如：识别身份证号因遮挡无法识别到18位、身份证号码的最后一位和性别匹配不上。通常当有逻辑问题的时候，认为识别出的结果是不可信的
|
# 返回值示例
人像面示例
{
"result": 1001,
"completeness": 0, ##此返回值为兼容基础版考虑在增强版接口中仍会单独返回，忽略即可，请参考warninfos中的completeness
"name": {
"quality": 0.691,
"result": "XXX",
"rect": {
"rt": {
"y": 975,
"x": 1404
},
"lt": {
"y": 612,
"x": 1402
},
"lb": {
"y": 613,
"x": 1285
},
"rb": {
"y": 976,
"x": 1287
}
},
"logic": 0
},
"time_used": 1358,
"gender": {
"quality": 0.745,
"result": "男",
"rect": {
"rt": {
"y": 692,
"x": 1178
},
"lt": {
"y": 621,
"x": 1178
},
"lb": {
"y": 622,
"x": 1103
},
"rb": {
"y": 693,
"x": 1104
}
},
"logic": 0
},
"warninfos": {
"quality": [
"idcard_number"
]
},
"address": {
"quality": 0.648,
"result": "宁夏XXXXXXXXXXXX",
"rect": {
"rt": {
"y": 1673,
"x": 811
},
"lt": {
"y": 567,
"x": 793
},
"lb": {
"y": 568,
"x": 506
},
"rb": {
"y": 1678,
"x": 529
}
},
"logic": 0
},
"card_rect": {
"rt": {
"y": 2557,
"x": 1628
},
"lt": {
"y": 117,
"x": 1630
},
"lb": {
"y": 115,
"x": 12
},
"rb": {
"y": 2599,
"x": 87
}
},
"request_id": "1720425874,3f721ece-fa83-421f-8b11-8df4c6833754",
"idcard_number": {
"quality": 0.03,
"result": "6422XXXXXXXXXXXXX8",
"rect": {
"rt": {
"y": 2324,
"x": 333
},
"lt": {
"y": 993,
"x": 300
},
"lb": {
"y": 994,
"x": 194
},
"rb": {
"y": 2327,
"x": 230
}
},
"logic": 0
},
"birth_month": {
"quality": 0.775,
"result": "8",
"rect": {
"rt": {
"y": 1059,
"x": 988
},
"lt": {
"y": 1015,
"x": 987
},
"lb": {
"y": 1015,
"x": 924
},
"rb": {
"y": 1059,
"x": 925
}
},
"logic": 0
},
"birth_day": {
"quality": 0.785,
"result": "9",
"rect": {
"rt": {
"y": 1292,
"x": 989
},
"lt": {
"y": 1248,
"x": 989
},
"lb": {
"y": 1249,
"x": 925
},
"rb": {
"y": 1293,
"x": 926
}
},
"logic": 0
},
"nationality": {
"quality": 0.77,
"result": "回",
"rect": {
"rt": {
"y": 1191,
"x": 1178
},
"lt": {
"y": 1125,
"x": 1177
},
"lb": {
"y": 1126,
"x": 1106
},
"rb": {
"y": 1192,
"x": 1106
}
},
"logic": 0
},
"birth_year": {
"quality": 0.742,
"result": "1980",
"rect": {
"rt": {
"y": 839,
"x": 1006
},
"lt": {
"y": 596,
"x": 1003
},
"lb": {
"y": 596,
"x": 901
},
"rb": {
"y": 840,
"x": 904
}
},
"logic": 0
},
"side": 0,
"legality": { ##此返回值为兼容基础版考虑在增强版接口中仍会单独返回，忽略即可，请参考warninfos中的legality
"Edited": 0.0,
"ID_Photo_Threshold": 0.8,
"Photocopy": 0.009,
"Temporary_ID_Photo": 0.0,
"ID_Photo": 0.991,
"Screen": 0.0
}
}
##基于兼容性考虑logic在增强版接口中仍会单独返回，忽略即可，请参考warninfos中的logic
国徽面示例
{
"result": 1001,
"time_used": 421,
"completeness": 0, ##此返回值为兼容基础版考虑在增强版接口中仍会单独返回，忽略即可，请参考warninfos中的completeness
"legality": { ##此返回值为兼容基础版考虑在增强版接口中仍会单独返回，忽略即可，请参考warninfos中的legality
"Edited": 0.0,
"ID_Photo_Threshold": 0.8,
"Photocopy": 0.0,
"Temporary_ID_Photo": 0.0,
"ID_Photo": 1.0,
"Screen": 0.0
},
"request_id": "1720426004,2837495f-1c8b-4797-baa2-337f49c339f8",
"valid_date_start": {
"quality": 0.872,
"result": "20180704",
"rect": {
"rt": {
"y": 265,
"x": 422
},
"lt": {
"y": 263,
"x": 237
},
"lb": {
"y": 283,
"x": 237
},
"rb": {
"y": 284,
"x": 422
}
},
"logic": 0
},
"issued_by": {
"quality": 0.832,
"result": "合肥XXXXXX分局",
"rect": {
"rt": {
"y": 226,
"x": 412
},
"lt": {
"y": 224,
"x": 239
},
"lb": {
"y": 244,
"x": 239
},
"rb": {
"y": 246,
"x": 413
}
},
"logic": 0
},
"valid_date_end": {
"quality": 0.872,
"result": "20380704",
"rect": {
"rt": {
"y": 265,
"x": 422
},
"lt": {
"y": 263,
"x": 237
},
"lb": {
"y": 283,
"x": 237
},
"rb": {
"y": 284,
"x": 422
}
},
"logic": 0
},
"card_rect": {
"rt": {
"y": 37,
"x": 488
},
"lt": {
"y": 25,
"x": 46
},
"lb": {
"y": 310,
"x": 32
},
"rb": {
"y": 314,
"x": 502
}
},
"side": 1
}
##基于兼容性考虑logic在增强版接口中仍会单独返回，忽略即可，请参考warninfos中的logic
# 特殊的ERROR
| HTTP 状态代码 | 错误信息 | 说明 |
|---|---|---|
| 400 | ID_CARD_NOT_FOUND | 图片中没有找到身份证 |
| 400 | INVALID_IMAGE_SIZE: image | 图片的像素不符合要求，图片像素多大或者过小 |
| 400 | IMAGE_ERROR_UNSUPPORTED_FORMAT: image | 图片解析失败 |
# 错误信息
HTTP 状态代码 |
错误信息 | 说明 |
|---|---|---|
| 400 | BAD_ARGUMENTS: <key> | 某个参数解析出错（比如必须是数字，但是输入的是非数字字符串; 或者长度过长，或者照片无法解析） |
| 400 | MISSING_ARGUMENTS: <key> | 缺少某个必选参数 |
| 400 | KEY_NOT_FOUND | encryption_type开启加密，但未配置加密公钥和解密私钥 |
| 403 | AUTHENTICATION_ERROR | api_key和api_secret不匹配 |
| 403 | AUTHORIZATION_ERROR:<reason> | api_key被停用、调用次数超限、没有调用此API的权限，或者没有以当前方式调用此API的权限。<reason>取值："DENIED." : api_key无权限或被停用"Limit reached." : 这个api_key对当前API的调用量达到上限。仅当api_key为测试key时返回 其他可能的错误码，请预留处理方案 |
| 403 | CONCURRENCY_LIMIT_EXCEEDED | 并发数超过限制 |
| 404 | API_NOT_FOUND | 所调用的API不存在 |
| 413 | Request Entity Too Large | 客户发送的请求大小或单张照片大小超过了10MB。该错误的返回格式为纯文本，不是json格式 |
| 500 | INTERNAL_ERROR | 服务器内部错误，当此类错误发生时请再次请求，如果持续出现此类错误，请及时联系 FaceID 客服或商务 |
# 调用示例
curl "https://api.megvii.com/faceid/v5/ocridcard" –F api_key=<api_key> -F api_secret=<api_secret> –F image=@id.jpg -F return_portrait=1
# 历史版本文档
身份证OCR识别API的第一个发行版本。由于V2.0.0以上的版本并不兼容老版本API，因此如有需要V1.0.0版本的文档，请从这里下载：OCRIDCard V1.0.0（旧版本）文档。
该文档未解决您的疑问？
查看常见问题
查看常见问题