本文提供了OCR图片识别异步任务的具体接口和参数说明,旨在帮助您编写程序构建HTTP调用请求。

  • 关于如何构造HTTP请求,请参见请求结构
  • 您也可以直接选用已构造好的HTTP请求,具体请参见SDK参考

提交OCR异步识别任务

描述

业务接口/green/image/asyncscan

提交OCR图文异步识别任务,识别图片中的文字信息。识别结果需要通过调用查询异步识别结果进行查询或者通过callback的方式进行接收,检测结果最多保留1个小时。

异步OCR检测支持非结构化的文字识别和结构化的卡证文字识别。

支持识别的卡证对象包括:营业执照、身份证、护照、银行卡、驾驶证、行驶证、车牌、车辆VIN码、增值税发票、自定义模板OCR
说明 卡证类的识别算法由阿里巴巴计算平台事业部PAI团队提供技术支撑。
说明 该接口为收费接口,具体请参考计费说明。

关于检测时长

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

关于图片的限制
  • 图片链接支持以下协议:HTTP和HTTPS。
  • 图片支持以下格式:PNG、JPG、JPEG、BMP、GIF、WEBP。
  • 图片大小限制为10MB以内。如您有特殊需求(大图片),可以提工单进行调整。
  • 图片下载时间限制为3s内,如果下载时间超过3s,将返回下载超时。
  • 图片像素建议不低于256*256,像素过低可能会影响识别效果。
  • 图片检测接口响应时间依赖图片的下载时间。请保证被检测图片所在的存储服务稳定可靠,建议您使用阿里云OSS存储或者CDN缓存等。

请求参数

关于在请求中必须包含的公共请求参数,请参考公共参数

请求body是一个JSON对象,字段说明如下:
名称 类型 是否必需 描述
bizType 字符串 该字段用于标识业务场景。针对不同的业务场景,您可以配置不同的内容审核策略,以满足不同场景下不同的审核标准或算法策略的需求。您可以通过云盾内容安全控制台创建业务场景(bizType),或者通过工单联系我们帮助您创建业务场景。
scenes 字符串数组 指定检测场景,取值:ocr
callback 字符串 异步检测结果回调通知您的URL,支持HTTP/HTTPS。该字段为空时,您必须定时检索检测结果。
seed 字符串 随机字符串,该值用于回调通知请求中的签名。当使用callback时,该字段必须提供。
tasks JSON数组 指定检测对象,JSON数组中的每个元素是一个OCR图文检测任务结构体(image表)。最多支持100个元素,即对100张图片进行识别。每个元素的具体结构描述见task
extras Map 若使用卡证信息识别服务,需要指定传入的卡证照片类型,格式为{"card":"{OcrCardType[-front/back]}"} 。其中,
  • OcrCardType代表证件类型,取值包括:
    • business-license:营业执照
    • id-card:身份证(正反面)
    • passport:护照
    • bank-card:银行卡
    • driver-license:驾驶证(正反面)
    • vehicle-license:行驶证(正反面)
    • vehicle-num:车牌
    • vehicle-vin:车辆VIN码
    • invoice:增值税发票
  • [-front/back]指定证件照片的正反面。需要指定正面反面的证件包括:身份证(id-card)、驾驶证(driver-license)、行驶证(vehicle-license)。其余证件类型不用指定正反面。
例如,身份证信息识别的extra取值为{"card":"id-card-front}{"card":"id-card-back},其中id-card-front表示身份证正面,id-card-back表示身份证反面;银行卡信息识别的extra取值为{"card":"bank-card"}

使用自定义模板OCR的extras格式为: {"card":"template","templateId":"xxx"}。其中,templateId 填写内容安全控制台上创建的模板ID。具体请参考自定义模板OCR

表 1. task
名称 类型 是否必需 描述
dataId 字符串 数据Id。需要保证在一次请求中所有的Id不重复。
url 字符串 待检测图像的URL。
interval 整型 截帧频率,GIF图/长图检测专用。GIF图可理解为图片数组,每interval张图片抽取一张进行检测。只有该值存在时,才会对GIF进行截帧。长图同时支持长竖图和长横图。
  • 对长竖图(高大于400像素,高宽比大于2.5),会按照(高:宽)取整来计算总图数,并进行切割。
  • 对长横图(宽大于400像素,宽高比大于2.5),会按照(宽:高)取整来计算总图数,并进行切割。
说明 默认只会检测GIF图/长图的第一帧,interval参数用于指示后台在检测时可按照该间隔跳着检测,以节省检测成本。需要与maxFrames参数组合使用。例如,设置interval为2,maxFrames为100,检测长图/GIF图时,将每间隔1帧检测一次,最多检测100帧,计费则按照实际检测的数量计算。
maxFrames 整型 最大截帧数量,GIF图/长图检测专用,默认值为1

interval*maxFrames小于该图片所包含的图片数量时,截帧间隔会自动修改为该图片所包含的图片数/maxFrames,以提高整体检测效果。

结果回调通知参数(callback、seed)

使用说明

如果您在请求参数中指定了回调通知参数callback、被回调callback值,即一个http(s)协议接口的URL,则需要支持POST方法,传输数据编码采用utf-8,并且支持两个表单参数checksumcontent。系统将按以下描述的生成规则和格式设置checksum和content的值,调用您的callback接口返回检测内容。

您服务端接收到我们推送的结果后,返回的HTTP状态码为200时,表示推送成功,其他的HTTP状态码均视为您接收失败,我们将最多重复推送16次。

回调结果参数的生成规则
名称 类型 描述
checksum String 用户uid + seed + content拼成字符串,通过SHA256算法生产。用户UID即账号ID,您可在阿里云控制台上查询。为防篡改,您可以在获取到推送结果时,按此算法生成字符串,与checksum做一次校验。
content String JSON字符串格式,请自行解析反转成JSON对象。content结果格式参见下文。
content结果格式
{
   "code": 200 ,
   "data": [
    {
       "code": 200 ,
       "dataId": "964719bf-30b1-4180-ba22-09e56d530bfb" ,
       "extras": {},
       "msg": "OK" ,
       "results": [
        {
           "bankCardInfo": {
             "bankCardNum": "6225768888888888" 
          },
           "label": "ocr" ,
           "rate": 99.91 ,
           "scene": "ocr" ,
           "suggestion": "review"
        }
      ],
       "taskId": "imguVUiCvA4NZ5jeaGJCS9IG-1pfBHc" ,
       "url":  "https://aip.bdstatic.com/portal/dist/1531393832694/ai_images/technology/ocr-cards/bankcard/demo-card-1.png" 
    }
  ],
   "msg": "success" ,
   "requestId": "1a2faf93-dd41-47d8-95ad-bdf6226540e4" 
}

返回参数

返回结果说明,参见返回结果

返回body中的data字段是JSON数组,每一个元素包含如下字段:
名称 类型 是否必需 描述
code 整型 错误码,和HTTP的status code一致。
msg 字符串 错误描述信息。
dataId 字符串 对应请求中的dataId
taskId 字符串 该检测任务的ID。
url 字符串 对应请求中的URL。

示例

请求示例
{
  "scenes": ["ocr"],
  "tasks": [
    {
      "dataId": "test4lNSMdggA0c56MMvfY1234-abcdpx",
      "url": "https://img.alicdn.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
    }
  ]
}
返回示例
{
  "code": 200, 
  "msg": "OK", 
  "requestId": "92AD868A-F5D2-4AEA-96D4-E1273B8E074C",
  "data": [
    {
      "code": 200, 
      "msg": "OK", 
      "dataId": " test4lNSMdggA0c56MMvfY1234-abcdpx ", 
      "taskId": "aaa25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695",
      "url": "https://img.alicdn.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
    }
  ]
}

查询异步识别结果

描述

业务接口/green/image/results

查询OCR图片异步识别结果。建议您将查询间隔设置为30秒,最长不能超出1个小时,否则结果将会丢失。关于调用异步OCR图文识别,参考提交OCR异步识别任务
说明 该接口为免费接口。

请求参数

关于在请求中必须包含的公共请求参数,请参考公共参数

请求body是一个JSON数组,字段说明如下:
名称 类型 是否必需 描述
body JSON数组 要查询的taskId列表。最大长度不超过1,000。

返回参数

返回结果说明,参见返回结果

返回body中的Data字段是JSON数组,每一个元素包含如下字段:
名称 类型 是否必需 描述
code 整型 错误码,和HTTP的status code一致。
msg 字符串 错误描述信息。
dataId 字符串 对应的请求中的dataId
taskId 字符串 该检测任务的ID。
url 字符串 对应的请求中的URL。
extras Map 额外调用参数。
说明 该参数可能会被调整,目前请勿依赖该参数的返回值。
results 数组 返回结果。调用成功时(code=200),返回结果中包含一个或多个元素。每个元素是个结构体,具体结构描述见result
表 2. result
名称 类型 是否必需 描述
scene 字符串 检测场景,取值为:ocr
label 字符串 检测结果的分类。取值为:
  • normal:正常图片,未检测到文字
  • ocr:含文字的图片
suggestion 字符串 建议用户执行的操作,取值范围:
  • pass:未识别出目标对象(如文字)
  • review:识别出目标对象(如文字)
rate 浮点数 在OCR图文识别场景中,可以无需参考该返回值。
ocrLocations 数组 静态图(非GIF图片)有文字时,返回识别出来的单条文字信息,具体结构描述见ocrLocation
ocrData 数组 静态图(非GIF图片)有文字时,返回识别出来的所有文字信息组合。通常文本组合信息存储于数组第一个元素上。
frames 数组 动态图(GIF图片)有文字时,返回识别出来的每一帧及对应的文字。
businessLicenseInfo 结构体 识别出来的营业执照信息,具体结构描述见businessLicenseInfo
说明 仅适用于卡证信息识别ocr场景,且在extras中指定{"card":"business-license"}
idCardInfo 结构体 识别出来的身份证信息,具体结构描述见idCardInfo
说明 仅适用于卡证信息识别ocr场景,且在extras中指定{"card":"id-card-front"}{"card":"id-card-back"}
passportInfo 结构体 识别出来的护照信息,具体结构描述见passportInfo
说明 仅适用于卡证信息识别ocr场景,且在extras中指定{"card":"passport"}
bankCardInfo 结构体 识别出来的银行卡信息,具体结构描述见bankCardInfo
说明 仅适用于卡证信息识别ocr场景,且在extras中指定{"card":"bank-card"}
driverLicenseFrontInfo 结构体 识别出来的驾驶证正面信息,具体结构描述见driverLicenseFrontInfo
说明 仅适用于卡证信息识别ocr场景,且在extras中指定{"card":"driver-license-front"}
driverLicenseBackInfo 结构体 识别出来的驾驶证反面信息,具体结构描述见driverLicenseBackInfo
说明 仅适用于卡证信息识别ocr场景,且在extras中指定{"card":"driver-license-back"}
vehicleLicenseFrontInfo 结构体 识别出来的行驶证正面信息,具体结构描述见vehicleLicenseFrontInfo
说明 仅适用于卡证信息识别ocr场景,且在extras中指定{"card":"vehicle-license-front"}
vehicleLicenseBackInfo 结构体 识别出来的行驶证反面信息,具体结构描述见vehicleLicenseBackInfo
说明 仅适用于卡证信息识别ocr场景,且在extras中指定{"card":"vehicle-license-back"}
vehicleNumInfo 结构体 识别出来的车牌信息,具体结构描述见vehicleNumInfo
说明 仅适用于卡证信息识别ocr场景,且在extras中指定{"card":"vehicle-num"}
vehicleVinInfo 结构体 识别出来的车辆VIN码信息,具体结构描述见vehicleVinInfo
说明 仅适用于卡证信息识别ocr场景,且在extras中指定{"card":"vehicle-vin"}
invoiceInfo 结构体 识别出来的增值税发票信息,具体结构描述见invoiceInfo
说明 仅适用于卡证信息识别ocr场景,且在extras中指定{"card":"invoice"}
customizeOcrInfo 结构体 识别出来的自定义模板OCR信息,具体结构描述见customizeOcrInfo
说明 仅适用于自定义模板OCR场景,且在extras中指定 {"card":"template"}
表 3. ocrLocation
名称 类型 是否必需 描述
text 字符串 识别出来的单条文本信息。
x 浮点数 以图片左上角为坐标原点,文字区域左上角到y轴距离。
y 浮点数 以图片左上角为坐标原点,文字区域左上角到x轴距离。
w 浮点数 文字区域的宽度。
h 浮点数 文字区域的高度。
表 4. businessLicenseInfo
名称 类型 是否必需 描述
regNum 字符串 注册号。
companyName 字符串 公司名称。
companyType 字符串 公司类型。
legalPerson 字符串 企业法人。
establishDate 字符串 注册日期。
vaildPeriod 字符串 营业终止日期。
address 字符串 地址。
capital 字符串 注册资本。
business 字符串 经营范围。
copy 布尔型 是否为副本。
copyId 字符串 副本号。
certSN 字符串 证照编号。
creditCode 字符串 统一社会信用代码。
organizationCode 字符串 组织机构代码。
taxCode 字符串 税务登记号。
companySN 字符串 公司编号。
composition 字符串 组成形式。
paidInCapital 字符串 实收资本。
表 5. idCardInfo
名称 类型 是否必需 描述
name 字符串 姓名。
sex 字符串 性别。取值:
nationality 字符串 民族。
number 字符串 身份证号。
birth 字符串 出生年月。格式为:yyyy-MM-dd
address 字符串 籍贯。
authority 字符串 签发机构。
startDate 字符串 有效期开始日期。格式为:yyyy-MM-dd
endDate 字符串 有效期结束日期。格式为:yyyy-MM-dd
说明 该字段可能返回“长期”。
angle 浮点数 证件顺时针旋转的角度。
copy 布尔型 身份证照片是否是复印件。
remake 布尔型 身份证照片是否是翻拍。
type 字符串 证件类型。取值:
  • front:身份证正面(人像面)
  • back:身份证背面(国徽面)
  • front_back:正常身份证正反同页
  • interim_front:临时身份证正面(人像面)
  • interim_back:临时身份证背面(国徽面)
  • interim_front_back:临时身份证正反同页
表 6. passportInfo
名称 类型 是否必需 描述
authority 字符串 发证机关。
birthDate 字符串 出生日期。
birthDay 字符串 生日。
birthPlace 字符串 出生地。
birthPlaceRaw 字符串 出生地(字母)。
expireDate 字符串 到期时间。
expireDay 字符串 到期日。
issueDate 字符串 发证日期。
issuePlace 字符串 发证地址。
issuePlaceRaw 字符串 发证地址(字母)。
name 字符串 姓名。
cnName 字符串 中文名称。
cnNameRaw 字符串 中文名称(字母)。
personId 字符串 身份Id。
sex 字符串 性别。
srcCountry 字符串 国籍。
type 字符串 类型。
line0 字符串 底部第一行。
line1 字符串 底部第二行。
表 7. bankCardInfo
名称 类型 是否必需 描述
bankCardNum 字符串 银行卡号。
表 8. driverLicenseFrontInfo
名称 类型 是否必需 描述
name 字符串 姓名。
number 字符串 驾驶证号。
sex 字符串 性别(男/女)。
address 字符串 住址。
vehicleType 字符串 准驾车型。
validStartDate 字符串 有效期开始时间,格式为:yyyy-MM-dd。
validEndDate 字符串 有效期截止时间,格式为:yyyy-MM-dd。
表 9. driverLicenseBackInfo
名称 类型 是否必需 描述
archiveNum 字符串 档案编号。
表 10. vehicleLicenseFrontInfo
名称 类型 是否必需 描述
plateNum 字符串 车牌号。
vehicleType 字符串 车辆类型。
owner 字符串 所有者名字。
useCharacter 字符串 车辆使用性质。
address 字符串 住址。
model 字符串 车辆品牌。
vin 字符串 车辆识别代号。
engineNum 字符串 发动机号码。
registerDate 字符串 注册日期,格式为:yyyy-MM-dd。
issueDate 字符串 发证日期,格式为:yyyy-MM-dd。
表 11. vehicleLicenseBackInfo
名称 类型 是否必需 描述
plateNum 字符串 车牌号。
fileNum 字符串 档案编号。
appprovedPassengerCapacity 整型 核定载人数。
grossMass 字符串 总质量。
unladenMass 字符串 整备质量。
approvedLoad 字符串 核定载质量。
tractionMass 字符串 准牵引总质量。
inspectionRecord 字符串 检验记录。
overallDimension 结构体 车辆轮廓尺寸(单位mm),具体结构描述见overallDimension
表 12. overallDimension
名称 类型 是否必需 描述
length 整型 车辆长度。
width 整型 车辆宽度。
height 整型 车辆高度。
表 13. VehicleNumInfo
名称 类型 是否必需 描述
num 字符串 车牌号。
rate 浮点数 车牌号的置信度,取值0-100。值越高表示识别出的车牌号越可信。
vehicleType 字符串 车牌类型,取值:
  • 小型汽车
  • 新能源车
  • 大型汽车
  • 挂车
  • 教练车
  • 警车
  • 军车
  • 使领馆车
  • 港澳车
vehicleTypeRate 浮点数 车牌类型的置信度,取值0-100。值越高表示识别出的车牌类型越可信。
表 14. VehicleVinInfo
名称 类型 是否必需 描述
vin 字符串 VIN号。
表 15. invoiceInfo
名称 类型 是否必需 描述
invoice_name 字符串 发票名称。
invoice_id 整型 发票代码。
invoice_number 整型 发票号码。
invoice_date 整型 开票日期。
invoice_bcompany 字符串 购买方名称。
invoice_bcode 字符串 购买方纳税人识别号。
invoice_baddress 字符串 购买方地址、电话。
invoice_baccount 字符串 购买方开户行及账号。
invoice_password 字符串 发票密码。
invoice_detail 数组 发票明细。具体结构描述见invoice_detail
invoice_totalamount 浮点型 合计金额。
invoice_totaltax 浮点型 合计税额。
invoice_totalamountupper 字符串 价税合计(大写)。
invoice_totalamountlower 字符串 价税合计(小写)。
invoice_scompany 字符串 销售方名称。
invoice_scode 字符串 销售方纳税人识别号。
invoice_saddress 字符串 销售方地址、电话。
invoice_saccount 字符串 销售方开户行及账号。
invoice_remark 字符串 备注。
invoice_payee 字符串 收款人。
invoice_reviewer 字符串 复核。
invoice_drawer 字符串 开票人。
表 16. invoice_detail
名称 类型 是否必需 描述
detail_name 字符串 货物或应税劳务、服务名称。
detail_type 字符串 规格型号。
detail_unit 字符串 单位。
detail_count 浮点型 数量。
detail_unitprice 浮点型 单价。
detail_amount 浮点型 金额。
detail_rate 字符串 税率。
detail_tax 浮点型 税额。
表 17. customizeOcrInfo
名称 类型 是否必需 描述
ocrInfo 数组 数组中每个结构体是一个识别出来的key:value字段。

示例

请求示例
{
  ["aaa25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695"]
}
返回示例
{
   "code":   200 ,
   "data":  [
    {
       "code":   200 ,
       "dataId":   "675876e4-6698-4f92-8bd9-19f5e20035fb" ,
       "extras":  {},
       "msg":   "OK" ,
       "results":  [
        {
           "label":   "ocr" ,
           "ocrData":  [
             "本文提供了调用图片异步检测任务的具体内容,"
          ],
           "ocrLocations":  [
            {
               "h":   19 ,
               "text":   "本文提供了调用图片异步检测任务的具体内容," ,
               "w":   362 ,
               "x":   31 ,
               "y":   11 
            }
          ],
           "rate":   99.91 ,
           "scene":   "ocr" ,
           "suggestion":   "review" 
        }
      ],
       "taskId":   "img7Iljku7br7u66Z29EsepH9-1pfBUQ" ,
       "url":   "http://green-system.oss-cn-hangzhou.aliyuncs.com/green_demo_image/2018-08-02/1533193802331_123.jpg?Expires=1533280202&OSSAccessKeyId=xxxxxxxxx&Signature=xxxxxxxxxx" 
    }
  ],
   "msg":   "OK" ,
   "requestId":   "992C7849-AA45-4055-8F82-8D44D64C15E3" 
}