API 文档

SDK 文档

诚邀爱技术、爱分享的你,成为文档内容共建者> HOT

功能描述

支持中国大陆居民二代身份证正反面所有字段的识别,包括姓名、性别、民族、出生日期、住址、公民身份证号、签发机关、有效期限;具备身份证照片、人像照片的裁剪功能和翻拍、PS、复印件告警功能,以及边框和框内遮挡告警、临时身份证告警和身份证有效期不合法告警等扩展功能。

说明:

  • 当前身份证识别的图片限制为:要求图片经 Base64 编码后不超过7M,分辨率建议500 × 800以上,支持 PNG、JPG、JPEG、BMP 格式。建议卡片部分占据图片2/3以上。
  • 身份证识别为付费服务,计费详情请参见 内容识别费用
  • 该功能目前仅提供 API 使用方式。

请求

上传时处理

身份证图片上传时识别的请求包与 COS 简单上传文件接口一致,只需增加相关处理参数,即可在图片上传时返回识别结果,并可将原图存入到 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>

说明:

  • Authorization: Auth String(详情请参见 请求签名 文档)。
  • 通过子账号使用时,需要授予相关的权限,详情请参见 授权粒度详情 文档。

云上数据处理

云上数据处理请求能够对已存储在 COS 的身份证图片进行相应处理操作,返回识别结果。

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>

说明:

  • Authorization: Auth String(详情请参见 请求签名 文档)。
  • 通过子账号使用时,需要授予相关的权限,详情请参见 授权粒度详情 文档。

请求参数

参数名称 描述 类型 是否必选
ObjectKey 对象文件名,例如:folder/document.jpg String
ci-process 数据万象处理能力,身份证识别固定为 IDCardOCR String
CardSide
  • FRONT:身份证有照片的一面(人像面)
  • BACK:身份证有国徽的一面(国徽面)
    该参数如果不填,将为您自动判断身份证正反面
  • String
    Config 以下可选字段均为 bool 类型,默认 false:
  • CropIdCard,身份证照片裁剪(去掉证件外多余的边缘、自动矫正拍摄角度)
  • CropPortrait,人像照片裁剪(自动抠取身份证头像区域)
  • CopyWarn,复印件告警
  • BorderCheckWarn,边框和框内遮挡告警
  • ReshootWarn,翻拍告警
  • DetectPsWarn,PS 检测告警
  • TempIdWarn,临时身份证告警
  • InvalidDateWarn,身份证有效日期不合法告警
  • Quality,图片质量分数(评价图片的模糊程度)
  • MultiCardDetect,是否开启多卡证检测
    参数设置方式参考:
    Config = {"CropIdCard":true,"CropPortrait":true}
  • String

    请求头

    此接口仅使用公共请求头部,详情请参见 公共请求头部 文档。

    请求体

    该请求无请求体。

    响应

    响应头

    此接口仅返回公共响应头部,详情请参见 公共响应头部 文档。

    响应体

    该响应体返回为 application/xml 数据,包含完整节点数据的内容展示如下:

    <Response>
      <IdInfo>
        身份证识别信息
      </IdInfo>
      <AdvancedInfo>
        身份证识别信息
      </AdvancedInfo>
    </Response>

    具体的数据内容如下:

    节点名称(关键字) 父节点 描述 类型
    Response 保存结果的容器 Container

    Response 的内容:

    节点名称(关键字) 父节点 描述 类型
    IdInfo Response 身份证识别信息 Container
    AdvancedInfo Response 扩展信息,不请求则不返回 Container

    IdInfo身份证识别信息中包含如下内容:

    节点名称(关键字) 父节点 描述 类型
    Name IdInfo 姓名(人像面) String
    Sex IdInfo 性别(人像面) String
    Nation IdInfo 民族(人像面) String
    Birth IdInfo 出生日期(人像面) String
    Address IdInfo 地址(人像面) String
    IdNum IdInfo 身份证号(人像面) String
    Authority IdInfo 发证机关(国徽面) String
    ValidDate IdInfo 证件有效期(国徽面) String

    AdvancedInfo扩展信息信息中包含如下内容:

    节点名称(关键字) 父节点 描述 类型
    IdCard AdvancedInfo 裁剪后身份证照片的 Base64 编码,设置 Config.CropIdCard 为 true 时返回 String
    Portrait AdvancedInfo 身份证头像照片的 Base64 编码,设置 Config.CropPortrait 为 true 时返回 String
    Quality AdvancedInfo 图片质量分数,设置 Config.Quality 为 true 时返回(取值范围:0~100,分数越低越模糊,建议阈值≥50) String
    BorderCodeValue AdvancedInfo 身份证边框不完整告警阈值分数,设置 Config.BorderCheckWarn 为 true 时返回(取值范围:0~100,分数越低边框遮挡可能性越低,建议阈值≥50) String
    WarnInfos IdInfo 告警信息,Code 告警码列表和释义:
  • 9100 身份证有效日期不合法告警
  • 9101 身份证边框不完整告警
  • 9102 身份证复印件告警
  • 9103 身份证翻拍告警
  • 9104 临时身份证告警
  • 9105 身份证框内遮挡告警
  • 9106 身份证 PS 告警
    可能存在多个 WarnInfos
  • String

    实际案例

    请求

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

    响应

    HTTP/1.1 200 OK
    Content-Type: application/xml
    Content-Length: 414641
    Date: Thu, 15 Jun 2017 12:37:29 GMT
    Server: tencent-image
    x-ci-request-id: NTk0MjdmODlfMjQ4OGY3XzYzYzhf****
    
    <Response>
      <IdInfo>
         <Name>李明</Name>
         <Sex>男</Sex>
         <Nation>汉</Nation>
         <Birth>1987/1/1</Birth>
         <Address>北京市石景山区高新技术园腾讯大楼</Address>
         <IdNum>440524198701010014</IdNum>
      </IdInfo>
      <AdvancedInfo>
         <IdCard>裁剪后身份证照片的 Base64 编码</IdCard>
         <Portrait>身份证头像照片的 Base64 编码</Portrait>
      </AdvancedInfo>
    </Response>

    错误码

    以下仅列出了接口业务逻辑相关的错误码,其他错误信息请参见 错误码 文档。

    错误码 描述
    FailedOperation.DownLoadError 文件下载失败
    FailedOperation.EmptyImageError 图片内容为空
    FailedOperation.IdCardInfoIllegal 身份证信息不合法(身份证号、姓名字段校验非法等)
    FailedOperation.ImageBlur 图片模糊
    FailedOperation.ImageDecodeFailed 图片解码失败
    FailedOperation.ImageNoIdCard 图片中未检测到身份证
    FailedOperation.ImageSizeTooLarge 图片尺寸过大,请参考输出参数中关于图片大小限制的说明
    FailedOperation.MultiCardError 照片中存在多张卡
    FailedOperation.OcrFailed OCR 识别失败
    FailedOperation.UnKnowError 未知错误
    FailedOperation.UnOpenError 服务未开通
    InvalidParameter.ConfigFormatError Config 格式错误
    InvalidParameterValue.InvalidParameterValueLimit 参数值错误
    LimitExceeded.TooLargeFileError 文件内容太大
    ResourcesSoldOut.ChargeStatusException 计费状态异常
    目录