调用/green/image/asyncscan识别结构化卡证OCR-AI 安全护栏(AI Guardrails)-阿里云帮助中心

本文介绍了调用图片异步检测接口识别结构化卡证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编码的传输数据，以及表单参数checksum和content。内容安全按照以下规则和格式设置checksum和content，调用您的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）
名称	类型	示例值	描述
companyName	String	xxx技术有限公司	公司名称。
companyType	String	有限责任公司	公司类型。
legalPerson	String	张XX	企业法人。
establishDate	String	2000年01月01日	注册日期。
vaildPeriod	String	2030年01月01日	营业终止日期。
address	String	xxx	地址。
capital	String	xxx	注册资本。
business	String	计算机软硬件开发	经营范围。
copy	Boolean	false	是否是副本。取值： true：是 false：否
copyId	String	xxx	副本号。
certSN	String	xxx	证照编号。
creditCode	String	xxx	统一社会信用代码。
organizationCode	String	xxx	组织机构代码。
taxCode	String	xxx	税务登记号。
companySN	String	xxx	公司编号。
composition	String	xxx	组成形式。
paidInCapital	String	xxx	实收资本。

表 4. 身份证信息（idCardInfo）
名称	类型	示例值	描述
name	String	张XX	姓名。
nationality	String	汉	民族。
number	String	5****************9	身份证号。
birth	String	2022-01-01	出生日期。格式：YYYY-MM-DD。
address	String	xxx	住址。
authority	String	xxx	签发机构。
startDate	String	2022-06-30	有效期开始日期。格式：YYYY-MM-DD。
endDate	String	2032-06-30	有效期结束日期。格式：YYYY-MM-DD。说明该字段可能返回以下值：长期。
angle	Float	96.2	证件顺时针旋转的角度。
copy	Boolean	false	身份证照片是否是复印件。取值： true：是 false：否说明默认不返回该字段。如果需要返回，请联系商务经理。
remake	Boolean	false	身份证照片是否是翻拍。取值： true：是 false：否说明默认不返回该字段。如果需要返回，请联系商务经理。
type	String	front	证件类型。取值： front：身份证人像面 back：身份证国徽面 front_back：正常身份证人像面和国徽面同页 interim_front：临时身份证人像面 interim_back：临时身份证国徽面 interim_front_back：临时身份证人像面和国徽面同页
numberValid	Boolean	true	证件号码是否合法。取值： true：是 false：否说明如果长度不正确或者号码不符合国家规范，会返回false。

表 5. 护照信息（passportInfo）
名称	类型	示例值	描述
authority	String	xxx	发证机关。
birthDate	String	2020年01月01日	出生日期。
birthDay	String	01月01日	生日。
birthPlace	String	xxx	出生地。
birthPlaceRaw	String	xxx	出生地（字母）。
expireDate	String	2030年01月01日	到期时间。
expireDay	String	01月01日	到期日。
issueDate	String	2022年01月01日	发证日期。
issuePlace	String	xxx	发证地址。
issuePlaceRaw	String	xxx	发证地址（字母）。
name	String	王xx	姓名。
cnName	String	xxx	中文名称。
cnNameRaw	String	xxx	中文名称（字母）。
personId	String	5****************9	身份ID。
srcCountry	String	中国	国籍。
type	String	xxx	类型。
line0	String	xxx	底部第一行。
line1	String	xxx	底部第二行。
surname	String	王	姓。
givenName	String	xx	名。

表 6. 银行卡信息（bankCardInfo）
名称	类型	示例值	描述
bankCardNum	String	622576888888****	银行卡号。

表 7. 驾驶证正面信息（driverLicenseFrontInfo）
名称	类型	示例值	描述
name	String	张XX	姓名。
number	String	123xxxxxxxxxxxxxxxx	驾驶证号。
address	String	xx省xx市xx区xx街道xx号	住址。
vehicleType	String	C1	准驾车型。
validStartDate	String	2022-01-01	有效期开始时间，格式：YYYY-MM-DD。
validEndDate	String	2028-01-01	有效期截止时间，格式：YYYY-MM-DD。

表 8. 驾驶证反面信息（driverLicenseBackInfo）
名称	类型	示例值	描述
archiveNum	String	xxx	档案编号。

表 9. 行驶证正面信息（vehicleLicenseFrontInfo）
名称	类型	示例值	描述
plateNum	String	陕xxxxxx	车牌号。
vehicleType	String	小型普通客车	车辆类型。
owner	String	张XX	所有者名字。
useCharacter	String	非营运	车辆使用性质。
address	String	xx省xx市xx区xx街道xx号	住址。
model	String	东风日产牌ABCxxxxx	车辆品牌。
vin	String	ABCxxxxxxxx1234	车辆识别代号。
engineNum	String	12xxxxA	发动机号码。
registerDate	String	2022-01-01	注册日期，格式：YYYY-MM-DD。
issueDate	String	2022-01-01	发证日期，格式：YYYY-MM-DD。

表 10. 行驶证反面信息（vehicleLicenseBackInfo）
名称	类型	示例值	描述
plateNum	String	陕Axxxxx	车牌号。
fileNum	String	12345678****	档案编号。
appprovedPassengerCapacity	Integer	xxx	核定载人数。
grossMass	String	xxx	总质量。
unladenMass	String	xxx	整备质量。
approvedLoad	String	xxx	核定载质量。
tractionMass	String	xxx	准牵引总质量。
inspectionRecord	String	1	检验记录。
overallDimension	Object		车辆轮廓尺寸信息。关于具体结构描述，请参见下表overallDimension。

表 11. overallDimension
名称	类型	示例值	描述
length	Integer	4000	车辆长度，单位：毫米。
width	Integer	2000	车辆宽度，单位：毫米。
height	Integer	1000	车辆高度，单位：毫米。

表 12. 车牌信息（VehicleNumInfo）
名称	类型	示例值	描述
num	String	陕Axxxxx	车牌号。
rate	Float	99.01	车牌号的置信度，取值范围：0~100。值越高表示识别出的车牌号越可信。
vehicleType	String	小型汽车	车牌类型，取值：小型汽车新能源车大型汽车挂车教练车警车军车使领馆车港澳车
vehicleTypeRate	Float	99.01	车牌类型的置信度，取值范围：0~100。值越高表示识别出的车牌类型越可信。

表 13. 车辆VIN码信息（VehicleVinInfo）
名称	类型	示例值	描述
vin	String	ABCxxxxxxxx1234	VIN号。

ocrCardInfo

表 14. 户口簿户主页信息
名称	类型	示例值	描述
locationNumber	String	xxx	地段号。
issueDate	String	2022年01月01日	签发日期。
householdType	String	居民户口	户别。
houseHolder	String	张XX	户主姓名。
address	String	广西xxx	住址。
community	String	xxx	户主社区。
householdNumber	String	xxx	户号。
undertaker	String	xxx	承办人签章。
type	String	household-head	卡证的类型，取值固定为household-head，表示户口簿户主页。

表 15. 户口簿常住人口页信息
名称	类型	示例值	描述
occupation	String	粮农	职业。
migrationDate1	String	2022年01月01日	何时由何地迁来本址。
idNumber	String	5****************9	身份证编号。
education	String	初中	文化程度。
birthPlace	String	xxx	出生地。
servicePremises	String	xxx	服务处所。
householdNumber	String	xxx	户号。
hometown	String	四川成都	籍贯。
name	String	张XX	姓名。
formerName	String	xxx	曾用名。
maritalStatus	String	未婚	婚姻状况。
nation	String	汉族	民族。
otherAddress	String	xxx	本市其他住址。
birthday	String	2020年01月01日	出生日期。
militaryService	String	xxx	兵役状况。
relationTo	String	户主	与户主关系。
religion	String	xxx	宗教信仰。
bloodType	String	B	血型。
registerDate	String	2023年02月06日	登记日期。
height	String	xxx	身高。
migrationDate2	String	xxx县xxx乡xxx村xx迁来	何时何地迁来本市。
undertaker	String	xxx	承办人签章。
type	String	household-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"
}