API接入说明
身份证识别API
描述
检测和识别中华人民共和国第二代身份证。
调用URL
https://api.megvii.com/faceid/v3/ocridcard
注意：在生产环境中，请使用HTTPS的通信方式。HTTP方式的通信属于不安全链路，存在安全风险，将无法得到服务可靠性保障。
调用方法
post
参数
| 可选/必选 | 参数名 | 类型 | 参数说明 |
|---|---|---|---|
| 必选 | api_key | String | 用于验证客户身份的API Key；对于每一个客户此字段不会变更，相当于用户名。 |
| 必选 | api_secret | String | 用于验证客户身份的API Secret；对于每一个客户可以申请变更此字段，相当于密码。 |
| 必选 | image | File | 一个图片，二进制文件，需要用Post Multipart/Form-Data的方式上传。 注：图片的文件大小小于10MB。支持的图片最小是200x200像素，最大是8000x8000像素。 |
| 可选 | return_portrait | String | 设定是否返回身份证上的人像（仅当传入的是身份证人像面图片，且识别到人脸才会返回，若没有识别到人脸，则不返回）。 “0”：不返回。默认值。 “1”：返回人像，JPG格式的base64。 注：如果是OCR国徽面，即使设定了此参数也不会返回。其他值均返回BAD_ARGUMENTS的错误信息。 |
返回值
| 图片类型 | 字段 | 类型 | 说明 |
|---|---|---|---|
| request_id | String | 用于区分每一次请求的唯一的字符串。除非发生404（API_NOT_FOUND )或 403 （AUTHORIZATION_ERROR）错误，此字段必定返回。 | |
| result | Int | 识别的结果信息： 1001: 表示识别出是一张没有问题的身份证； 1002: 表示识别出是一张身份证，但在识别结果中存在异常情况，其中异常情况包括： 1.有字段没有识别出来 2.识别的结果中存在逻辑问题（logic字段为1） 3.识别的字段上存在图片质量问题（quality字段低于默认的阈值） 4.识别的结果上存在合法性问题（legality字段的五分类结果不为真实身份证） 注：其他错误码请预留处理方案，我们可能增加其他情况的返回。 | |
| side | Int | 0: 表示传入的图片为身份证人像面 1: 表示传入的图片为身份证国徽面 | |
| 人像面 | 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 、长期。该字段为字典类型，相关的结构体信息请参照下面的“字段的结构体信息”表格 |
| legality | Dict | 返回身份证照片的合法性检查结果。它为一个结构体，里面包含身份证的五种分类及真实身份证判定阈值。结构体是按照key-value pair类型进行设计。其中身份证五种分类的概率值（取［0，1］区间实数，取3位有效数字，总和等于1）。
| |
| completeness | Int | 设表示身份证图片的完整性，平整性； 0: 表示图片里面的身份证是完整的 1: 表示图片里面的身份证不完整，但其关键信息内容区域全部都在图片内 2: 表示图片里面的身份证不完整，且有部分内容在区域外 注：其他错误码请预留处理方案，我们可能增加其他情况的返回。 | |
| 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 错误信息 |
字段的结构体信息
此函是为非必须函数，获取的SDK构筑信息便于后期定位问题，建议使用；
| 字段 | 类型 | 说明 |
|---|---|---|
| result | String | 表示字段识别出来的内容，若没有识别到，则返回空字符串 |
| quality | Float | 表示该区域是否存在质量问题（存在影响识别的光斑、阴影、遮挡、污渍等）。取［0，1］区间实数，3位有效数字。 注： 1.存在质量问题如果是光斑，部分遮挡，也是可以识别出内容的，本字段对存在留存需求的场景提供参考 2.当字段为“portrait”时，quality返回值暂时没有意义 3.系统对质量判断的默认阈值为0.15 |
| 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位、身份证号码的最后一位和性别匹配不上。通常当有逻辑问题的时候，认为识别出的结果是不可信的。 0: 表示正常 1: 表示存在逻辑问题 注：当字段为“portrait”时，logic返回值暂时没有意义。 |
返回值示例
人像面示例：
{
"result": 1002,
"completeness": 1,
"name": {
"quality": 0.956,
"result": "张三",
"rect": {
"rt": {
"y": 137,
"x": 385
},
"lt": {
"y": 136,
"x": 271
},
"lb": {
"y": 180,
"x": 271
},
"rb": {
"y": 181,
"x": 385
}
},
"logic": 0
},
"time_used": 442,
"gender": {
"quality": 0.968,
"result": "女",
"rect": {
"rt": {
"y": 225,
"x": 309
},
"lt": {
"y": 225,
"x": 275
},
"lb": {
"y": 261,
"x": 275
},
"rb": {
"y": 261,
"x": 309
}
},
"logic": 0
},
"address": {
"quality": 0.959,
"result": "北京市海淀区xxxxx",
"rect": {
"rt": {
"y": 388,
"x": 684
},
"lt": {
"y": 384,
"x": 269
},
"lb": {
"y": 474,
"x": 270
},
"rb": {
"y": 479,
"x": 683
}
},
"logic": 0
},
"card_rect": {
"rt": {
"y": 55,
"x": 1126
},
"lt": {
"y": 49,
"x": 89
},
"lb": {
"y": 680,
"x": 100
},
"rb": {
"y": 695,
"x": 1101
}
},
"request_id": "1526629075,8dcd4722-9f2b-42ca-a2c3-bae3a061b20f",
"idcard_number": {
"quality": 0.007,
"result": "110xxxxxx123456789",
"rect": {
"rt": {
"y": 593,
"x": 970
},
"lt": {
"y": 586,
"x": 416
},
"lb": {
"y": 622,
"x": 416
},
"rb": {
"y": 630,
"x": 968
}
},
"logic": 1
},
"birth_month": {
"quality": 0.995,
"result": "11",
"rect": {
"rt": {
"y": 306,
"x": 459
},
"lt": {
"y": 306,
"x": 435
},
"lb": {
"y": 337,
"x": 435
},
"rb": {
"y": 337,
"x": 459
}
},
"logic": 1
},
"portrait": {
"quality": 0,
"result": "/9j/4AAQSkZJRgABA...", //Base64字符串
"rect": {
"rt": {
"y": 307,
"x": 559
},
"lt": {
"y": 306,
"x": 526
},
"lb": {
"y": 338,
"x": 526
},
"rb": {
"y": 338,
"x": 558
}
},
"logic": 0
},
"birth_day": {
"quality": 0.995,
"result": "19",
"rect": {
"rt": {
"y": 307,
"x": 559
},
"lt": {
"y": 306,
"x": 526
},
"lb": {
"y": 338,
"x": 526
},
"rb": {
"y": 338,
"x": 558
}
},
"logic": 0
},
"nationality": {
"quality": 0.946,
"result": "汉",
"rect": {
"rt": {
"y": 230,
"x": 509
},
"lt": {
"y": 230,
"x": 474
},
"lb": {
"y": 265,
"x": 474
},
"rb": {
"y": 265,
"x": 508
}
},
"logic": 0
},
"birth_year": {
"quality": 0.983,
"result": "1989",
"rect": {
"rt": {
"y": 303,
"x": 347
},
"lt": {
"y": 303,
"x": 272
},
"lb": {
"y": 334,
"x": 272
},
"rb": {
"y": 335,
"x": 347
}
},
"logic": 1
},
"side": 0,
"legality": {
"Edited": 0,
"ID_Photo_Threshold": 0.8,
"Photocopy": 0,
"Temporary_ID_Photo": 0,
"ID_Photo": 0.001,
"Screen": 0.999
}
}
国徽面示例：
{
"result": 1001,
"time_used": 619,
"completeness": 0,
"legality": {
"Edited": 0,
"ID_Photo_Threshold": 0.8,
"Photocopy": 0,
"Temporary_ID_Photo": 0,
"ID_Photo": 0.999,
"Screen": 0.001
},
"request_id": "1527069951,2e8e2b3e-c06d-4771-8960-aad21f7b792a",
"valid_date_start": {
"quality": 0.921,
"result": "20140701",
"rect": {
"rt": {
"y": 931,
"x": 751
},
"lt": {
"y": 939,
"x": 388
},
"lb": {
"y": 973,
"x": 389
},
"rb": {
"y": 964,
"x": 753
}
},
"logic": 0
},
"issued_by": {
"quality": 0.902,
"result": "北京市海淀区公安局",
"rect": {
"rt": {
"y": 853,
"x": 752
},
"lt": {
"y": 861,
"x": 391
},
"lb": {
"y": 897,
"x": 392
},
"rb": {
"y": 888,
"x": 755
}
},
"logic": 0
},
"valid_date_end": {
"quality": 0.921,
"result": "20240701",
"rect": {
"rt": {
"y": 931,
"x": 751
},
"lt": {
"y": 939,
"x": 388
},
"lb": {
"y": 973,
"x": 389
},
"rb": {
"y": 964,
"x": 753
}
},
"logic": 0
},
"card_rect": {
"rt": {
"y": 451,
"x": 881
},
"lt": {
"y": 458,
"x": 5
},
"lb": {
"y": 1038,
"x": 4
},
"rb": {
"y": 1014,
"x": 926
}
},
"side": 1
}
特殊的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> | 缺少某个必选参数。 |
| 403 | AUTHENTICATION_ERROR | api_key和api_secret不匹配。 |
| 403 | AUTHORIZATION_ERROR:<reason> | api_key被停用、调用次数超限、没有调用此API的权限，或者没有以当前方式调用此API的权限。 1."DENIED." : api_key无权限或被停用 2."Limit reached." : 这个api_key对当前API的调用量达到上限。仅当api_key为测试key时返回 3.其他可能的错误码，请预留处理方案。 |
| 403 | CONCURRENCY_LIMIT_EXCEEDED | 并发数超过限制 |
| 403 | NON_ENTERPRISE_CERTIFICATION | 客户未进行企业认证 |
| 403 | BALANCE_NOT_ENOUGH | 余额不足 |
| 403 | ACCOUNT_DISABLED | 账户已停用 |
| 404 | API_NOT_FOUND | 所调用的API不存在 |
| 413 | Request Entity Too Large | 客户发送的请求大小或单张照片大小超过了10MB。该错误的返回格式为纯文本，不是json格式 |
| 500 | INTERNAL_ERROR | 服务器内部错误，当此类错误发生时请再次请求，如果持续出现此类错误，请及时联系 FaceID 客服或商务 |
调用示例
curl "https://api.megvii.com/faceid/v3/ocridcard" –F api_key=<api_key> -F api_secret=<api_secret> –F image=@id.jpg -F return_portrait=1