接入文档
证件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 设定是否返回身份证上的人像（仅当传入的身份证人像面图片，且识别到人脸才会返回，若没有识别到人脸，则不返回）
  • “0”：不返回（默认值）
  • “1”：返回人像，JPG格式的base64
注：如果是OCR国徽面，即使设定了此参数也不会返回，其他值均返回BAD_ARGUMENTS的错误信息
encryption_type int 设定是否开启传输数据加密
  • “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加密说明
warn_config String 用于设置告警类型，以下可选字段均为json格式字符串，bool类型，默认false不返回：
  • legality告警分类
      • photocopy身份证复印件告警
      screen身份证翻拍告警
      temporary_id_photo 临时身份证告警
      edited 身份证疑似存在PS痕迹告警
  • logic 识别的结果中存在逻辑问题
  • logic_amend修正告警问题
  • completeness完整性告警
  • quality质量告警
  • field字段识别不出来告警在
配置示例：
{ "legality": {"photocopy": true,"screen": false,"temporary_id_photo ": false,"edited ": false}, "logic": false, "quality": false, "completeness": false, "field": false }
mobilize_type int 设定调用API类型
  • “0”：SDK
  • “1”：H5
  • “2”：其他（默认值）

# 返回值说明

返回值条件 字段 类型 说明
不区分正反面，都会返回右列的值 request_id String 用于区分每一次请求的唯一的字符串。除非发生404（API_NOT_FOUND )或 403 （AUTHORIZATION_ERROR）错误，此字段必定返回
result Int 识别的结果信息：
  • 1001: 表示识别出是一张没有问题的身份证
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 、长期。该字段为字典类型，相关的结构体信息请参照下面的“字段的结构体信息”表格
    不区分正反面，都会返回右列的值 warninfos jsonObject
    告警信息。
    告警类别可以同时出现一个或多个；
    同类告警可以出现一个或多个；
    扩展信息，不请求则不返回warninfos字段；
    { "legality": [ 1, 2, 3 ], "logic": [ 1, 2, 3 ], "completeness": [ 1 ], "quality": [ "name", "gender", "nationality", "..." ], "field": [ "name", "gender", "nationality", "..." ] }
    legality 分类告警
    • 1：photocopy身份证复印件告警，
    • 2：screen身份证翻拍告警，
    • 3：temporary_id_photo 临时身份证告警，
    • 4：edited 身份证疑似存在PS痕迹告警，
    logic 识别的结果中存在逻辑问题
    • 1：身份证号逻辑不合法
    • 2：身份证号与出生年字段逻辑不合法
    • 3：身份证号与出生月字段逻辑不合法
    • 4：身份证号与出生日字段逻辑不合法
    • 5：身份证号与性别字段逻辑不合法
    • 6：身份证有效日期不合法
    logic_amend修正告警问题
    修正告警字段说明
    gender性别修正告警
    birth_year出生年份修正告警
    birth_month出生月数修正告警
    birth_day出生日修正告警
    completeness完整性告警
    • 0：表示图片里面的身份证是完整的
    • 1：表示图片里面的身份证不完整，但其关键信息内容区域全部都在图片内
    • 2：表示图片里面的身份证不完整，且有部分内容在区域外
    quality质量告警，展示质量告警字段：
    质量告警字段说明
    name姓名质量告警
    gender性别质量告警
    nationality民族质量告警
    birth_year出生年份质量告警
    birth_month出生月数质量告警
    birth_day出生日质量告警
    idcard_number身份证号质量告警
    address住址质量告警
    portrait身份证图片上的头像图片质量告警
    issued_by签发机关质量告警
    valid_date_start有效日期的起始时间质量告警
    valid_date_end有效日期的结束时间质量告警
    field字段未识别告警，展示未能识别字段：
    未识别告警字段说明
    name姓名未识别
    gender性别未识别
    nationality民族未识别
    birth_year出生年份未识别
    birth_month出生月数未识别
    birth_day出生日未识别
    idcard_number身份证号未识别
    address住址未识别
    portrait身份证图片上的头像图片未识别
    issued_by签发机关未识别
    valid_date_start有效日期的起始时间未识别
    valid_date_end有效日期的结束时间未识别
    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位有效数字
    注：
    • 存在质量问题如果是光斑，部分遮挡，也是可以识别出内容的，本字段对存在留存需求的场景提供参考
    • 系统对质量判断的默认阈值为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": 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（旧版本）文档。

    该文档未解决您的疑问？查看常见问题
    Copyright © 2024 北京旷视科技有限公司