API 文档
概述 接口地址 输入参数 输出参数 扩展能力 调用示例 错误码 📝 在线测试

🪪 身份证识别

基于腾讯云OCR IDCardOCR API

POST https://ocr.tencentcloudapi.com

1. 接口描述

接口请求域名： ocr.tencentcloudapi.com

本接口支持中国大陆居民二代身份证正反面所有字段的识别，包括姓名、性别、民族、出生日期、住址、公民身份证号、签发机关、有效期限，识别准确度达到99%以上。

另外，本接口还支持多种扩展能力，满足不同场景的需求。如身份证照片、人像照片的裁剪功能。

默认接口请求频率限制：20次/秒。

扩展能力

能力项 说明
CropIdCard 身份证照片裁剪（去掉证件外多余的边缘、自动矫正拍摄角度）
CropPortrait 人像照片裁剪（自动抠取身份证头像区域）

接口地址

请求地址 
POST https://ocr.tencentcloudapi.com

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。

参数名称 必选 类型 描述
Action 是 String 公共参数，本接口取值：IDCardOCR
Version 是 String 公共参数，本接口取值：2018-11-19
Region 否 String 公共参数，此参数为可选参数
ImageBase64 否 String 图片的 Base64 值。要求图片经Base64编码后不超过 10M，分辨率建议500*800以上，支持PNG、JPG、JPEG、BMP格式。建议卡片部分占据图片2/3以上。图片的 ImageUrl、ImageBase64 必须提供一个，如果都提供，只使用 ImageUrl。
ImageUrl 否 String 图片的 Url 地址。要求图片经Base64编码后不超过 10M，分辨率建议500*800以上，支持PNG、JPG、JPEG、BMP格式。建议卡片部分占据图片2/3以上。建议图片存储于腾讯云，可保障更高的下载速度和稳定性。
CardSide 否 String FRONT：身份证有照片的一面（人像面）
BACK：身份证有国徽的一面（国徽面）
该参数如果不填，将为您自动判断身份证正反面
Config 否 String 以下可选字段均为bool类型，默认false：
CropIdCard，身份证照片裁剪（去掉证件外多余的边缘、自动矫正拍摄角度）
CropPortrait，人像照片裁剪（自动抠取身份证头像区域）
示例值：{"CropIdCard":true,"CropPortrait":true}
EnableRecognitionRectify 否 Boolean 默认值为true，打开识别结果纠正开关。开关开启后，身份证号、出生日期、性别，三个字段会进行矫正补齐，统一结果输出。

3. 输出参数

参数名称 类型 描述
Name String 姓名（人像面）
Sex String 性别（人像面）
Nation String 民族（人像面）
Birth String 出生日期（人像面）
Address String 地址（人像面）
IdNum String 身份证号（人像面）
Authority String 发证机关（国徽面）
ValidDate String 证件有效期（国徽面）
AdvancedInfo String 扩展信息，不请求则不返回：
IdCard，裁剪后身份证照片的base64编码，请求 Config.CropIdCard 时返回；
Portrait，身份证头像照片的base64编码，请求 Config.CropPortrait 时返回
RequestId String 唯一请求 ID，由服务端生成，每次请求都会返回

扩展能力

✂️

身份证照片裁剪

设置 CropIdCard: true

去掉证件外多余的边缘、自动矫正拍摄角度

结果输出到 AdvancedInfo.IdCard

👤

人像照片裁剪

设置 CropPortrait: true

自动抠取身份证头像区域

结果输出到 AdvancedInfo.Portrait

4. 示例

示例1：身份证照片裁剪和人像照片裁剪调用示例

输入示例 
POST / HTTP/1.1
Host: ocr.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: IDCardOCR

{
  "SecretId": "AKIDdIjxymOny9JONG2hJ7qPp8KLPPCmA0gB",
  "SecretKey": "ObgaJuMekfSBzfLvNeKqJlHcmx2ziO6t",
  "ImageUrl": "https://ocr-demo-1254418846.cos.ap-guangzhou.myqcloud.com/card/IDCardOCR/IDCardOCR1.jpg",
  "Config": "{\"CropIdCard\":true,\"CropPortrait\":true}",
  "CardSide": "FRONT"
}
输出示例 
{
  "Response": {
    "Name": "李明",
    "Sex": "男",
    "Nation": "汉",
    "Birth": "1987/1/1",
    "Address": "北京市石景山区高新技术园腾讯大楼",
    "IdNum": "440524198701010014",
    "Authority": "",
    "ValidDate": "",
    "AdvancedInfo": "{\"IdCard\":\"/9j/4AAQSkZJRg.....s97n//2Q==\",\"Portrait\":\"/9j/4AAQSkZJRg.....s97n//2Q==\"}",
    "RequestId": "97c323da-5fd3-4fe6-b0b3-1cf10b04422c"
  }
}

示例2：身份证识别（人像面）调用示例

输入示例 
POST / HTTP/1.1
Host: ocr.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: IDCardOCR

{
  "SecretId": "AKIDdIjxymOny9JONG2hJ7qPp8KLPPCmA0gB",
  "SecretKey": "ObgaJuMekfSBzfLvNeKqJlHcmx2ziO6t",
  "ImageUrl": "https://ocr-demo-1254418846.cos.ap-guangzhou.myqcloud.com/card/IDCardOCR/IDCardOCR1.jpg",
  "CardSide": "FRONT"
}
输出示例 
{
  "Response": {
    "Address": "广东省深圳市南山区腾讯大厦",
    "Authority": "",
    "Birth": "1995/5/13",
    "IdNum": "440305199505132561",
    "Name": "刘洋",
    "Nation": "汉",
    "RequestId": "c762a670-c622-408a-865a-da27a9ffa53b",
    "Sex": "女",
    "ValidDate": ""
  }
}

示例3：身份证识别（国徽面）调用示例

输入示例 
POST / HTTP/1.1
Host: ocr.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: IDCardOCR

{
  "SecretId": "AKIDdIjxymOny9JONG2hJ7qPp8KLPPCmA0gB",
  "SecretKey": "ObgaJuMekfSBzfLvNeKqJlHcmx2ziO6t",
  "ImageUrl": "https://ocr-demo-1254418846.cos.ap-guangzhou.myqcloud.com/card/IDCardBackOCR/IDCardBackOCR2.jpg",
  "CardSide": "BACK"
}
输出示例 
{
  "Response": {
    "Address": "",
    "Authority": "上海市公安局南山分局",
    "Birth": "",
    "IdNum": "",
    "Name": "",
    "Nation": "",
    "RequestId": "c058efd9-a469-4256-a18d-bf539fd2231b",
    "Sex": "",
    "ValidDate": "2018.08.12-2038.08.12"
  }
}

示例4：cURL 调用

cURL 
curl -X POST "https://ocr.tencentcloudapi.com" \
  -H "Content-Type: application/json" \
  -H "X-TC-Action: IDCardOCR" \
  -H "X-TC-Version: 2018-11-19" \
  -d '{
    "SecretId": "AKIDdIjxymOny9JONG2hJ7qPp8KLPPCmA0gB",
    "SecretKey": "ObgaJuMekfSBzfLvNeKqJlHcmx2ziO6t",
    "ImageUrl": "图片URL地址",
    "Config": "{\"CropIdCard\":true,\"CropPortrait\":true}",
    "CardSide": "FRONT"
  }'

示例5：PHP 调用

PHP 
<?php
// 腾讯云API密钥
$secretId = 'AKIDdIjxymOny9JONG2hJ7qPp8KLPPCmA0gB';
$secretKey = 'ObgaJuMekfSBzfLvNeKqJlHcmx2ziO6t';

// 请求参数
$params = [
    'Action' => 'IDCardOCR',
    'Version' => '2018-11-19',
    'ImageUrl' => '图片URL地址',
    'CardSide' => 'FRONT',
    'Config' => json_encode([
        'CropIdCard' => true,
        'CropPortrait' => true,
    ]),
];

// 调用API
$result = callTencentOCR($secretId, $secretKey, $params);

// 解析结果
if (isset($result['Response']['Error'])) {
    echo '错误：' . $result['Response']['Error']['Message'];
} else {
    $data = $result['Response'];
    echo '姓名：' . $data['Name'] . PHP_EOL;
    echo '性别：' . $data['Sex'] . PHP_EOL;
    echo '民族：' . $data['Nation'] . PHP_EOL;
    echo '出生：' . $data['Birth'] . PHP_EOL;
    echo '住址：' . $data['Address'] . PHP_EOL;
    echo '身份证号：' . $data['IdNum'] . PHP_EOL;
    
    // 解析扩展信息
    $advancedInfo = json_decode($data['AdvancedInfo'] ?? '{}', true);
    if (!empty($advancedInfo['IdCard'])) {
        file_put_contents('idcard_cropped.jpg', base64_decode($advancedInfo['IdCard']));
    }
    if (!empty($advancedInfo['Portrait'])) {
        file_put_contents('portrait_cropped.jpg', base64_decode($advancedInfo['Portrait']));
    }
}
?>

5. 错误码

以下仅列出了接口业务逻辑相关的错误码，其他错误码见 公共错误码。

错误码 描述
FailedOperation.CardSideError 身份证CardSide类型错误
FailedOperation.DownLoadError 文件下载失败
FailedOperation.EmptyImageError 图片内容为空
FailedOperation.IdCardInfoIllegal 第二代身份证信息不合法或缺失
FailedOperation.IdCardTooSmall 图片分辨率过小或身份证在原图中的占比过小
FailedOperation.ImageBlur 图片模糊
FailedOperation.ImageDecodeFailed 图片解码失败
FailedOperation.ImageNoIdCard 图片中未检测到第二代身份证或临时身份证
FailedOperation.ImageSizeTooLarge 图片尺寸过大
FailedOperation.MultiCardError 图片中存在两张及以上同面卡证
FailedOperation.OcrFailed OCR识别失败
InvalidParameter.ConfigFormatError Config不是有效的JSON格式
LimitExceeded.TooLargeFileError 文件内容太大

6. 开发者资源

PHP SDK 已集成所有功能，开箱即用：

📦 下载 PHP SDK

腾讯云官方 SDK：
PHP · Python · Java · Go · Node.js