tencent cloud

ID Card Recognition
Last updated: 2025-09-09 20:02:18
ID Card Recognition
Last updated: 2025-09-09 20:02:18

Feature Description

Support recognition of all fields on both sides of second-generation Chinese ID cards for residents on the Chinese mainland, including name, gender, ethnicity, date of birth, address, identification number, issuing authority, and validity period; possess cropping function for ID card photos and portrait photos, as well as alarm features for rephotographed, PS-ed, and photocopied documents, along with extended features such as border and frame block alarm, temporary ID card alarm, and invalid validity period alert.
Note:
The feature currently only provides API usage.

Authorization Description

When used by a sub-account, the ci:CreateIDCardOCRJob permission must be granted. For details, see Cloud Infinite action.

Activating a Service

Using this feature requires enabling Cloud Infinite in advance and binding a bucket. For details, see Bind Bucket.
Use this feature requires enabling AI Content Recognition service in advance via console or API. For details, see Enable AI Content Recognition Service.

Use Limits

When using this API, please confirm the relevant restrictions first. For details, see Usage Limits.
Current identity card recognition requires the image to be no more than 7M after Base64 encoding, with a resolution of at least 500 × 800 recommended, and supports PNG, JPG, JPEG, BMP formats. It is advisable for the card part to occupy more than 2/3 of the image.

Fee Description

This API is a paid service. Generated costs will be charged by Cloud Infinite. For detailed billing instructions, see Content Recognition.


Request

Process Upon Upload

The request packet for recognition during ID card photo upload matches the simple file upload API of COS. Just add relevant processing parameters to return recognition results during image upload and store the original image in COS.
PUT /<ObjectKey>?ci-process=IDCardOCR&CardSide=<CardSide>&Config=<Config> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>

Note:
Authorization: Auth String. For details, see Request Signature document.

Cloud Data Processing

Cloud data processing requests can perform corresponding processing operations on stored ID card photos in COS and return recognition results.
GET /<ObjectKey>?ci-process=IDCardOCR&CardSide=<CardSide>&Config=<Config> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>

Note:
Authorization: Auth String. For details, see Request Signature document.

Request parameters.

Parameter Name
Description
Type
Required or Not
ObjectKey
object filename, for example: folder/document.jpg
String
Yes
ci-process
Cloud Infinite processing capability IDCardOCR fixed as identity card recognition
String
Yes
CardSide
FRONT: The photo side of the identity card (portrait side)
BACK: The national emblem side of the identity card (national emblem side)
If this parameter is not filled in, it will automatically determine both sides of the ID card.
String
No
Config
The following optional fields are all bool type, default false.
CropIdCard, ID card photo cropping (remove extra edges outside the document, automatically correct shooting angle)
Crop portrait (automatically cut out the ID card portrait area)
CopyWarn, photocopy alarm
BorderCheckWarn, border and frame block alarm
ReshootWarn
DetectPsWarn, PS detection alarm
TempIdWarn, temporary ID card alarm
InvalidDateWarn, invalid date alarm for ID card validity
Quality, image quality score (evaluates the blurriness of an image)
MultiCardDetect, whether multi-card detection is enabled
Parameter setting method reference:
Config = {"CropIdCard":true,"CropPortrait":true}
String
No

Request header.

This API only uses common request headers. For details, see Common Request Headers documentation.

Request body.

This request has no request body.

Response

Response Headers

This API only returns the public response header. For details, see Common Response Headers documentation.

Response Body

The response body is returned as application/xml. An example including the complete node data is shown below:
<Response>
  <IdInfo>
    identity card recognition information
  </IdInfo>
  <AdvancedInfo>
    identity card recognition information
  </AdvancedInfo>
</Response>
The data are as follows:
Node Name (Keyword)
Parent Node
Description
Type
Response
None.
Container for saving results
Container
The content of the Response
Node Name (Keyword)
Parent Node
Description
Type
IdInfo
Response
Identity card recognition information
Container
AdvancedInfo
Response
extended information, do not return if not requested
Container
Identity card recognition information contains the following content:
Node Name (Keyword)
Parent Node
Description
Type
Name
IdInfo
name (portrait side)
String
Sex
IdInfo
gender (portrait side)
String
Nation
IdInfo
ethnicity (portrait side)
String
Birth
IdInfo
date of birth (portrait side)
String
Address
IdInfo
address (portrait side)
String
IdNum
IdInfo
identity card number (portrait side)
String
Authority
IdInfo
issuing authority (national emblem side)
String
ValidDate
IdInfo
document validity period (national emblem side)
String
The AdvancedInfo contains the following content:
Node Name (Keyword)
Parent Node
Description
Type
IdCard
AdvancedInfo
Base64-encoded cropped ID card photo, returned when Config.CropIdCard is set to true
String
Portrait
AdvancedInfo
Base64-encoded ID card portrait photo, returned when Config.CropPortrait is set to true
String
Quality
AdvancedInfo
Image quality score, returned when Config.Quality is set to true (value range: 0~100, lower score indicates blurrier image, recommended threshold ≥50)
String
BorderCodeValue
AdvancedInfo
ID card border incomplete alarm threshold score, returned when Config.BorderCheckWarn is set to true (value range: 0~100, lower score indicates lower likelihood of border obstruction, recommended threshold ≥50)
String
WarnInfos
IdInfo
alarm information, Code: list of alarm codes and their definitions
9100 invalid date alarm for ID card validity
incomplete ID card border alarm
9102 ID card copy alarm
9103 alarm for identity card rephotographing
9104 temporary ID card alarm
9105 ID card frame occlusion alarm
9106 ID card PS alarm
Multiple WarnInfos may exist
String

Examples

Request

GET /test.jpg?ci-process=IDCardOCR&CardSide=FRONT&Config={"CropIdCard":true, "CropIdCard":true} HTTP/1.1
Authorization: q-sign-algorithm=sha1&q-ak=**********************************&q-sign-time=1497530202;1497610202&q-key-time=1497530202;1497610202&q-header-list=&q-url-param-list=&q-signature=**************************************
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 414641
Date: Thu, 15 Jun 2017 12:37:29 GMT
Server: tencent-ci
x-ci-request-id: NTk0MjdmODlfMjQ4OGY3XzYzYzhf****

<Response>
  <IdInfo>
     <Name>Li Ming</Name>
     <Sex>Male</Sex>
     <Nation>Han</Nation>
     <Birth>1987/1/1</Birth>
     <Address>Beijing Shijingshan High-tech Park Tencent Building</Address>
     <IdNum>440524198701010014</IdNum>
  </IdInfo>
  <AdvancedInfo>
     <IdCard>Cropped ID card photo's Base64 encoding</IdCard>
     <Portrait>Base64 encoding of ID card portrait photo</Portrait>
  </AdvancedInfo>
</Response>

Error Code

The following lists only error codes related to API business logic. For other error information, please refer to the Error Codes document.
Error Code
Description
FailedOperation.DownLoadError
file download failure
FailedOperation.EmptyImageError
image content empty
FailedOperation.IdCardInfoIllegal
identity card information is invalid (invalid identity card number, name field verification invalid, etc.)
FailedOperation.ImageBlur
blurry image
FailedOperation.ImageDecodeFailed
image decoding failure
FailedOperation.ImageNoIdCard
No identity card detected in the image
FailedOperation.ImageSizeTooLarge
Image size is too large. See the description about image size limit in the output parameters.
FailedOperation.MultiCardError
Multiple cards exist in the photo
FailedOperation.OcrFailed
OCR recognition failed.
FailedOperation.UnKnowError
Unknown error.
FailedOperation.UnOpenError
Service not activated
InvalidParameter.ConfigFormatError
Invalid Config format
InvalidParameterValue.InvalidParameterValueLimit
Parameter Value Error
LimitExceeded.TooLargeFileError
File content is too large
ResourcesSoldOut.ChargeStatusException
Billing status abnormal

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback