文档

异步检测

更新时间:

本文介绍了调用图片异步检测接口识别结构化卡证OCR的方法。结构化卡证OCR能够识别证件类图片中的文字并以结构化的方式返回文字内容。使用该场景的前提是您知道要检测的图片包含哪种类型的证件。

结构化卡证OCR目前支持识别以下卡证类型:营业执照、身份证(人像面和国徽面)、护照、银行卡、驾驶证(正反面)、行驶证(正反面)、车牌、车辆VIN码、户口簿户主页、户口簿常住人口页。

(图片异步检测)使用说明

业务接口:/green/image/asyncscan,表示图片异步检测。

您可以调用该接口创建图片异步检测任务。关于如何构造HTTP请求,请参见请求结构;您也可以直接选用已构造好的HTTP请求,更多信息,请参见SDK概览

  • 计费信息

    该接口为收费接口。关于计费方式,请参见内容安全产品定价

  • 检测超时

    同步检测允许的最长检测时间是6秒,如果检测在该时间限制内没有完成,系统会强制返回超时错误码。如果您对实时性要求不高,可以选择异步检测,其他情况下请选择同步检测,同步检测接口的调用相对简单些。对于同步检测接口的调用,建议您将超时时间设置为6秒。

  • 返回结果

    异步检测任务不会实时返回检测结果,您需要通过callback或者轮询的方式获取检测结果。检测结果最长保留一小时。

    • callback获取检测结果:提交异步检测任务时,在请求参数中传入callback参数,用来自动接收检测结果,具体请参见(异步检测)请求参数

    • 轮询获取检测结果:提交异步检测任务时,无需传入callback参数;提交异步检测任务后,调用结果查询接口获取检测结果,具体请参见(图片异步检测结果查询)使用说明

  • 图片要求

    • 图片链接支持以下协议:HTTP和HTTPS。

    • 图片支持以下格式:PNG、JPG、JPEG、BMP、GIF、WEBP。

    • 图片大小限制为20 MB以内(适用于同步和异步调用),高度或者宽度不能超过30,000像素(px),且图像总像素不超过2.5亿(px)

      说明

      其中,GIF格式的图片,图像总像素不超过4,194,304(px),高度或者宽度不能超过30,000像素(px)。

    • 图片下载时间限制为3秒内,如果下载时间超过3秒,返回下载超时。

    • 图片像素建议不低于256*256(px),像素过低可能会影响识别效果。

    • 图片检测接口的响应时间依赖图片的下载时间。请保证被检测图片所在的存储服务稳定可靠,建议您使用阿里云OSS存储或者CDN缓存等。

QPS限制

本接口的单用户QPS限制为10次/秒。超过限制,API调用会被限流,这可能会影响您的业务,请合理调用。

(异步检测)请求参数

名称

类型

是否必须

示例值

描述

bizType

String

default

该字段用于标识您的业务场景。您可以通过内容安全控制台创建业务场景(具体操作,请参见自定义机审标准)。

scenes

StringArray

["ocr"]

指定检测场景,取值:ocr

callback

String

http://www.aliyundoc.com/xx.json

检测结果回调通知您的URL,支持使用HTTP和HTTPS协议的地址。该字段为空时,您必须定时轮询检测结果。

callback接口必须支持POST方法、UTF-8编码的传输数据,以及表单参数checksumcontent。内容安全按照以下规则和格式设置checksumcontent,调用您的callback接口返回检测结果。

  • checksum:字符串格式,由用户uid + seed + content拼成字符串,通过SHA256算法生成。用户UID即阿里云账号ID,可以在阿里云控制台查询。为防篡改,您可以在获取到推送结果时,按上述算法生成字符串,与checksum做一次校验。

    说明

    用户UID必须是阿里云账号的UID,而不是RAM用户的UID。

  • content:JSON字符串格式,请自行解析反转成JSON对象。关于content结果的示例,请参见查询检测结果的返回示例。

说明

您的服务端callback接口收到内容安全推送的结果后,如果返回的HTTP状态码为200,则表示接收成功,其他的HTTP状态码均视为接收失败。接收失败时,内容安全将最多重复推送16次检测结果,直到接收成功。重复推送16次后仍未接收成功,则不再推送,建议您检查callback接口的状态。

seed

String

aabbcc123

随机字符串,该值用于回调通知请求中的签名。

由英文字母、数字、下划线(_)组成,不超过64个字符。由您自定义,用于在接收到内容安全的回调通知时校验请求由阿里云内容安全服务发起。

说明

当使用callback时,该字段必须提供。

cryptType
String
SHA256
使用回调通知时(callback),设置对回调通知内容进行加密的算法。内容安全会将返回结果(由用户uid + seed + content拼接的字符串)按照您设置的加密算法加密后,再发送到您的回调通知地址。取值:
  • SHA256(默认):使用SHA256加密算法。
  • SM3:使用国密HMAC-SM3加密算法,返回十六进制的字符串,且字符串由小写字母和数字组成。

    例如,abc经国密SM3加密后返回66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0

tasks

JSONArray

指定检测对象,JSON数组中的每个元素是一个检测任务结构体。最多支持100个元素,即每次提交100条内容进行检测,支持100个元素的前提是需要将并发任务调整到100个以上。关于每个元素的具体结构描述,请参见task

extras

JSONObject

xxx

指定要识别的证件类型,格式为{"card":"${CardType}"}CardType表示证件类型,取值:
  • business-license:营业执照
  • id-card-front:身份证人像面
  • id-card-back:身份证国徽面
  • passport:护照
  • bank-card:银行卡
  • driver-license-front:驾驶证正面
  • driver-license-back:驾驶证反面
  • vehicle-license-front:行驶证正面
  • vehicle-license-back:行驶证反面
  • vehicle-num:车牌
  • vehicle-vin:车辆VIN码
  • household-head:户口簿户主页
  • household-resident:户口簿常住人口页
表 1. task

名称

类型

是否必须

示例值

描述

dataId

String

test_data_xxxx

数据ID。需要保证在一次请求中所有的ID不重复。

url

String

https://www.aliyundoc.com/test_image_xxxx.png

检测对象的URL。

  • 公网HTTP/HTTPS URL,且长度不超过2048个字符。

  • 阿里云OSS提供的文件路径。您需要先授权内容安全访问OSS存储空间,仅限相同区域的OSS空间。更多信息,请参见授权内容安全访问OSS存储空间

    文件路径格式:oss://<bucket-name>.<endpoint>/<object-name>

(异步检测)返回数据

名称

类型

示例值

描述

code

Integer

200

错误码,和HTTP状态码一致。

更多信息,请参见公共错误码

msg

String

OK

请求消息的响应信息。

dataId

String

检测对象对应的数据ID。

说明

如果在检测请求参数中传入了dataId,则此处返回对应的dataId

taskId

String

img5A@k7a@B4q@6K@d9nfKgOs-1s****

检测任务的ID。

url

String

https://www.aliyundoc.com/test_image_xxxx.png

检测对象的URL。

  • 公网HTTP/HTTPS URL,且长度不超过2048个字符。

  • 阿里云OSS提供的文件路径。您需要先授权内容安全访问OSS存储空间,仅限相同区域的OSS空间。更多信息,请参见授权内容安全访问OSS存储空间

    文件路径格式:oss://<bucket-name>.<endpoint>/<object-name>

extras

JSONObject

xxx

额外调用参数,对应检测请求参数中的extras

说明

该参数可能会被调整,目前请勿依赖该参数的返回值。

(异步检测)示例

请求示例

说明

以银行卡识别为例(extras传入{"card": "bank-card"})。如果需要识别其他类型的卡证,传入对应的卡证类型即可,具体请参见(异步检测)请求参数

http(s)://[Endpoint]/green/image/asyncscan
&<公共请求参数>
{
    "scenes": [
        "ocr"
    ],
    "extras": {
        "card": "bank-card"
    },
    "tasks": [
        {
            "dataId": "test_data_xxxx",
            "url": "https://www.aliyundoc.com/test_image_xxxx.png"
        }
    ]
}

正常返回示例

{
    "code": 200,
    "msg": "OK",
    "requestId": "92AD868A-F5D2-4AEA-96D4-E1273B8E074C",
    "data": [
        {
            "code": 200,
            "msg": "OK",
            "dataId": "test_data_xxxx",
            "taskId": "img5A@k7a@B4q@6K@d9nfKgOs-1s****",
            "url": "https://www.aliyundoc.com/test_image_xxxx.png"
        }
    ]
}

(图片异步检测结果查询)使用说明

业务接口:/green/image/results,表示查询图片异步检测结果。

您可以调用该接口查询图片异步检测任务的结果。关于如何构造HTTP请求,请参见请求结构;您也可以直接选用已构造好的HTTP请求,更多信息,请参见SDK概览

  • 计费信息

    该接口不计费。

  • 查询超时

    建议您将查询间隔设置为30秒(即在提交异步检测任务30秒后查询结果),最长不能超出4个小时,否则结果将会丢失。

QPS限制

本接口的单用户QPS限制为10次/秒。超过限制,API调用会被限流,这可能会影响您的业务,请合理调用。

(结果查询)请求参数

名称

类型

是否必须

示例值

描述

body

JSONArray

["img5A@k7a@B4q@6K@d9nfKgOs-1sWeLu"]

要查询的检测任务的taskId列表。数组中的元素个数不超过100个。

您在提交检测任务后,可以从返回数据中获取检测任务的taskId

(结果查询)返回数据

名称

类型

示例值

描述

code

Integer

200

错误码,和HTTP状态码一致。

更多信息,请参见公共错误码

msg

String

OK

请求消息的响应信息。

dataId

String

test_data_xxxx

检测对象对应的数据ID。

说明

如果在检测请求参数中传入了dataId,则此处返回对应的dataId

taskId

String

img5A@k7a@B4q@6K@d9nfKgOs-1s****

检测任务的ID。

url

String

https://www.aliyundoc.com/test_image_xxxx.png

检测对象的URL。

  • 公网HTTP/HTTPS URL,且长度不超过2048个字符。

  • 阿里云OSS提供的文件路径。您需要先授权内容安全访问OSS存储空间,仅限相同区域的OSS空间。更多信息,请参见授权内容安全访问OSS存储空间

    文件路径格式:oss://<bucket-name>.<endpoint>/<object-name>

extras

JSONObject

xxx

额外调用参数,对应检测请求参数中的extras

说明

该参数可能会被调整,目前请勿依赖该参数的返回值。

results

Array

返回结果。调用成功时(code=200),返回结果中包含一个或多个元素。每个元素是个结构体,具体结构描述请参见result

表 2. result

名称

类型

示例值

描述

scene

String

ocr

检测场景,取值:ocr

label

String

ocr

检测结果的分类。取值:

  • normal:图片中未识别出文字信息。

  • ocr:图片中包含文字信息。

suggestion

String

review

建议用户执行的操作,取值:

  • pass:无需关注返回结果。

  • review:关注识别出的文字信息。

rate

Float

99.91

在OCR图文识别场景中,可以不用关注该返回值。

businessLicenseInfo

Object

识别出来的营业执照信息。关于具体结构描述,请参见businssLicenseInfo

说明

只有在异步检测任务的请求参数extras中指定了{"card":"business-license"}才会返回该结果。

idCardInfo

Object

识别出来的身份证信息。关于具体结构描述,请参见idCardInfo

说明

只有在异步检测任务的请求参数extras中指定了{"card":"id-card-front"}{"card":"id-card-back"}才会返回该结果。

passportInfo

Object

识别出来的护照信息。关于具体结构描述,请参见passportInfo

说明

只有在异步检测任务的请求参数extras中指定了{"card":"passport"}才会返回该结果。

bankCardInfo

Object

识别出来的银行卡信息。关于具体结构描述,请参见bankCardInfo

说明

只有在异步检测任务的请求参数extras中指定了{"card":"bank-card"}才会返回该结果。

driverLicenseFrontInfo

Object

识别出来的驾驶证正面信息。关于具体结构描述,请参见driverLicenseFrontInfo

说明

只有在异步检测任务的请求参数extras中指定了{"card":"driver-license-front"}才会返回该结果。

driverLicenseBackInfo

Object

识别出来的驾驶证反面信息。关于具体结构描述,请参见driverLicenseBackInfo

说明

只有在异步检测任务的请求参数extras中指定{"card":"driver-license-back"}才会返回该结果。

vehicleLicenseFrontInfo

Object

识别出来的行驶证正面信息。关于具体结构描述,请参见vehicleLicenseFrontInfo

说明

只有在异步检测任务的请求参数extras中指定了{"card":"vehicle-license-front"}才会返回该结果。

vehicleLicenseBackInfo

Object

识别出来的行驶证反面信息。关于具体结构描述,请参见vehicleLicenseBackInfo

说明

只有在异步检测任务的请求参数extras中指定了{"card":"vehicle-license-back"}才会返回该结果。

vehicleNumInfo

Object

识别出来的车牌信息。关于具体结构描述,请参见vehicleNumInfo

说明

只有在异步检测任务的请求参数extras中指定了{"card":"vehicle-num"}才会返回该结果。

vehicleVinInfo

Object

识别出来的车辆VIN码信息。关于具体结构描述,请参见vehicleVinInfo

说明

只有在异步检测任务的请求参数extras中指定了{"card":"vehicle-vin"}才会返回该结果。

ocrCardInfo

Object

识别出来的其他卡证的OCR信息。关于具体结构描述,请参见ocrCardInfo

说明

只有在异步检测任务的请求参数extras中指定了以下内容,才会返回相应结果:

  • {"card":"household-head"}:返回户口簿户主页信息。

  • {"card":"household-resident"}:返回户口簿常住人口页信息。

表 3. 营业执照信息(businessLicenseInfo)
名称类型示例值描述
companyNameStringxxx技术有限公司公司名称。
companyTypeString有限责任公司公司类型。
legalPersonString张XX企业法人。
establishDateString2000年01月01日注册日期。
vaildPeriodString2030年01月01日营业终止日期。
addressStringxxx地址。
capitalStringxxx注册资本。
businessString计算机软硬件开发经营范围。
copyBooleanfalse是否是副本。取值:
  • true:是
  • false:否
copyIdStringxxx副本号。
certSNStringxxx证照编号。
creditCodeStringxxx统一社会信用代码。
organizationCodeStringxxx组织机构代码。
taxCodeStringxxx税务登记号。
companySNStringxxx公司编号。
compositionStringxxx组成形式。
paidInCapitalStringxxx实收资本。
表 4. 身份证信息(idCardInfo)
名称类型示例值描述
nameString张XX姓名。
nationalityString民族。
numberString5****************9身份证号。
birthString2022-01-01出生日期。格式:YYYY-MM-DD。
addressStringxxx住址。
authorityStringxxx签发机构。
startDateString2022-06-30有效期开始日期。格式:YYYY-MM-DD。
endDateString2032-06-30有效期结束日期。格式:YYYY-MM-DD。
说明 该字段可能返回以下值:长期
angleFloat96.2证件顺时针旋转的角度。
copyBooleanfalse身份证照片是否是复印件。取值:
  • true:是
  • false:否
说明 默认不返回该字段。如果需要返回,请联系商务经理。
remakeBooleanfalse身份证照片是否是翻拍。取值:
  • true:是
  • false:否
说明 默认不返回该字段。如果需要返回,请联系商务经理。
typeStringfront证件类型。取值:
  • front:身份证人像面
  • back:身份证国徽面
  • front_back:正常身份证人像面和国徽面同页
  • interim_front:临时身份证人像面
  • interim_back:临时身份证国徽面
  • interim_front_back:临时身份证人像面和国徽面同页
numberValidBooleantrue证件号码是否合法。取值:
  • true:是
  • false:否
    说明 如果长度不正确或者号码不符合国家规范,会返回false
表 5. 护照信息(passportInfo)
名称类型示例值描述
authorityStringxxx发证机关。
birthDateString2020年01月01日出生日期。
birthDayString01月01日生日。
birthPlaceStringxxx出生地。
birthPlaceRawStringxxx出生地(字母)。
expireDateString2030年01月01日到期时间。
expireDayString01月01日到期日。
issueDateString2022年01月01日发证日期。
issuePlaceStringxxx发证地址。
issuePlaceRawStringxxx发证地址(字母)。
nameString王xx姓名。
cnNameStringxxx中文名称。
cnNameRawStringxxx中文名称(字母)。
personIdString5****************9身份ID。
srcCountryString中国国籍。
typeStringxxx类型。
line0Stringxxx底部第一行。
line1Stringxxx底部第二行。
surnameString姓。
givenNameStringxx名。
表 6. 银行卡信息(bankCardInfo)
名称类型示例值描述
bankCardNumString622576888888****银行卡号。
表 7. 驾驶证正面信息(driverLicenseFrontInfo)
名称类型示例值描述
nameString张XX姓名。
numberString123xxxxxxxxxxxxxxxx驾驶证号。
addressStringxx省xx市xx区xx街道xx号住址。
vehicleTypeStringC1准驾车型。
validStartDateString2022-01-01有效期开始时间,格式:YYYY-MM-DD。
validEndDateString2028-01-01有效期截止时间,格式:YYYY-MM-DD。
表 8. 驾驶证反面信息(driverLicenseBackInfo)
名称类型示例值描述
archiveNumStringxxx档案编号。
表 9. 行驶证正面信息(vehicleLicenseFrontInfo)
名称类型示例值描述
plateNumString陕xxxxxx车牌号。
vehicleTypeString小型普通客车车辆类型。
ownerString张XX所有者名字。
useCharacterString非营运车辆使用性质。
addressStringxx省xx市xx区xx街道xx号住址。
modelString东风日产牌ABCxxxxx车辆品牌。
vinStringABCxxxxxxxx1234车辆识别代号。
engineNumString12xxxxA发动机号码。
registerDateString2022-01-01注册日期,格式:YYYY-MM-DD。
issueDateString2022-01-01发证日期,格式:YYYY-MM-DD。
表 10. 行驶证反面信息(vehicleLicenseBackInfo)
名称类型示例值描述
plateNumString陕Axxxxx车牌号。
fileNumString12345678****档案编号。
appprovedPassengerCapacityIntegerxxx核定载人数。
grossMassStringxxx总质量。
unladenMassStringxxx整备质量。
approvedLoadStringxxx核定载质量。
tractionMassStringxxx准牵引总质量。
inspectionRecordString1检验记录。
overallDimensionObject车辆轮廓尺寸信息。关于具体结构描述,请参见下表overallDimension。
表 11. overallDimension
名称类型示例值描述
lengthInteger4000车辆长度,单位:毫米。
widthInteger2000车辆宽度,单位:毫米。
heightInteger1000车辆高度,单位:毫米。
表 12. 车牌信息(VehicleNumInfo)
名称类型示例值描述
numString陕Axxxxx车牌号。
rateFloat99.01车牌号的置信度,取值范围:0~100。值越高表示识别出的车牌号越可信。
vehicleTypeString小型汽车车牌类型,取值:
  • 小型汽车
  • 新能源车
  • 大型汽车
  • 挂车
  • 教练车
  • 警车
  • 军车
  • 使领馆车
  • 港澳车
vehicleTypeRateFloat99.01车牌类型的置信度,取值范围:0~100。值越高表示识别出的车牌类型越可信。
表 13. 车辆VIN码信息(VehicleVinInfo)
名称类型示例值描述
vinStringABCxxxxxxxx1234VIN号。
ocrCardInfo
  • 表 14. 户口簿户主页信息
    名称类型示例值描述
    locationNumberStringxxx地段号。
    issueDateString2022年01月01日签发日期。
    householdTypeString居民户口户别。
    houseHolderString张XX户主姓名。
    addressString广西xxx住址。
    communityStringxxx户主社区。
    householdNumberStringxxx户号。
    undertakerStringxxx承办人签章。
    typeStringhousehold-head卡证的类型,取值固定为household-head,表示户口簿户主页。
  • 表 15. 户口簿常住人口页信息
    名称类型示例值描述
    occupationString粮农职业。
    migrationDate1String2022年01月01日何时由何地迁来本址。
    idNumberString5****************9身份证编号。
    educationString初中文化程度。
    birthPlaceStringxxx出生地。
    servicePremisesStringxxx服务处所。
    householdNumberStringxxx户号。
    hometownString四川成都籍贯。
    nameString张XX姓名。
    formerNameStringxxx曾用名。
    maritalStatusString未婚婚姻状况。
    nationString汉族民族。
    otherAddressStringxxx本市其他住址。
    birthdayString2020年01月01日出生日期。
    militaryServiceStringxxx兵役状况。
    relationToString户主与户主关系。
    religionStringxxx宗教信仰。
    bloodTypeStringB血型。
    registerDateString2023年02月06日登记日期。
    heightStringxxx身高。
    migrationDate2Stringxxx县xxx乡xxx村xx迁来何时何地迁来本市。
    undertakerStringxxx承办人签章。
    typeStringhousehold-resident卡证的类型,取值固定为household-resident,表示户口簿常住人口页。

(结果查询)示例

请求示例

http(s)://[Endpoint]/green/image/results
&<公共请求参数>
[
    "img5A@k7a@B4q@6K@d9nfKgOs-1s****"
]

正常返回示例

  • 银行卡信息

    {
        "code": 200,
        "data": [
            {
                "code": 200,
                "dataId": "test_data_xxxx",
                "extras": {
    
                },
                "msg": "OK",
                "results": [
                    {
                        "bankCardInfo": {
                            "bankCardNum": "622576888888****"
                        },
                        "label": "ocr",
                        "rate": 99.91,
                        "scene": "ocr",
                        "suggestion": "review"
                    }
                ],
                "taskId": "img5A@k7a@B4q@6K@d9nfKgOs-1s****",
                "url": "https://www.aliyundoc.com/test_image_xxxx.png"
            }
        ],
        "msg": "success",
        "requestId": "1a2faf93-dd41-47d8-95ad-bdf6226540e4"
    }
  • 户口簿户主页信息

    {
        "msg": "OK",
        "code": 200,
        "data": [
            {
                "msg": "OK",
                "code": 200,
                "dataId": "test_data_xxxx",
                "extras": {
    
                },
                "results": [
                    {
                        "rate": 99.91,
                        "suggestion": "review",
                        "label": "ocr",
                        "ocrCardInfo": {
                            "houseHolder": "居民户口",
                            "address": "广西XXXXXX",
                            "type": "household-head",
                            "locationNumber": "",
                            "issueDate": "广西XXX",
                            "community": "",
                            "householdNumber": "",
                            "householdType": "XXX",
                            "undertaker": "汉"
                        },
                        "scene": "ocr"
                    }
                ],
                "taskId": "img5A@k7a@B4q@6K@d9nfKgOs-1s****",
                "url": "https://www.aliyundoc.com/test_image_xxxx.png"
            }
        ],
        "requestId": "6162F805-A6B9-446C-9B7C-5F26CFB03D89"
    }
  • 户口簿常住人口页信息

    {
        "msg": "OK",
        "code": 200,
        "data": [
            {
                "msg": "OK",
                "code": 200,
                "dataId": "test_data_xxxx",
                "extras": {
    
                },
                "results": [
                    {
                        "rate": 99.91,
                        "suggestion": "review",
                        "label": "ocr",
                        "ocrCardInfo": {
                            "birthday": "2020年01月01日",
                            "hometown": "四孔成都",
                            "occupation": "粮农",
                            "education": "初中",
                            "nation": "汉族",
                            "militaryService": "",
                            "relationTo": "户主",
                            "type": "household-resident",
                            "idNumber": "12345620200101****",
                            "bloodType": "",
                            "householdNumber": "",
                            "religion": "",
                            "undertaker": "XXX",
                            "birthPlace": "XX省XX",
                            "migrationDate1": "ivzi.03.zoXXX县XXX乡XXX村XX迁来",
                            "migrationDate2": "",
                            "otherAddress": "",
                            "servicePremises": "",
                            "name": "支小宝",
                            "formerName": "",
                            "maritalStatus": "",
                            "registerDate": "2023年02月06日",
                            "height": ""
                        },
                        "scene": "ocr"
                    }
                ],
                "taskId": "img5A@k7a@B4q@6K@d9nfKgOs-1s****",
                "url": "https://www.aliyundoc.com/test_image_xxxx.png"
            }
        ],
        "requestId": "AE11413F-1AE4-4147-8807-2F7673D67D72"
    }