RecognizeIdcard-阿里云帮助中心

Operation description

Scenarios

Alibaba Cloud Identity Card OCR is an official Alibaba Cloud OCR product that intelligently recognizes text from images of both sides of Mainland China identity cards, including temporary ID cards, and provides structured output.
Built on the advanced AI technology and massive datasets of Alibaba DAMO Academy, Alibaba Cloud OCR provides a stable, simple, real-time, and comprehensive service.
Sample image for this API:

Core capabilities

Category	Overview
Multi-type support	Automatically distinguishes front and back sides, and recognizes minority-language layouts, temporary IDs, rare characters, images with glare, and low-quality images.
Risk detection	Detects document risks such as incomplete images, photocopies, and screen captures, and provides quality scores.
Face detection	Locates the portrait on the ID and returns its coordinates.
Image enhancement	Enables automatic image enhancement by default, including auto-rotation, distortion correction, and blur reduction.

How to use this API

Step	Overview
1	Activate the Personal Document Recognition service. Before or after activation, test this feature for free in the Experience Center.
2	Purchase an ID recognition resource plan. This API includes a free quota for testing. If you do not purchase a plan, the system charges you based on actual usage through the pay-as-you-go model.
3	Refer to the code examples on the debugging page to integrate the API. After integration, call the API to get recognition results. If you use a RAM user, the primary Alibaba Cloud account must grant authorization. For instructions on how to create a RAM user, see Create a RAM user. The OCR service provides a system authorization policy named AliyunOCRFullAccess. For details on how to grant permissions, see Grant permissions to a RAM user on the Users page

Important notes

Type	Overview
Image formats	Supported formats: PNG, JPG, JPEG, BMP, GIF, TIFF, and WebP. PDF is not supported.
Image dimensions	Image width and height must be greater than 15 pixels and less than 8,192 pixels. The aspect ratio, which is the longer side divided by the shorter side, must be less than 50. For best recognition results, use images with both width and height over 500 pixels.
Image size	The binary file size must not exceed 10 MB. Larger images slow down the response time. Use images under 1.5 MB and pass them by URL when you call the API.
Country and language	This API supports only mainland China identity cards.
Other tips	Ensure the entire ID, including all edges, is visible in the image. The system automatically handles glare and distortion. However, these factors can reduce accuracy. For best results, use clear, glare-free, and undistorted images.
Related features	Mixed ID card recognition International ID 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:RecognizeIdcard

none

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
Url	string	No	Use either this parameter or the body parameter. You must specify one, but not both. The URL of the image. The URL must be less than 2,048 bytes. Base64 encoding is not supported.	https://img.alicdn.com/tfs/TB1q5IeXAvoK1RjSZFNXXcxMVXa-483-307.jpg
body	string	No	Use either this parameter or the Url parameter. You must specify one, but not both. The binary data of the image. The size cannot exceed 10 MB. If you call the API over HTTP, place the image binary data in the HTTP request body. If you use a software development kit (SDK), pass the image data in the `body` parameter of the SDK method.	图片二进制文件
OutputFigure	boolean	No	Specifies whether to enable pattern detection. The default value is false. true: enables pattern detection. false: disables pattern detection.	false
OutputQualityInfo	boolean	No	Specifies whether to enable ID quality checks. The default value is false. Quality checks include detection for screen captures and photocopies, a completeness score, an overall quality score, and a tampering index. Note: If you set this parameter, you must use the latest SDK version. If you do not set this parameter, you do not need to update the SDK.	false
Llm_rec	boolean	No

Response elements

Element	Type	Description	Example
	object	The response schema.
RequestId	string	The ID of the request.	86B83935-DD36-195B-B6E4-D07BE370C8B6
Data	string	The data returned.	{"algo_version": "48f3e265513a79d5f9bc26f0c010476bbd856b2d", "data": {"face": {"algo_version": "48f3e265513a79d5f9bc26f0c010476bbd856b2d", "angle": 0, "data": {"address": "四川省攀枝花市榕树街277号", "birthDate": "1986年1月9日", "ethnicity": "汉", "idNumber": "510124198809071234", "name": "王銘宇", "sex": "男"}, "ftype": 0, "height": 397, "orgHeight": 397, "orgWidth": 619, "prism_keyValueInfo": [{"key": "name", "keyProb": 100, "value": "王銘宇", "valuePos": [{"x": 139, "y": 75}, {"x": 194, "y": 75}, {"x": 194, "y": 94}, {"x": 139, "y": 94}], "valueProb": 100}, {"key": "sex", "keyProb": 100, "value": "男", "valuePos": [{"x": 139, "y": 122}, {"x": 159, "y": 122}, {"x": 159, "y": 144}, {"x": 139, "y": 144}], "valueProb": 100}, {"key": "ethnicity", "keyProb": 100, "value": "汉", "valuePos": [{"x": 260, "y": 122}, {"x": 282, "y": 122}, {"x": 282, "y": 142}, {"x": 260, "y": 142}], "valueProb": 100}, {"key": "birthDate", "keyProb": 100, "value": "1986年1月9日", "valuePos": [{"x": 141, "y": 170}, {"x": 303, "y": 168}, {"x": 304, "y": 183}, {"x": 142, "y": 185}], "valueProb": 100}, {"key": "address", "keyProb": 100, "value": "四川省攀枝花市榕树街277号", "valuePos": [{"x": 141, "y": 221}, {"x": 385, "y": 221}, {"x": 385, "y": 241}, {"x": 141, "y": 241}], "valueProb": 100}, {"key": "idNumber", "keyProb": 100, "value": "510124198809071234", "valuePos": [{"x": 226, "y": 338}, {"x": 543, "y": 336}, {"x": 543, "y": 355}, {"x": 227, "y": 356}], "valueProb": 100}], "sliceRect": {"x0": 10, "x1": 623, "x2": 629, "x3": 10, "y0": 17, "y1": 18, "y2": 398, "y3": 412}, "warning": {"completenessScore": 100, "isCopy": 0, "isReshoot": 0, "qualityScore": 89.296059, "tamperScore": 99.99968}, "width": 619}}, "height": 416, "orgHeight": 416, "orgWidth": 629, "width": 629}
Code	string	The error code. This parameter is returned only when an error occurs.	noPermission
Message	string	The error message. This parameter is returned only when an error occurs.	You are not authorized to perform this operation.

Response parameter descriptions

Field	Type	Description
data	object	The structured information. The front side data is in the face field, and the back side data is in the back field.
figure	list	The location of the face on the front of the ID. This field is returned only if OutputFigure is set to true.
sliceRect	object	The coordinates of the detected sub-image.
prism_keyValueInfo	list	The coordinates of the structured information.
ftype	int	Indicates whether the image is a photocopy. 1: Yes. 0: No.
warning	object	The ID quality check information. This field is returned only if OutputQualityInfo is set to true.
angle	int	The rotation angle of the image. 0 indicates upright, 90 indicates rotated 90 degrees clockwise, 180 indicates upside down, and 270 indicates rotated 90 degrees counter-clockwise.
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.

Front side recognition results (face field)

Field	Type	Description
name	string	The name.
sex	string	The gender.
ethnicity	string	The ethnicity.
birthDate	string	The date of birth.
address	string	The address.
idNumber	string	The ID number.

Back side recognition results (back field)

Field	Type	Description
issueAuthority	string	The issuing authority.
validPeriod	string	The validity period.

Structured coordinate information (prism_keyValueInfo field)

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

Front portrait location 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 portrait coordinate information: center coordinates (x, y), width, height, and clockwise rotation angle. 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, and bottom-left).

ID quality check results (warning field)

Field	Type	Description
isCopy	int	Indicates whether the image is a photocopy. 1: Yes. 0: No.
isReshoot	int	Indicates whether the image is a screen capture. 1: Yes. 0: No.
completenessScore	float	The completeness score.
qualityScore	float	The overall quality score.
tamperScore	float	The tampering index. A higher value indicates a greater likelihood of tampering. The recommended threshold is 60.

Examples

Success response

JSON format

{
  "RequestId": "86B83935-DD36-195B-B6E4-D07BE370C8B6",
  "Data": "{\"algo_version\": \"48f3e265513a79d5f9bc26f0c010476bbd856b2d\", \"data\": {\"face\": {\"algo_version\": \"48f3e265513a79d5f9bc26f0c010476bbd856b2d\", \"angle\": 0, \"data\": {\"address\": \"四川省攀枝花市榕树街277号\", \"birthDate\": \"1986年1月9日\", \"ethnicity\": \"汉\", \"idNumber\": \"510124198809071234\", \"name\": \"王銘宇\", \"sex\": \"男\"}, \"ftype\": 0, \"height\": 397, \"orgHeight\": 397, \"orgWidth\": 619, \"prism_keyValueInfo\": [{\"key\": \"name\", \"keyProb\": 100, \"value\": \"王銘宇\", \"valuePos\": [{\"x\": 139, \"y\": 75}, {\"x\": 194, \"y\": 75}, {\"x\": 194, \"y\": 94}, {\"x\": 139, \"y\": 94}], \"valueProb\": 100}, {\"key\": \"sex\", \"keyProb\": 100, \"value\": \"男\", \"valuePos\": [{\"x\": 139, \"y\": 122}, {\"x\": 159, \"y\": 122}, {\"x\": 159, \"y\": 144}, {\"x\": 139, \"y\": 144}], \"valueProb\": 100}, {\"key\": \"ethnicity\", \"keyProb\": 100, \"value\": \"汉\", \"valuePos\": [{\"x\": 260, \"y\": 122}, {\"x\": 282, \"y\": 122}, {\"x\": 282, \"y\": 142}, {\"x\": 260, \"y\": 142}], \"valueProb\": 100}, {\"key\": \"birthDate\", \"keyProb\": 100, \"value\": \"1986年1月9日\", \"valuePos\": [{\"x\": 141, \"y\": 170}, {\"x\": 303, \"y\": 168}, {\"x\": 304, \"y\": 183}, {\"x\": 142, \"y\": 185}], \"valueProb\": 100}, {\"key\": \"address\", \"keyProb\": 100, \"value\": \"四川省攀枝花市榕树街277号\", \"valuePos\": [{\"x\": 141, \"y\": 221}, {\"x\": 385, \"y\": 221}, {\"x\": 385, \"y\": 241}, {\"x\": 141, \"y\": 241}], \"valueProb\": 100}, {\"key\": \"idNumber\", \"keyProb\": 100, \"value\": \"510124198809071234\", \"valuePos\": [{\"x\": 226, \"y\": 338}, {\"x\": 543, \"y\": 336}, {\"x\": 543, \"y\": 355}, {\"x\": 227, \"y\": 356}], \"valueProb\": 100}], \"sliceRect\": {\"x0\": 10, \"x1\": 623, \"x2\": 629, \"x3\": 10, \"y0\": 17, \"y1\": 18, \"y2\": 398, \"y3\": 412}, \"warning\": {\"completenessScore\": 100, \"isCopy\": 0, \"isReshoot\": 0, \"qualityScore\": 89.296059, \"tamperScore\": 99.99968}, \"width\": 619}}, \"height\": 416, \"orgHeight\": 416, \"orgWidth\": 629, \"width\": 629}",
  "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.