1. API Description
Domain name for API request: ocr.tencentcloudapi.com.
This API is used to recognize all fields on the front and back sides of a second-generation resident identity card for the Chinese mainland: name, gender, ethnicity, date of birth, domicile, identification number, issuing authority, and validity period, with a recognition accuracy of over 99%.
In addition, this API supports multiple value-added capabilities to meet the needs of different scenarios. It can crop ID card photos and profile photos, and provide warnings for nine cases, as detailed below.
| Capability | Description |
|---|---|
| Cropping | Crops the ID card photo (by removing extra edges outside the ID card and automatically correcting the shooting angle). |
| Crops the profile photo (by automatically cutting out the face area in the ID card). | |
| Warning | Warns about invalid ID card validity periods. |
| Warns about incomplete ID card borders. | |
| Warns about photocopied images. | |
| Warns about spoofed images. | |
| Warns about border and frame occlusions. | |
| Warns about temporary ID cards. | |
| Warns about photoshopped images. | |
| Warns about blurry ID card images (blurriness can be determined based on the image quality score). |
A maximum of 20 requests can be initiated per second for this API.
We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.
2. Input Parameters
The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.
| Parameter Name | Required | Type | Description |
|---|---|---|---|
| Action | Yes | String | Common Params. The value used for this API: IDCardOCR. |
| Version | Yes | String | Common Params. The value used for this API: 2018-11-19. |
| Region | No | String | Common Params. This parameter is not required for this API. |
| ImageBase64 | No | String | The Base64-encoded value of an image. The image cannot exceed 7 MB after being Base64-encoded. A resolution above 500 x 800 is recommended. PNG, JPG, JPEG, and BMP formats are supported. It is recommended that the card part occupy more than 2/3 area of the image. Either ImageUrl or ImageBase64 of the image must be provided. If both are provided, ImageUrl is used. |
| ImageUrl | No | String | The URL of the image. The image cannot exceed 7 MB after being Base64-encoded. A resolution above 500 x 800 is recommended. PNG, JPG, JPEG, and BMP formats are supported. It is recommended that the card part occupy more than 2/3 area of the image. We recommend that you store the image in Tencent Cloud for higher download speed and stability. |
| CardSide | No | String | FRONT: The side with the profile photo.BACK: The side with the national emblem.If this parameter is not specified, the system will automatically determine the ID card side. |
| Config | No | String | The following parameters are all of bool type and default to false:CropIdCard: Crops the ID card photo (by removing extra edges outside the ID card and automatically correcting the shooting angle).CropPortrait: Crops the profile photo (by automatically cutting out the face area in the ID card).CopyWarn: Warns about photocopied images.BorderCheckWarn: Warns about border and frame occlusions.ReshootWarn: Warns about spoofed images.DetectPsWarn: Warns about photoshopped images.TempIdWarn: Warns about temporary ID cards.InvalidDateWarn: Warns about invalid ID card validity periods.Quality: Gets the image quality score (by evaluating the blurriness of the image).MultiCardDetect: Enables multi-card detection.ReflectWarn: Enables glare detection.Parameter setting method via SDK: Config = Json.stringify({"CropIdCard":true,"CropPortrait":true}) Parameter setting method via API 3.0 Explorer: Config = {"CropIdCard":true,"CropPortrait":true} |
3. Output Parameters
| Parameter Name | Type | Description |
|---|---|---|
| Name | String | Name (profile photo side) |
| Sex | String | Gender (profile photo side) |
| Nation | String | Ethnicity (profile photo side) |
| Birth | String | Date of birth (profile photo side) |
| Address | String | Address (profile photo side) |
| IdNum | String | ID number (profile photo side) |
| Authority | String | Issuing authority (national emblem side) |
| ValidDate | String | Validity period (national emblem side) |
| AdvancedInfo | String | Extended information, which will be returned only when requested. For the input parameters, please see example 3 and example 4.IdCard: Base64-encoded content of the cropped ID card photo, which will be returned if Config.CropIdCard is set to true.Portrait: Base64-encoded content of the ID photo on the card, which will be returned if Config.CropPortrait is set to true.Quality: Image quality score, which will be returned if Config.Quality is set to true. Value range: 0–100. The lower the score, the blurrier the image. The recommended threshold is ≥ 50.BorderCodeValue: Warning threshold score for incomplete ID card borders, which will be returned if Config.BorderCheckWarn is set to true. Value range: 0–100. The lower the score, the lower the probability of border occlusion. The recommended threshold value is ≤ 50.WarnInfos: Warning information. Warning codes and descriptions are as follows:-9100: The ID card validity period is invalid. -9101: The ID card borders are incomplete. -9102: The ID card image is photocopied. -9103: The ID card image is spoofed. -9104: The ID card is a temporary one. -9105: The ID card frame is occluded. -9106: The ID card image is photoshopped. -9107: The ID card image has glares. |
| RequestId | String | The unique request ID, which is returned for each request. RequestId is required for locating a problem. |
4. Example
Example1 Recognizing the front side of a Chinese mainland identity card Debugging tool
This example shows you how to recognize the front side of a Chinese mainland identity card.
Input Example
POST / HTTP/1.1
Host: ocr.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: IDCardOCR
<Common request parameters>
{
"ImageUrl": "https://xx/a.jpg",
"CardSide": "FRONT"
}
Output Example
{
"Response": {
"Name": "",
"Sex": "",
"Nation": "",
"Birth": "1987/1/1",
"Address": "",
"IdNum": "440524198701010014",
"Authority": "",
"ValidDate": "",
"AdvancedInfo": "{}",
"RequestId": "ab2c132e-9e1c-43d3-b0ef-9b4d80f00330"
}
}
Example2 Recognizing the back side of a Chinese mainland identity card Debugging tool
This example shows you how to recognize the back side of a Chinese mainland identity card.
Input Example
POST / HTTP/1.1
Host: ocr.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: IDCardOCR
<Common request parameters>
{
"ImageUrl": "https://xx/a.jpg",
"CardSide": "BACK"
}
Output Example
{
"Response": {
"Name": "",
"Sex": "",
"Nation": "",
"Birth": "",
"Address": "",
"IdNum": "",
"Authority": "",
"ValidDate": "2010.07.21-2020.07.21",
"AdvancedInfo": "{}",
"RequestId": "0d394478-6d4d-48fc-8b19-552415bf46de"
}
}
Example3 Cropping the ID card photo and profile photo Debugging tool
This example shows you how to crop the ID card photo and profile photo.
Input Example
POST / HTTP/1.1
Host: ocr.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: IDCardOCR
<Common request parameters>
{
"ImageUrl": "https://xx/a.jpg",
"Config": "{\"CropIdCard\":true,\"CropPortrait\":true}",
"CardSide": "FRONT"
}
Output Example
{
"Response": {
"Name": "",
"Sex": "",
"Nation": "",
"Birth": "1987/1/1",
"Address": "",
"IdNum": "440524198701010014",
"Authority": "",
"ValidDate": "",
"AdvancedInfo": "{\"IdCard\":\"/9j/4AAA.........\",\"Portrait\":\"/9j/4AAQSkZJRBA=...........\"}",
"RequestId": "97c323da-5fd3-4fe6-b0b3-1cf10b04422c"
}
}
Example4 Recognizing a temporary Chinese mainland identity card Debugging tool
This example shows you how to recognize a temporary ID card.
Input Example
POST / HTTP/1.1
Host: ocr.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: IDCardOCR
<Common request parameters>
{
"ImageUrl": "https://xx/a.jpg",
"Config": "{\"TempIdWarn\":true}",
"CardSide": "FRONT"
}
Output Example
{
"Response": {
"Name": "",
"Sex": "",
"Nation": "",
"Birth": "",
"Address": "",
"IdNum": "",
"Authority": "",
"ValidDate": "",
"AdvancedInfo": "{\"WarnInfos\":[-9104]}",
"RequestId": "sd33222eqd1dqq948487"
}
}
5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.
- Tencent Cloud SDK 3.0 for Python
- Tencent Cloud SDK 3.0 for Java
- Tencent Cloud SDK 3.0 for PHP
- Tencent Cloud SDK 3.0 for Go
- Tencent Cloud SDK 3.0 for NodeJS
- Tencent Cloud SDK 3.0 for .NET
- Tencent Cloud SDK 3.0 for C++
Command Line Interface
6. Error Code
The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.
| Error Code | Description |
|---|---|
| FailedOperation.CardSideError | The CardSide type of the ID card is incorrect. |
| FailedOperation.DownLoadError | File download failed. |
| FailedOperation.EmptyImageError | The image is empty. |
| FailedOperation.IdCardInfoIllegal | The ID card information (ID number, name, etc.) is invalid. |
| FailedOperation.IdCardTooSmall | The resolution of the image is too low or the proportion of the ID card in the image is too small. |
| FailedOperation.ImageBlur | The image is blurry. |
| FailedOperation.ImageDecodeFailed | Image decoding failed. |
| FailedOperation.ImageNoIdCard | No ID card is detected in the image. |
| FailedOperation.ImageSizeTooLarge | The image is too large. Please see the description of image size limit in the output parameters. |
| FailedOperation.MultiCardError | There are multiple cards in the photo. |
| FailedOperation.OcrFailed | OCR failed. |
| FailedOperation.UnKnowError | Unknown error. |
| FailedOperation.UnOpenError | The service is not activated. |
| InvalidParameter.ConfigFormatError | Config is not in valid JSON format. |
| InvalidParameterValue.InvalidParameterValueLimit | Incorrect parameter value. |
| LimitExceeded.TooLargeFileError | The file is too large. |
| ResourcesSoldOut.ChargeStatusException | Exceptional billing status. |
Yes
No
Was this page helpful?