通用证件识别
功能介绍
识别身份证件图像，并将识别的结构化结果返回给用户。支持多个国家/地区的身份证、驾驶证和护照，具体国家/地区和证件列表详见表1。该接口的使用限制请参见约束与限制，详细使用指导请参见OCR服务使用简介章节。
国家/地区 |
英文名称 |
国家/地区代码 country_region |
支持证件类型 id_type |
|---|---|---|---|
越南 |
Vietnam |
VNM |
PP、DL、ID |
印度 |
India |
IND |
PP |
菲律宾 |
Philippines |
PHL |
PP、DL、ID（仅支持UMID） |
阿尔巴尼亚 |
Albania |
ALB |
PP、DL、ID |
巴西 |
Brazil |
BRA |
PP |
印度尼西亚 |
Indonesia |
IDN |
PP |
马来西亚 |
Malaysia |
MYS |
PP |
尼日利亚 |
Nigeria |
NGA |
PP |
巴基斯坦 |
Pakistan |
PAK |
PP |
俄罗斯 |
Russia |
RUS |
PP（仅支持国际标准版本） |
中国台湾 |
Taiwan (China) |
TWN |
PP |
乌克兰 |
Ukraine |
UKR |
PP |
泰国 |
Thailand |
THA |
ID、PP |
智利 |
Chile |
CHL |
ID、PP |
中国香港 |
Hong Kong (China) |
HKG |
ID |
|
|||
约束与限制
- 只支持JPEG、JPG、PNG、BMP、TIFF格式图片。
- 图片最小边不小于100px，最长边不超过8192px。
调试
您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。
API Explorer可调用区域为中国-香港。
前提条件
在使用通用证件识别之前，需要您完成服务申请和认证鉴权，具体操作流程请参见开通服务和认证鉴权章节。
用户首次使用需要先申请开通。服务只需要开通一次即可，后面使用时无需再次申请。如未开通服务，调用服务时会提示ModelArts.4204报错，请在调用服务前先进入控制台开通服务，并注意开通服务区域与调用服务的区域保持一致。
URI
POST /v2/{project_id}/ocr/id-document
请求参数
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
X-Auth-Token |
是 |
String |
用户Token。 用于获取操作API的权限。获取Token接口响应消息头中X-Subject-Token的值即为Token。 |
Content-Type |
是 |
String |
发送的实体的MIME类型，参数值为“application/json”。 |
Enterprise-Project-Id |
否 |
String |
企业项目ID。OCR支持通过企业项目管理（EPS）对不同用户组和用户的资源使用，进行分账。 获取方法：进入“企业项目管理”页面，单击企业项目名称，在企业项目详情页获取Enterprise-Project-Id（企业项目ID）。
企业项目创建步骤请参见用户指南。
说明：
创建企业项目后，在传参时，有以下三类场景。
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
image |
否 |
String |
该参数与url二选一。图像数据，base64编码，要求base64编码后大小不超过10MB。图片最小边不小于100px，最长边不超过8192px，支持JPEG、JPG、PNG、BMP、TIFF。 |
url |
否 |
String |
该参数与image二选一。图片的url路径，目前支持： Image URL. Currently, the following URLs are supported:
说明：
|
country_region |
否 |
Array of strings |
证件签发国家或地区代码，命名遵循ISO-3166 3位代码。可选值。支持填写1个或多个国家/地区。指定参数后，服务只识别指定国家/地区的卡证，如留空，则识别所有支持的卡证。建议国家/地区固定或有限范围的情况下填写。支持国家/地区列表见表1。
说明：
识别越南语时，该参数为必填。 |
id_type |
否 |
Array of strings |
证件类型。可选值。支持填写1种或多种证件。指定参数后，服务只识别指定类型的卡证，如留空，默认识别所有类型卡证，建议已知证件类型的情况下填写。支持证件类型如下：
|
return_portrait_image |
否 |
Boolean |
控制是否返回portrait_image（证件中的人像图片），true代表需要返回，false代表不需要。 |
响应参数
状态码： 200
参数 |
参数类型 |
描述 |
|---|---|---|
result |
IdDocumentItem object |
识别结果。 调用失败时此字段为空。 |
参数 |
参数类型 |
描述 |
|---|---|---|
country_region |
String |
证件签发国家或地区代码，命名遵循ISO-3166 3位代码。当前支持国家/地区列表见表1。 |
id_type |
String |
证件类型，可选值如下：
|
side |
String |
证件正面或反面,可选值：
|
first_name |
String |
名。 |
last_name |
String |
姓氏。 |
sex |
String |
性别，可选值： M:男性 F:女性 X:中性。 |
nationality |
String |
持有人国籍。 |
birth_date |
String |
生日，格式为yyyy-mm-dd。 |
issue_date |
String |
签发日期，yyyy-mm-dd。 |
expiry_date |
String |
有效日期，yyyy-mm-dd。 |
document_number |
String |
证件号码。 |
address |
String |
持有人通讯地址。 |
issuing_authority |
String |
签发机关。 |
portrait_image |
String |
可选返回，证件头像图像base64编码。 |
confidence |
Object |
字段置信度，为0~1之间的小数，值越大，表明识别结果越可靠。 |
状态码： 400
参数 |
参数类型 |
描述 |
|---|---|---|
error_code |
String |
调用失败时的错误码，具体请参见错误码。 调用成功时无此字段。 |
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/id-document”，“project_id”为项目ID，获取方法请参见获取项目ID
- 如何获取Token请参见构造请求。
- 请求示例（方式一：使用图片的Base64编码）
POST https://{endpoint}/v2/{project_id}/ocr/id-document { "image" : "/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAA...", "country_region" : "ALB", "id_type" : "PP" } - 请求示例（方式二：使用图片URL）
POST https://{endpoint}/v2/{project_id}/ocr/id-document { "url" : "https://BucketName.obs.xxxx.com/ObjectName", "country_region" : "ALB", "id_type" : "PP" }
响应示例
状态码： 200
成功响应样例
{
"result" : {
"country_region" : "ALB",
"id_type" : "PP",
"side" : "front"
}
}
状态码： 400
失败响应示例
{
"error_code" : "AIS.0103",
"error_msg" : "The image size does not meet the requirements."
}
状态码
状态码 |
描述 |
|---|---|
200 |
成功响应样例 |
400 |
失败响应样例 |
状态码请参见状态码。
错误码
错误码请参见错误码。
