# 描述

检测和识别中华人民共和国第二代身份证。

# 调用URL

https://api.megvii.com/faceid/v3/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	String	设定是否返回身份证上的人像（仅当传入的身份证人像面图片，且识别到人脸才会返回，若没有识别到人脸，则不返回） “0”：不返回（默认值） “1”：返回人像，JPG格式的base64 注：如果是OCR国徽面，即使设定了此参数也不会返回，其他值均返回BAD_ARGUMENTS的错误信息
	exception_range	JsonObject	用于自定义纳入1002的异常情况的范围，可设置以下字段： "legality"：Bool类型，取值true（默认值）或者false。true表示将识别的结果上存在合法性问题（legality字段的五分类结果不为真实身份证）纳入1002，false表示不将其纳入1002 "text_quality"：Bool类型，取值true（默认值）或者false。true表示识别的字段上存在图片质量问题（quality字段低于默认的阈值）纳入1002，false表示不将其纳入1002 "logic"：Bool类型，取值true（默认值）或者false。true表示将识别的结果存在逻辑问题（logic字段为1）or存在字段没识别出来纳入1002，false代表不将其纳入1002 "completeness"：Bool类型，取值true或者false（默认值）。true表示将身份证不完整（completeness为1或2）纳入1002，false表示不将其纳入1002 "face_detect"：Bool类型，取值true或者false（默认值）。true代表将身份证人像面不存在人脸纳入1002，false代表不将其纳入1002
	encryption_type	String	设定是否开启传输数据加密 “0”：否（默认值） “1”：SM2 “2”：RSA 加密对象说明: 参数中的image 传入的身份证图片为人像面与国徽面时，返回对应的字段，包括name，gender，nationality，birth_year，birth_month，birth_day，idcard_number，address，portrait，issued_by，valid_date_start，valid_date_end 详细说明见：OCR加密说明

# 返回值说明

返回值条件	字段	类型	说明
不区分正反面，都会返回右列的值	request_id	String	用于区分每一次请求的唯一的字符串。除非发生404（API_NOT_FOUND )或 403 （AUTHORIZATION_ERROR）错误，此字段必定返回
	result	Int	识别的结果信息： 1001: 表示识别出是一张没有问题的身份证 1002: 表示识别出是一张身份证，但在识别结果中存在异常情况，异常情况范围可通过exception_range字段自定义，默认异常情况包括：有字段没有识别出来识别的结果中存在逻辑问题（logic字段为1）识别的字段上存在图片质量问题（quality字段低于默认的阈值）识别的结果上存在合法性问题（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） ID_Photo：分类1 - 真实身份证照片 Temporary_ID_Photo：分类2 - 临时身份证照片 Photocopy：分类3 - 身份证的复印件 Screen：分类4 - 手机或电脑屏幕翻拍的照片 Edited：分类5 - 用工具合成或者编辑过的身份证图片 ID_Photo_Threshold：表示判断为真实身份证照片的阈值，通常来说，如果ID_Photo的值不低于该阈值，则可以认定为真实拍摄的注：随产品迭代，未来会增加新的分类，因此在集成此API时请留意兼容性
	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 错误信息

# 字段的结构体信息

+result	String	表示字段识别出来的内容，若没有识别到，则返回空字符串
+quality	Float	表示该区域是否存在质量问题（存在影响识别的光斑、阴影、遮挡、污渍等）。取［0，1］区间实数，3位有效数字注：存在质量问题如果是光斑，部分遮挡，也是可以识别出内容的，本字段对存在留存需求的场景提供参考当字段为“portrait”时，quality返回值暂时没有意义系统对质量判断的默认阈值为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: 表示存在逻辑问题

# 返回值示例

人像面示例

{
    "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>	缺少某个必选参数
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/v3/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（旧版本）文档。