文档首页> 文字识别 OCR> API参考> API> 护照识别

更新时间：2023-11-10 GMT+08:00

查看PDF

护照识别

功能介绍

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

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

图1 护照示例图

约束与限制

支持中国大陆护照的全字段识别。
支持含有完整机读码的中国港澳台地区及外国护照识别。
只支持识别PNG、JPG、JPEG、BMP、TIFF格式图片。
图像各边的像素大小在15px到8192px之间。
图像中护照首页区域有效占比超过25%，保证护照首页内容及其边缘包含在图像内。
支持图像中护照任意角度的水平旋转。
支持少量扭曲，扭曲后图像中的护照长宽比与实际护照相差不超过10%。
能处理反光、暗光等干扰的图片但影响识别精度。

调试

您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

前提条件

在使用之前，需要您完成服务申请和认证鉴权，具体操作流程请参见开通服务和认证鉴权章节。

用户首次使用需要先开通服务。服务只需要开通一次即可，后面使用时无需再次申请。如未开通服务，调用服务时会提示ModelArts.4204报错，请在调用服务前先进入控制台开通服务，并注意开通服务区域与调用服务的区域保持一致。

URI

POST /v2/{project_id}/ocr/passport

表1 路径参数
参数	是否必选	说明
endpoint	是	终端节点，即调用API的请求地址。不同服务不同区域的endpoint不同，您可以从终端节点中获取。
project_id	是	项目ID，您可以从获取项目ID中获取。

请求参数

表2 请求Header参数
参数	是否必选	参数类型	描述
X-Auth-Token	是	String	用户Token。用于获取操作API的权限。获取Token接口响应消息头中X-Subject-Token的值即为Token。
Content-Type	是	String	发送的实体的MIME类型，参数值为“application/json”。

表3 请求Body参数
参数	是否必选	参数类型	说明
image	否	String	该参数与url二选一。图片的Base64编码，要求Base64编码后大小不超过10MB。图片最短边不小于15px，最长边不超过8192px，支持JPEG、JPG、PNG、BMP、TIFF格式。图片Base64编码示例如/9j/4AAQSkZJRgABAg...，带有多余前缀会产生The image format is not supported报错。
url	否	String	该参数与image二选一。图片的url路径，目前支持：公网http/https url OBS提供的url，使用OBS数据需要进行授权。包括对服务授权、临时授权、匿名公开授权，详情参见配置OBS访问权限。说明：接口响应时间依赖于图片的下载时间，如果图片下载时间过长，会返回接口调用失败。请保证被检测图片所在的存储服务稳定可靠，推荐使用OBS服务存储图片数据。 url中不能存在中文字符，若存在，中文需要进行utf8编码。
country_code	否	String	输入值为护照颁发国的国家码，根据国家码选择对应的护照识别服务。若输入中未选此字段，服务会根据自己识别判断的护照类型匹配相应的护照识别服务。若选择值为“GENERAL”，则选择护照机器码识别。若选择值为“CHN”，则选择中国护照全字段识别。

响应参数

根据识别的结果，可能有不同的HTTP响应状态码（status code）。例如，200表示API调用成功，400表示调用失败，详细的状态码和响应参数说明如下。

状态码： 200

表4 响应Body参数
参数	参数类型	描述
result	PassportResult object	识别结果。调用失败时不返回此字段。该结果中包含：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	出生日期。返回值例如，1990-12-12。
date_of_expiry	String	护照有效期。返回值例如，2020-07-08。
date_of_issue	String	护照签发日期。返回值例如，2010-07-09。说明：该字段仅限中国大陆护照。
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.ap-southeast-1.myhuaweicloud.com或ocr.ap-southeast-1.myhuaweicloud.cn”，请求URL为“https://ocr.ap-southeast-1.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语言读取本地护照图片进行文字识别

# 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}
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": 0.9987, 
            "country_code": 0.9897, 
            "passport_number": 0.9997, 
            "nationality": 0.9977, 
            "surname": 0.9729, 
            "given_name": 0.9729, 
            "sex": 0.9897, 
            "date_of_birth": 0.9998, 
            "date_of_expiry": 0.9995, 
            "date_of_issue": 0.9969, 
            "place_of_birth": 0.9937, 
            "place_of_issue": 0.9993, 
            "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	失败响应样例

状态码请参见状态码。

错误码

错误码请参见错误码。

父主题： API

上一篇：网络图片识别

下一篇：泰文身份证识别

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消