1. 接口描述
接口请求域名: ocr.tencentcloudapi.com 。
身份证识别(安全加密版)接口实现了数据加密传输,能够有效防止个人身份证隐私信息不被窃取泄露。
本接口支持中国大陆居民二代身份证正反面所有字段的识别,包括姓名、性别、民族、出生日期、住址、公民身份证号、签发机关、有效期限,识别准确度达到99%以上。
另外,本接口还支持多种增值能力,满足不同场景的需求。如身份证照片、人像照片的裁剪功能,同时具备9种告警功能,如下表所示。
增值能力 | 能力项 |
---|---|
裁剪功能 | 身份证照片裁剪(去掉证件外多余的边缘、自动矫正拍摄角度) |
人像照片裁剪(自动抠取身份证头像区域) | |
告警功能 | 身份证有效日期不合法,即有效日期不符合5年、10年、20年、长期期限 |
身份证边框不完整告警 | |
身份证复印件告警 | |
身份证翻拍告警 | |
身份证框内遮挡告警 | |
临时身份证告警 | |
身份证疑似存在PS痕迹告警 | |
图片模糊告警(可根据图片质量分数判断) |
默认接口请求频率限制:20次/秒。
推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数。
参数名称 | 必选 | 类型 | 描述 |
---|---|---|---|
Action | 是 | String | 公共参数,本接口取值:RecognizeEncryptedIDCardOCR。 |
Version | 是 | String | 公共参数,本接口取值:2018-11-19。 |
Region | 是 | String | 公共参数,详见产品支持的 地域列表,本接口仅支持其中的: ap-beijing, ap-guangzhou, ap-hongkong, ap-shanghai 。 |
EncryptedBody | 是 | String | 请求体被加密后的密文,本接口只支持加密传输 |
Encryption | 是 | Encryption | 敏感数据加密信息。对传入信息有加密需求的用户可使用此参数,详情请点击左侧链接。 |
ImageBase64 | 否 | String | 图片的 Base64 值。要求图片经Base64编码后不超过 7M,分辨率建议500*800以上,支持PNG、JPG、JPEG、BMP格式。建议卡片部分占据图片2/3以上。 图片的 ImageUrl、ImageBase64 必须提供一个,如果都提供,只使用 ImageUrl。 |
ImageUrl | 否 | String | 图片的 Url 地址。要求图片经Base64编码后不超过 7M,分辨率建议500*800以上,支持PNG、JPG、JPEG、BMP格式。建议卡片部分占据图片2/3以上。图片下载时间不超过 3 秒。 建议图片存储于腾讯云,可保障更高的下载速度和稳定性。 示例值:https://xx/a.jpg |
CardSide | 否 | String | FRONT:身份证有照片的一面(人像面), BACK:身份证有国徽的一面(国徽面), 该参数如果不填,将为您自动判断身份证正反面。 示例值:FRONT |
Config | 否 | String | 以下可选字段均为bool 类型,默认false: CropIdCard,身份证照片裁剪(去掉证件外多余的边缘、自动矫正拍摄角度) CropPortrait,人像照片裁剪(自动抠取身份证头像区域) CopyWarn,复印件告警 BorderCheckWarn,边框和框内遮挡告警 ReshootWarn,翻拍告警 DetectPsWarn,疑似存在PS痕迹告警 TempIdWarn,临时身份证告警 InvalidDateWarn,身份证有效日期不合法告警 Quality,图片质量分数(评价图片的模糊程度) MultiCardDetect,是否开启正反面同框识别(仅支持二代身份证正反页同框识别或临时身份证正反页同框识别) ReflectWarn,是否开启反光检测 SDK 设置方式参考: Config = Json.stringify({"CropIdCard":true,"CropPortrait":true}) API 3.0 Explorer 设置方式参考: Config = {"CropIdCard":true,"CropPortrait":true} |
EnableRecognitionRectify | 否 | Boolean | 默认值为true,打开识别结果纠正开关。开关开启后,身份证号、出生日期、性别,三个字段会进行矫正补齐,统一结果输出;若关闭此开关,以上三个字段不会进行矫正补齐,保持原始识别结果输出,若原图出现篡改情况,这三个字段的识别结果可能会不统一。 示例值:false |
EnableReflectDetail | 否 | Boolean | 默认值为false。 此开关需要在反光检测开关开启下才会生效(即此开关生效的前提是config入参里的"ReflectWarn":true),若EnableReflectDetail设置为true,则会返回反光点覆盖区域详情。反光点覆盖区域详情分为四部分:人像照片位置、国徽位置、识别字段位置、其他位置。一个反光点允许覆盖多个区域,且一张图片可能存在多个反光点。 示例值:false |
3. 输出参数
参数名称 | 类型 | 描述 |
---|---|---|
Name | String | 姓名(人像面) 示例值:李明 |
Sex | String | 性别(人像面) 示例值:男 |
Nation | String | 民族(人像面) 示例值:汉 |
Birth | String | 出生日期(人像面) 示例值:1987/1/1 |
Address | String | 地址(人像面) 示例值:北京市石景山区高新技术园腾讯大楼 |
IdNum | String | 身份证号(人像面) 示例值:440524198701010014 |
Authority | String | 发证机关(国徽面) |
ValidDate | String | 证件有效期(国徽面) |
AdvancedInfo | String | 扩展信息,不请求则不返回,具体输入参考示例3和示例4。 IdCard,裁剪后身份证照片的base64编码,请求 Config.CropIdCard 时返回; Portrait,身份证头像照片的base64编码,请求 Config.CropPortrait 时返回; Quality,图片质量分数,请求 Config.Quality 时返回(取值范围:0 ~ 100,分数越低越模糊,建议阈值≥50); BorderCodeValue,身份证边框不完整告警阈值分数,请求 Config.BorderCheckWarn时返回(取值范围:0 ~ 100,分数越低边框遮挡可能性越低,建议阈值≤50); WarnInfos,告警信息,Code 告警码列表和释义: -9100 身份证有效日期不合法告警, -9101 身份证边框不完整告警, -9102 身份证复印件告警(黑白及彩色复印件), -9108 身份证复印件告警(仅黑白复印件), -9103 身份证翻拍告警, -9105 身份证框内遮挡告警, -9104 临时身份证告警, -9106 身份证疑似存在PS痕迹告警, -9107 身份证反光告警。 示例值:{} |
ReflectDetailInfos | Array of ReflectDetailInfo | 反光点覆盖区域详情结果,具体内容请点击左侧链接 |
EncryptedBody | String | 加密后的数据 |
Encryption | Encryption | 敏感数据加密信息 |
RequestId | String | 唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 身份证识别(安全加密版)示例
身份证识别(安全加密版)示例
输入示例
POST / HTTP/1.1
Host: ocr.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: RecognizeEncryptedIDCardOCR
<公共请求参数>
{
"ImageBase64": "",
"ImageUrl": "",
"CardSide": "",
"Config": "",
"EncryptedBody": "cpA8uWgtLjDSY8NvIoRe/UH0LlAa8+a3Jj6lVN5+9u4LFQxEj3x3QqNnPXZJ3f5aAcEYZPxnaglJVSzimWT8rDKJmnFRU2309cJysuV7GVZgfiLPlAtZ659BRUYTgZD2aLSSD2WJZt1izHmPx1Lt1A==",
"Encryption": {
"Algorithm": "AES-256-CBC",
"TagList": [],
"CiphertextBlob": "sBmIZTmfcZ4FZIskKB1PC3yYx0a/CxBh8KwnQWgsgK96UeHeswIJdH7Gt4LW8yiIUjFq7PdikshkRdYPk9OWWEfAWb70DjfNnWLhI8FMMT72A+V+uWeQZN4VtwWdH6I2FrV4aXYxblq7cHHALvL1Ey8x0Cl9CFBeIrQsBGNnnW8=",
"Iv": "U2KHDqXYtpCl3l5BRuH0qw==",
"EncryptList": [
"EncryptedBody"
]
}
}
输出示例
{
"Response": {
"Address": "",
"AdvancedInfo": "",
"Authority": "",
"Birth": "",
"EncryptedBody": "R+psIR59D8HR23D2S1SpEDrR0GPkpzQ+ynmilaOGMI0b/qKNJVYxo/myjctCdswpctobCP+QDd1nG0tYe651VfkcgBYcRPjEKp7sXKIKsOL7f6kilHoLkCCbpzXGq+Q6c+A+TdxUC36xT8jfYF/5mFqRD/qnEqlg/9L/6SeJ+6TQ0CWPmlAzw2dRWvSHq/sigMd98CAsk9M7VvqYFYM9uuIm62etac2/i8OpVSww3RVuIDNprJS/iM4BlmA3Y8hdv2EDp5zZy9BIo1Nzx+qAVhpMxasLs/1sEBBDaxRzP6o=",
"Encryption": {
"Algorithm": "AES-256-CBC",
"CiphertextBlob": "sBmIZTmfcZ4FZIskKB1PC3yYx0a/CxBh8KwnQWgsgK96UeHeswIJdH7Gt4LW8yiIUjFq7PdikshkRdYPk9OWWEfAWb70DjfNnWLhI8FMMT72A+V+uWeQZN4VtwWdH6I2FrV4aXYxblq7cHHALvL1Ey8x0Cl9CFBeIrQsBGNnnW8=",
"EncryptList": [
"EncryptedBody"
],
"Iv": "U2KHDqXYtpCl3l5BRuH0qw==",
"TagList": null
},
"IdNum": "",
"Name": "",
"Nation": "",
"ReflectDetailInfos": [],
"RequestId": "9782fbce-de72-4325-8e07-ffb3d540be90",
"Sex": "",
"ValidDate": ""
}
}
5. 开发者资源
腾讯云 API 平台
腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台,方便您从同一入口查询及使用腾讯云提供的所有 API 服务。
API Inspector
用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况,并自动生成各语言版本的 API 代码,也可前往 API Explorer 进行在线调试。
SDK
云 API 3.0 提供了配套的开发工具集(SDK),支持多种编程语言,能更方便的调用 API。
- Tencent Cloud SDK 3.0 for Python: GitHub Gitee
- Tencent Cloud SDK 3.0 for Java: GitHub Gitee
- Tencent Cloud SDK 3.0 for PHP: GitHub Gitee
- Tencent Cloud SDK 3.0 for Go: GitHub Gitee
- Tencent Cloud SDK 3.0 for Node.js: GitHub Gitee
- Tencent Cloud SDK 3.0 for .NET: GitHub Gitee
- Tencent Cloud SDK 3.0 for C++: GitHub Gitee
- Tencent Cloud SDK 3.0 for Ruby: GitHub Gitee
命令行工具
6. 错误码
以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码。
错误码 | 描述 |
---|---|
FailedOperation.CardSideError | 身份证CardSide类型错误 |
FailedOperation.DownLoadError | 文件下载失败。 |
FailedOperation.EmptyImageError | 图片内容为空。 |
FailedOperation.IdCardInfoIllegal | 第二代身份证信息不合法或缺失(身份证号、姓名字段校验非法等) |
FailedOperation.IdCardTooSmall | 图片分辨率过小或身份证在原图中的占比过小 |
FailedOperation.ImageBlur | 图片模糊。 |
FailedOperation.ImageDecodeFailed | 图片解码失败。 |
FailedOperation.ImageNoIdCard | 图片中未检测到第二代身份证或临时身份证。 |
FailedOperation.ImageSizeTooLarge | 图片尺寸过大,请参考输入参数中关于图片大小限制的说明。 |
FailedOperation.MultiCardError | 图片中存在两张及以上同面卡证,请上传卡证单面图片或一正一反双面图片。 |
FailedOperation.OcrFailed | OCR识别失败。 |
FailedOperation.UnKnowError | 未知错误。 |
FailedOperation.UnOpenError | 服务未开通。 |
InvalidParameter.ConfigFormatError | Config不是有效的JSON格式。 |
InvalidParameterValue.InvalidParameterValueLimit | 参数值错误。 |
LimitExceeded.TooLargeFileError | 文件内容太大。 |
ResourceUnavailable.InArrears | 账号已欠费。 |
ResourceUnavailable.ResourcePackageRunOut | 账号资源包耗尽。 |
ResourcesSoldOut.ChargeStatusException | 计费状态异常。 |