腾讯云身份证识别 (IDCardOCR)

用途

调用腾讯云OCR身份证识别接口，支持中国大陆居民二代身份证正反面所有字段的识别，识别准确度达99%以上。

核心能力：

• 人像面(FRONT)：识别姓名、性别、民族、出生日期、住址、公民身份证号
• 国徽面(BACK)：识别签发机关、证件有效期
• 附加功能：身份证照片/人像照片裁剪、7种告警检测（复印件、翻拍、PS、临时身份证等）

官方文档：https://cloud.tencent.com/document/api/866/33524

使用时机

当用户提出以下需求时触发此技能：

• 需要从身份证图片中提取文字信息
• 需要验证身份证真伪（复印件/翻拍/PS检测）
• 需要裁剪身份证照片或人像照片
• 涉及身份证OCR识别的任何场景

环境要求

• Python 3.6+
• 依赖：tencentcloud-sdk-python（通过 pip install tencentcloud-sdk-python 安装）
• 环境变量：
  • TENCENTCLOUD_SECRET_ID：腾讯云API密钥ID
  • TENCENTCLOUD_SECRET_KEY：腾讯云API密钥Key

使用方式

运行 scripts/main.py 脚本完成身份证识别。

请求参数

Config JSON 可选开关：CropIdCard、CropPortrait、CopyWarn、BorderCheckWarn、ReshootWarn、DetectPsWarn、TempIdWarn、InvalidDateWarn、Quality、MultiCardDetect、ReflectWarn

⚠️ UserAgent参数使用指南

--user-agent参数是可选参数，不传时脚本会自动探测当前调用平台（WorkBuddy / OpenClaw / QClaw / ADP / CodeBuddy），并输出 skill-；无法识别时回退为 skillother。用于标识API调用来源，便于按渠道追踪和统计调用次数：

实现说明:

• 不传 --user-agent 时，脚本通过环境变量 + 进程树回溯自动探测渠道
• SDK 会将其拼接为 SDK_PYTHON_x.x.x; skill- 注入到请求的 RequestClient 字段
• cam_access_server 会将此值写入 ES 日志的 requestClient 字段，可直接聚合统计
• 探测逻辑异常安全：任何失败回退为 skillother，不影响 OCR 主流程

输出格式

识别成功后返回 JSON 格式结果：

人像面(FRONT)：

{
  "Name": "张三",
  "Sex": "男",
  "Nation": "汉",
  "Birth": "1990/01/01",
  "Address": "XX省XX市XX区XX路XX号",
  "IdNum": "110101199001011234",
  "AdvancedInfo": "{"WarnInfos":[]}",
  "RequestId": "xxx"
}

国徽面(BACK)：

{
  "Authority": "XX市公安局",
  "ValidDate": "2020.01.01-2040.01.01",
  "AdvancedInfo": "{"WarnInfos":[]}",
  "RequestId": "xxx"
}

告警码说明

⚠️ 告警检测使用须知

WarnInfos 仅在 Config 字段非空时才会返回。--card-warn-type（Basic/Advanced）仅切换告警算法等级，不替代 Config。若需要检测电子身份证（-9110）等任何告警，必须在 --config 中开启至少一个告警开关（如 CopyWarn、BorderCheckWarn、ReshootWarn、DetectPsWarn、TempIdWarn、InvalidDateWarn、ReflectWarn 等）。

调用方指引：当用户表达了告警检测需求（如"检测电子身份证"、"检测翻拍"等）但未指定 --config 时，应主动向用户确认是否开启告警通道，并推荐默认配置 {"CopyWarn":true,"BorderCheckWarn":true,"ReshootWarn":true,"DetectPsWarn":true,"TempIdWarn":true,"InvalidDateWarn":true,"ReflectWarn":true}。

调用示例

# 基础调用示例（--user-agent 默认为 Skills，可不传）
python scripts/main.py --image-url "https://example.com/idcard.jpg" --card-side FRONT

# 使用 Base64 文件调用
python scripts/main.py --image-base64 "/path/to/base64.txt"

# 开启告警检测和照片裁剪
python scripts/main.py --image-url "https://example.com/idcard.jpg" 
  --config '{"CropIdCard":true,"CopyWarn":true,"ReshootWarn":true}'

# 使用进阶PS告警（需配合 --config 开启告警通道，否则 WarnInfos 不会返回）
python scripts/main.py --image-url "https://example.com/idcard.jpg" 
  --config '{"CopyWarn":true,"BorderCheckWarn":true,"ReshootWarn":true,"DetectPsWarn":true,"TempIdWarn":true,"InvalidDateWarn":true,"ReflectWarn":true}' 
  --card-warn-type Advanced