本文提供了提交OCR图文同步检测任务的具体接口及参数说明,帮助您编写程序构建HTTP调用请求。

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

描述

业务接口:/green/image/scan

说明 该接口为收费接口,具体计费方式请参见内容安全产品定价

通过提交OCR图文同步识别任务,识别图片中的文字或卡证信息,并同步返回识别的结果。OCR图文识别支持图片中非结构化的文字识别和结构化的卡证文字识别。支持识别的卡证对象包括:营业执照、身份证、护照、银行卡、驾驶证、行驶证、车牌、车辆VIN码、增值税发票、自定义模板OCR。

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

同步检测请求一般会在一秒内返回结果,但在一些特殊场景(例如系统繁忙导致堆积严重、图片较大、含有OCR内容较多等),耗时可能会增加。OCR的处理速度依赖图片中文字的字数,字数越多处理时间越长。如果您检测的场景中文字较多,推荐您使用OCR图文异步检测接口,具体请参见异步检测

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

请求参数

名称 类型 是否必须 描述
bizType 字符串 该字段用于标识业务场景。针对不同的业务场景,您可以配置不同的内容审核策略,以满足不同场景下不同的审核标准或算法策略的需求。您可以通过云盾内容安全控制台创建业务场景(bizType),或者通过工单联系我们帮助您创建业务场景。
scenes 字符串数组 指定检测场景,取值:ocr
tasks JSON数组 指定检测对象,JSON数组中的每个元素是一个OCR图文检测任务结构体(image表)。最多支持10个元素,即对10张图片进行识别。每个元素的具体结构描述请参见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,以提高整体检测效果。

返回参数

名称 类型 是否必须 描述
code 整型 错误码,和HTTP的status code一致。
msg 字符串 错误描述信息。
dataId 字符串 对应请求中的dataId
taskId 字符串 该检测任务的ID。
url 字符串 对应请求中的URL。
extras map 对应请求中的extras,即上传的卡证图片类型。
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字段。

示例

请求示例
  • 银行卡识别
    {
        "scenes": [
            "ocr"
        ],
        "extras": {
            "card": "bank-card"
        },
        "tasks": [
            {
                "dataId": "test2abcdmO$tAON6qYUrtCRgLo-1234di",
                "url": "https://img.alicdn.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
            }
        ]
    }
  • 增值税发票识别
    {
        "scenes": [
            "ocr"
        ],
        "extras": {
            "card": "invoice"
        },
        "tasks": [
            {
                "dataId": "test2abcdmO$tAON6qYUrtCRgLo-1234di",
                "url": "http://green-system.oss-cn-hangzhou.aliyuncs.com/green_demo_image/2018-11-23/1542940516238_vatinvoice.png?Expires=1543026916&OSSAccessKeyId=xxxxxxx&Signature=xxxxxxxx"
            }
        ]
    }
  • 自定义模板OCR识别
    {
        "scenes": [
            "ocr"
        ],
        "extras": {
            "card": "template",
            "templateId": "xxx"
        },
        "tasks": [
            {
                "dataId": "test2abcdmO$tAON6qYUrtCRgLo-1234di",
                "url": "http://green-system.oss-cn-hangzhou.com/xxx.jpg"
            }
        ]
    }
返回示例
  • 银行卡识别
    {
        "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"
    }
  • 增值税发票识别
    {
        "msg":"OK",
        "code":200,
        "data":[
            {
                "msg":"OK",
                "code":200,
                "dataId":"test3faX7kc7bIy6TU$enTW0nt-1pPFFA",
                "extras":{
                    "md5":"303f7159179153a94033724ffd28ea44"
                },
                "results":[
                    {
                        "invoiceInfo":{
                            "invoice_bcompany":"****软件有限公司",
                            "invoice_baccount":"**银行某支行****",
                            "invoice_drawer":"张某某",
                            "invoice_totalamountupper":"肆仟玖佰肆拾圆整",
                            "invoice_name":"**增值税专用发票",
                            "invoice_date":"20170422",
                            "invoice_totaltax":"717.78",
                            "invoice_reviewer":"",
                            "invoice_totalamountlower":"4940.00",
                            "invoice_id":"1100151234",
                            "invoice_number":"57951234",
                            "invoice_scompany":"****有限责任公司",
                            "invoice_saccount":"****支行1105011012340000****",
                            "invoice_saddress":"****",
                            "invoice_remark":"KP12****",
                            "invoice_totalamount":"4222.22",
                            "invoice_password":"1<000+0000-0000>79*27<>7295<-123020-8>07+63*683-80+>314-9+0+/<0-<-/1++35*958*6>98709/+9323858+8745<724615252",
                            "invoice_payee":"",
                            "invoice_detail":[
                                {
                                    "detail_amount":"888.89",
                                    "detail_name":"荣莉龙芽花茶",
                                    "detail_rate":"17%",
                                    "detail_count":"20",
                                    "detail_type":"",
                                    "detail_unitprice":"44.4444444",
                                    "detail_tax":"151.11",
                                    "detail_unit":""
                                },
                                {
                                    "detail_amount":"3333.33",
                                    "detail_name":"大佛龙井绿茶",
                                    "detail_rate":"17%",
                                    "detail_count":"50",
                                    "detail_type":"",
                                    "detail_unitprice":"66.6666667",
                                    "detail_tax":"566.67",
                                    "detail_unit":""
                                }
                            ],
                            "invoice_baddress":"****",
                            "invoice_bcode":"91330000000000****",
                            "invoice_scode":"91110000000000****"
                        },
                        "rate":99.91,
                        "suggestion":"review",
                        "label":"ocr",
                        "scene":"ocr"
                    }
                ],
                "taskId":"img1CVBf$Vgrno7wF75H5LaRm-1pPFFA",
                "url":"http://green-system.oss-cn-hangzhou.aliyuncs.com/green_demo_image/2018-11-21/1542797345830_vatinvoice.png?Expires=1542883746&OSSAccessKeyId=xxxxxx&Signature=xxxxxxxxx"
            }
        ],
        "requestId":"81121B0B-2BFE-44BA-9825-C15CA5E99551"
    }
  • 自定义模板OCR识别
    {
        "msg": "OK",
        "code": 200,
        "data": [
            {
                "msg": "OK",
                "code": 200,
                "dataId": "test7uIF8NzkbjX7hlOuVX7o8i-1qia8z",
                "extras": {
    
                },
                "results": [
                    {
                        "rate": 99.91,
                        "suggestion": "review",
                        "customizeOcrInfo": {
                            "ocrInfo": [
                                {
                                    "生日": "1981.08.03"
                                },
                                {
                                    "有效期": "2012.12.12-2022.12.11"
                                }
                            ]
                        },
                        "label": "ocr",
                        "scene": "ocr"
                    }
                ],
                "taskId": "imgCjxO0DeXTC7phcds6yrEm-1qia8A",
                "url": "http://green-system.oss-cn-hangzhou.aliyuncs.com/xxx.jpg"
            }
        ],
        "requestId": "8ADA8439-4AD7-49BE-8496-2D57F7FB0387"
    }