文档首页 > > API参考> API>

护照识别

护照识别

分享
更新时间:2021/03/17 GMT+08:00

功能介绍

识别护照首页图片中的文字信息,并以json格式返回识别的结构化结果。

当前版本支持中国护照的全字段识别。外国护照支持护照下方两行国际标准化的机读码识别,并可从中提取6-7个关键字段信息。该接口的使用限制请参见约束与限制,详细使用指导请参见OCR服务使用简介章节。

图1 护照识别示例图

如果图片中包含多张卡证票据,请调用智能分类识别服务。

调试

您可以在API Explorer中调试该接口。

前提条件

在使用护照识别之前,需要您完成服务申请和认证鉴权,具体操作流程请参见申请服务认证鉴权章节。

URI

POST https://{endpoint}/v2/{project_id}/ocr/passport

表1 路径参数

参数

是否必选

说明

endpoint

指定承载REST服务端点的服务器域名或IP,不同服务不同区域的endpoint不同,您可以从终端节点中获取。

例如,OCR服务在“华北-北京四”区域的“endpoint”“ocr.cn-north-4.myhuaweicloud.com”

project_id

项目ID,您可以从获取项目ID中获取。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

String

用户Token。

Token认证就是在调用API的时候将Token加到请求消息头,从而通过身份认证,获得操作API的权限,响应消息头中X-Subject-Token的值即为Token。

Content-Type

String

发送的实体的MIME类型,参数值为“application/json”。

表3 请求Body参数

参数

是否必选

参数类型

说明

image

否,该参数与url二选一

String

图像数据,base64编码,要求base64编码后大小不超过10MB。

图片最小边不小于15px,最长边不超过4096px,支持JPEG、JPG、PNG、BMP、TIFF格式。

url

否,该参数与image二选一

String

图片的url路径,目前支持:

  • 公网http/https url
  • OBS提供的url,使用OBS数据需要进行授权。包括对服务授权、临时授权、匿名公开授权,详情参见配置OBS访问权限
说明:
  • 接口响应时间依赖于图片的下载时间,如果图片下载时间过长,会返回接口调用失败。
  • 请保证被检测图片所在的存储服务稳定可靠,推荐使用OBS服务存储图片数据。

country_code

String

输入值为护照颁发国的国家码,根据国家码选择对应的护照识别服务。

  • 若输入中未选此字段,服务会根据自己识别判断的护照类型匹配相应的护照识别服务。
  • 若选择值为“GENERAL”,则选择护照机器码识别。
  • 若选择值为“CHN”,则选择中国护照全字段识别。

响应参数

根据识别的结果,可能有不同的HTTP响应状态码(status code),状态码和响应参数说明如下。

状态码: 200

表4 响应Body参数

参数

参数类型

描述

result

PassportResult object

调用成功时表示调用结果。

Result中包含:13个主要字段,由英文表达;extra_info,由本地官方语言表达;以及主要字段的置信度信息,置信度越大,对应的字段的值越准确。

调用失败时无此字段。

表5 PassportResult

参数

参数类型

描述

passport_type

String

护照类型。

  • P:普通因私护照
  • W:外交护照
  • G:公务护照

country_code

String

护照签发国的国家码。

passport_number

String

护照号码。

nationality

String

护照持有人国籍。

surname

String

姓。

given_name

String

名字。

sex

String

性别。

date_of_birth

String

出生日期。

date_of_expiry

String

护照有效期。

date_of_issue

String

护照签发日期。

place_of_birth

String

出生地。

place_of_issue

String

签发地。

issuing_authority

String

签发机关。

因为各个领事馆签发机关简写未统一,所以服务统一对中国的英文简写处理为“P.R.China”。例如:有的签发机关是“P.R.C”,识别结果均显示“P.R.China”

confidence

Object

相关字段的置信度信息,取值范围0~1。

置信度越大,表示本次识别的对应字段的可靠性越高,在统计意义上,置信度越大,准确率越高。

置信度由算法给出,不直接等价于对应字段的准确率。

extra_info

Object

默认为空。对于中国护照,“extra_info”内会包含护照上由汉字描述的字段信息,如姓名、出生地等信息。

状态码: 400

表6 响应Body参数

参数

参数类型

说明

error_code

String

调用失败时的错误码,具体请参见错误码

当出现错误码“ModelArts.4204”时,请参考为什么调用API时提示“ModelArts.4204”?章节。

调用成功时无此字段。

error_msg

String

调用失败时的错误信息。

调用成功时无此字段。

请求示例

  • “endpoint”即调用API的请求地址,不同服务不同区域的“endpoint”不同,具体请参见终端节点

    例如,护照识别服务部署在“华北-北京四”区域的“endpoint”“ocr.cn-north-4.myhuaweicloud.com”,请求URL为“https://ocr.cn-north-4.myhuaweicloud.com/v2/{project_id}/ocr/passport”“project_id”为项目ID,获取方法请参见获取项目ID

  • 如何获取Token具体操作请参见构造请求
  • 请求样例(方式一:使用图片的base64编码)
    POST https://{endpoint}/v2/{project_id}/ocr/passport
    Request Header:
    Content-Type: application/json
    X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...
    Request Body:
    {
        "image":"/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAA...",
        "country_code": "GENERAL"
    }
  • 请求样例(方式二:使用图片URL)
    POST https://{endpoint}/v2/{project_id}/ocr/passport
    Request Header:
    Content-Type: application/json
    X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...
    Request Body:
    {
        "url":"https://BucketName.obs.xxxx.com/ObjectName",
        "country_code": "GENERAL"
    }
  • Python3语言请求代码示例(其他语言参照下列示例编写或使用OCR SDK)
    # encoding:utf-8
    
    import requests
    import base64
    
    url = "https://{endpoint}/v2/{project_id}/ocr/passport"
    token = "用户获取得到的实际token值"
    headers = {'Content-Type': 'application/json', 'X-Auth-Token': token}
    
    imagepath = r'./data/passport-demo.png'
    with open(imagepath, "rb") as bin_data:
        image_data = bin_data.read()
    image_base64 = base64.b64encode(image_data).decode("utf-8")  # 使用图片的base64编码
    payload = {"image": image_base64}  # url与image参数二选一
    response = requests.post(url, headers=headers, json=payload)
    print(response.text)

响应示例

状态码:200

中国护照

{
    "result": {
        "passport_type": "P", 
        "country_code": "CHN", 
        "passport_number": "ED999XXXX", 
        "nationality": "CHINESE", 
        "surname": "ZHANG", 
        "given_name": "SAN", 
        "sex": "F", 
        "date_of_birth": "1990-12-12", 
        "date_of_expiry": "2020-07-08", 
        "date_of_issue": "2010-07-09", 
        "place_of_birth": "HUNAN", 
        "place_of_issue": "GUANGDONG", 
        "issuing_authority": "MPS Exit & Entry Administration", 
        "extra_info": {
            "local_language": {
                "name": "张三", 
                "sex": "女", 
                "place_of_birth": "湖南", 
                "place_of_issue": "广东", 
                "issuing_authority": "xxx出入境管理局", 
                "nationality": "中国"
            }
        }, 
        "confidence": {
            "passport_type": 1.0, 
            "country_code": 1.0, 
            "passport_number": 0.9997, 
            "nationality": 1.0, 
            "surname": 0.9729, 
            "given_name": 0.9729, 
            "sex": 1.0, 
            "date_of_birth": 0.9998, 
            "date_of_expiry": 0.9995, 
            "date_of_issue": 0.9969, 
            "place_of_birth": 1.0, 
            "place_of_issue": 1.0, 
            "issuing_authority": 0.9985
        }
    }
}

外国护照

{
    "result": {
        "country_code": "ETF", 
        "surname": "HUZHAO", 
        "given_name": "ZHAOMIN DESALEGN ", 
        "passport_number": "EP435XXXX", 
        "date_of_birth": "1985-09-18", 
        "sex": "M", 
        "date_of_expiry": "2022-01-15", 
        "machine_code": "P<ETFHUZHAO<< ZHAOMIN <DESALEGN<<<<<<<<<<<<<<<", 
        "machine_code2": "EP435XXXX7ETF8509185M2201155<<<<<<<<<<<<<<08", 
        "extra_info": {},
        "confidence": {
            "country_code": 0.9727, 
            "surname": 0.9727, 
            "given_name": 0.9727, 
            "passport_number": 0.9558, 
            "date_of_birth": 0.9558, 
            "sex": 0.9558, 
            "date_of_expiry": 0.9558
        }
    }
}

状态码:400

失败响应示例

{
    "error_code": "AIS.0103", 
    "error_msg": "The image size does not meet the requirements." 
}

状态码

状态码

描述

200

成功响应。

400

失败响应。

状态码请参见状态码

错误码

错误码请参见错误码

分享:

    相关文档

    相关产品