RecognizeHKIdcard-阿里云帮助中心

Operation description

How to use this API

Step	Overview
1	Activate the Personal ID OCR service.
2	Purchase a Hong Kong (China) Identity Card OCR resource plan. This API provides a free quota for testing. If you do not purchase a resource plan, the system automatically charges you on a pay-as-you-go basis for each call.
3	Use the code samples on the testing page to integrate the API. After integration, call the API to get the recognition results. If a RAM user calls the API, the parent Alibaba Cloud account must grant permissions to the RAM user. For more information about how to create a RAM user, see Create a RAM user. The OCR service provides a system authorization policy named AliyunOCRFullAccess. For more information about how to grant permissions, see Grant permissions to a RAM user

Important notes

Type	Overview
Image format	This API supports PNG, JPG, JPEG, BMP, GIF, TIFF, and WebP formats. PDF format is not supported.
Image dimensions	The image height and width must be greater than 15 pixels and less than 8,192 pixels. The aspect ratio must be less than 50. For best results, use an image with a height and width greater than 500 pixels.
Image size	The binary file of the image cannot exceed 10 MB. Large images can slow down the API response. Use images smaller than 1.5 MB and call the API by passing the image URL.
Country and language	This API only supports Hong Kong (China) identity cards.
Other notes	Ensure that the entire identity card, including its edges, is visible in the image. This feature automatically handles interference such as reflections and distortions, but this can affect accuracy. For best results, use clear images without reflections or distortions.
Related features	International ID card recognition.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ocr:RecognizeHKIdcard

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
Url	string	No	Specify either this parameter or the body parameter. You cannot specify both or leave both empty. The image URL. The URL cannot exceed 2,048 bytes in length. Base64-encoded images are not supported.	https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241223/bomzne/%E4%B8%AD%E5%9B%BD%E9%A6%99%E6%B8%AF%E8%BA%AB%E4%BB%BD%E8%AF%81%E8%AF%86%E5%88%AB.png
body	string	No	Specify either this parameter or the Url parameter. You cannot specify both or leave both empty. The binary file of the image. The maximum size is 10 MB. If you call the API using HTTP, upload the image's binary file in the HTTP body. If you call the API using an SDK, place the image in the SDK's body.	图片二进制文件

Response elements

Element	Type	Description	Example
	object	Schema of Response
RequestId	string	The unique ID of the request.	43A29C77-405E-4CC0-BC55-EE694AD00655
Data	string	The returned data.	{ "algo_version": "5e7c3de7fb3969700828bd933ee071782bc22088", "data": { "birthDate": "01-01-19XX", "firstIssuedDate": "(01-79)", "idNumber": "CXXXXXX(E)", "issuedCode": "*AZ", "issuedDate": "XX-09-03", "nameCn": "李XX", "nameCode": "2621 2535 5174", "nameEn": "LEE, Chi Nan", "sex": "女F" }, "ftype": 0, "height": 158, "orgHeight": 158, "orgWidth": 249, "prism_keyValueInfo": [ { "key": "nameCn", "keyProb": 100, "value": "李XX", "valuePos": [ { "x": 11, "y": 27 }, { "x": 53, "y": 27 }, { "x": 53, "y": 40 }, { "x": 11, "y": 40 } ], "valueProb": 100 }, { "key": "nameEn", "keyProb": 97, "value": "LEE, XX", "valuePos": [ { "x": 10, "y": 40 }, { "x": 81, "y": 40 }, { "x": 81, "y": 51 }, { "x": 10, "y": 51 } ], "valueProb": 97 }, { "key": "nameCode", "keyProb": 100, "value": "XXX", "valuePos": [ { "x": 73, "y": 54 }, { "x": 155, "y": 54 }, { "x": 155, "y": 64 }, { "x": 73, "y": 64 } ], "valueProb": 100 }, { "key": "birthDate", "keyProb": 100, "value": "01-01-19XX", "valuePos": [ { "x": 73, "y": 86 }, { "x": 133, "y": 85 }, { "x": 133, "y": 93 }, { "x": 74, "y": 95 } ], "valueProb": 100 }, { "key": "sex", "keyProb": 98, "value": "女F", "valuePos": [ { "x": 153, "y": 84 }, { "x": 171, "y": 84 }, { "x": 171, "y": 94 }, { "x": 153, "y": 94 } ], "valueProb": 98 }, { "key": "issuedCode", "keyProb": 99, "value": "*AZ", "valuePos": [ { "x": 75, "y": 97 }, { "x": 104, "y": 97 }, { "x": 104, "y": 106 }, { "x": 75, "y": 106 } ], "valueProb": 99 }, { "key": "firstIssuedDate", "keyProb": 100, "value": "(01-79)", "valuePos": [ { "x": 74, "y": 119 }, { "x": 115, "y": 118 }, { "x": 115, "y": 126 }, { "x": 75, "y": 128 } ], "valueProb": 100 }, { "key": "issuedDate", "keyProb": 100, "value": "15-09-03", "valuePos": [ { "x": 74, "y": 135 }, { "x": 133, "y": 133 }, { "x": 133, "y": 143 }, { "x": 75, "y": 144 } ], "valueProb": 100 }, { "key": "idNumber", "keyProb": 100, "value": "XXXXXX(E)", "valuePos": [ { "x": 160, "y": 134 }, { "x": 232, "y": 133 }, { "x": 232, "y": 142 }, { "x": 161, "y": 144 } ], "valueProb": 100 } ], "sliceRect": { "x0": 0, "x1": 248, "x2": 248, "x3": 0, "y0": 0, "y1": 0, "y2": 157, "y3": 158 }, "width": 249 }
Code	string	The error code. This field is not returned if the recognition is successful.	noPermission
Message	string	The error message. This field is not returned if the recognition is successful.	You are not authorized to perform this operation.

Response parameters

Field	Type	Description
data	object	The structured information.
figure	list	The position of the face on the portrait side of the ID card.
sliceRect	list	The coordinates of the structured information.
prism_keyValueInfo	list	The coordinates of the structured information.
ftype	int	Indicates whether the image is a photocopy. 1: Yes. 0: No.
height	int	The height of the image after algorithmic correction.
width	int	The width of the image after algorithmic correction.
orgHeight	int	The height of the original image.
orgWidth	int	The width of the original image.

Structured information (data field)

Field	Type	Description
birthDate	string	The date of birth.
firstIssuedDate	string	The date of first issue.
idNumber	string	The identity card number.
issuedCode	string	The issuance symbol.
issuedDate	string	The date of issue.
nameCn	string	The name in Chinese.
nameCode	string	The Chinese commercial code for the name.
nameEn	string	The name in English.
sex	string	The sex.

Structured coordinate information (prism_keyValueInfo field)

Field	Type	Description
key	string	The name of the detected field.
keyProb	int	The confidence level of the field name.
value	string	The value corresponding to the detected field name.
valueProb	int	The confidence level of the value corresponding to the field name.
valuePos	list	The coordinates of the four corners of the field in the original image (top-left, top-right, bottom-right, bottom-left).

Portrait position information (figure field)

Field	Type	Description
type	string	The pattern type.
x	int	The x-coordinate of the top-left corner of the portrait.
y	int	The y-coordinate of the top-left corner of the portrait.
w	int	The width of the portrait.
h	int	The height of the portrait.
box	object	The coordinate information of the portrait: the x and y coordinates of the center, the width and height, and the clockwise rotation angle of the pattern. The definition is the same as RotatedRect in OpenCV. For more information, see the OpenCV documentation.
points	list	The coordinates of the four corners of the portrait (top-left, top-right, bottom-right, bottom-left).

Examples

Success response

JSON format

{
  "RequestId": "43A29C77-405E-4CC0-BC55-EE694AD00655",
  "Data": "{\n    \"algo_version\": \"5e7c3de7fb3969700828bd933ee071782bc22088\",\n    \"data\": {\n        \"birthDate\": \"01-01-19XX\",\n        \"firstIssuedDate\": \"(01-79)\",\n        \"idNumber\": \"CXXXXXX(E)\",\n        \"issuedCode\": \"***AZ\",\n        \"issuedDate\": \"XX-09-03\",\n        \"nameCn\": \"李XX\",\n        \"nameCode\": \"2621 2535 5174\",\n        \"nameEn\": \"LEE, Chi Nan\",\n        \"sex\": \"女F\"\n    },\n    \"ftype\": 0,\n    \"height\": 158,\n    \"orgHeight\": 158,\n    \"orgWidth\": 249,\n    \"prism_keyValueInfo\": [\n        {\n            \"key\": \"nameCn\",\n            \"keyProb\": 100,\n            \"value\": \"李XX\",\n            \"valuePos\": [\n                {\n                    \"x\": 11,\n                    \"y\": 27\n                },\n                {\n                    \"x\": 53,\n                    \"y\": 27\n                },\n                {\n                    \"x\": 53,\n                    \"y\": 40\n                },\n                {\n                    \"x\": 11,\n                    \"y\": 40\n                }\n            ],\n            \"valueProb\": 100\n        },\n        {\n            \"key\": \"nameEn\",\n            \"keyProb\": 97,\n            \"value\": \"LEE, XX\",\n            \"valuePos\": [\n                {\n                    \"x\": 10,\n                    \"y\": 40\n                },\n                {\n                    \"x\": 81,\n                    \"y\": 40\n                },\n                {\n                    \"x\": 81,\n                    \"y\": 51\n                },\n                {\n                    \"x\": 10,\n                    \"y\": 51\n                }\n            ],\n            \"valueProb\": 97\n        },\n        {\n            \"key\": \"nameCode\",\n            \"keyProb\": 100,\n            \"value\": \"XXX\",\n            \"valuePos\": [\n                {\n                    \"x\": 73,\n                    \"y\": 54\n                },\n                {\n                    \"x\": 155,\n                    \"y\": 54\n                },\n                {\n                    \"x\": 155,\n                    \"y\": 64\n                },\n                {\n                    \"x\": 73,\n                    \"y\": 64\n                }\n            ],\n            \"valueProb\": 100\n        },\n        {\n            \"key\": \"birthDate\",\n            \"keyProb\": 100,\n            \"value\": \"01-01-19XX\",\n            \"valuePos\": [\n                {\n                    \"x\": 73,\n                    \"y\": 86\n                },\n                {\n                    \"x\": 133,\n                    \"y\": 85\n                },\n                {\n                    \"x\": 133,\n                    \"y\": 93\n                },\n                {\n                    \"x\": 74,\n                    \"y\": 95\n                }\n            ],\n            \"valueProb\": 100\n        },\n        {\n            \"key\": \"sex\",\n            \"keyProb\": 98,\n            \"value\": \"女F\",\n            \"valuePos\": [\n                {\n                    \"x\": 153,\n                    \"y\": 84\n                },\n                {\n                    \"x\": 171,\n                    \"y\": 84\n                },\n                {\n                    \"x\": 171,\n                    \"y\": 94\n                },\n                {\n                    \"x\": 153,\n                    \"y\": 94\n                }\n            ],\n            \"valueProb\": 98\n        },\n        {\n            \"key\": \"issuedCode\",\n            \"keyProb\": 99,\n            \"value\": \"***AZ\",\n            \"valuePos\": [\n                {\n                    \"x\": 75,\n                    \"y\": 97\n                },\n                {\n                    \"x\": 104,\n                    \"y\": 97\n                },\n                {\n                    \"x\": 104,\n                    \"y\": 106\n                },\n                {\n                    \"x\": 75,\n                    \"y\": 106\n                }\n            ],\n            \"valueProb\": 99\n        },\n        {\n            \"key\": \"firstIssuedDate\",\n            \"keyProb\": 100,\n            \"value\": \"(01-79)\",\n            \"valuePos\": [\n                {\n                    \"x\": 74,\n                    \"y\": 119\n                },\n                {\n                    \"x\": 115,\n                    \"y\": 118\n                },\n                {\n                    \"x\": 115,\n                    \"y\": 126\n                },\n                {\n                    \"x\": 75,\n                    \"y\": 128\n                }\n            ],\n            \"valueProb\": 100\n        },\n        {\n            \"key\": \"issuedDate\",\n            \"keyProb\": 100,\n            \"value\": \"15-09-03\",\n            \"valuePos\": [\n                {\n                    \"x\": 74,\n                    \"y\": 135\n                },\n                {\n                    \"x\": 133,\n                    \"y\": 133\n                },\n                {\n                    \"x\": 133,\n                    \"y\": 143\n                },\n                {\n                    \"x\": 75,\n                    \"y\": 144\n                }\n            ],\n            \"valueProb\": 100\n        },\n        {\n            \"key\": \"idNumber\",\n            \"keyProb\": 100,\n            \"value\": \"XXXXXX(E)\",\n            \"valuePos\": [\n                {\n                    \"x\": 160,\n                    \"y\": 134\n                },\n                {\n                    \"x\": 232,\n                    \"y\": 133\n                },\n                {\n                    \"x\": 232,\n                    \"y\": 142\n                },\n                {\n                    \"x\": 161,\n                    \"y\": 144\n                }\n            ],\n            \"valueProb\": 100\n        }\n    ],\n    \"sliceRect\": {\n        \"x0\": 0,\n        \"x1\": 248,\n        \"x2\": 248,\n        \"x3\": 0,\n        \"y0\": 0,\n        \"y1\": 0,\n        \"y2\": 157,\n        \"y3\": 158\n    },\n    \"width\": 249\n}",
  "Code": "noPermission",
  "Message": "You are not authorized to perform this operation."
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.