接入文档
证件OCR识别
身份证识别接入
API接入
API接入

# 描述

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

# 调用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的错误信息
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: 表示识别出是一张身份证,但在识别结果中存在异常情况,其中异常情况包括:
    • 有字段没有识别出来
    • 识别的结果中存在逻辑问题(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(旧版本)文档

    该文档未解决您的疑问?查看常见问题