本文介绍了调用图片同步检测接口(/green/image/scan)进行自定义模板OCR识别的方法。自定义模板OCR能够满足您自定义识别图片中的特定字段的需求,通过创建OCR模板,您可以定制需要识别的文字并以key-value的形式返回。

前提条件

您已经通过内容安全控制台创建了自定义模板。更多信息,请参见自定义OCR模板

接口说明

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

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

  • 计费信息

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

  • 检测超时

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

  • 返回结果

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

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

请求参数

名称 类型 是否必选 描述
bizType String 该字段用于标识您的业务场景。您可以通过内容安全控制台创建业务场景(具体操作,请参见自定义机审标准),或者提交工单联系我们帮助您创建业务场景。
scenes StringArray 指定检测场景,唯一取值:ocr
tasks JSONArray 指定检测对象,JSON数组中的每个元素是一个检测任务结构体。最多支持100个元素,即每次提交100条内容进行检测,支持100个元素的前提是需要将并发任务调整到100个以上。关于每个元素的具体结构描述,请参见task
extras JSONObject 指定要应用的OCR模板,格式为{"card":"template","templateId":"xxx"}templateId填写您在内容安全控制台创建的模板ID。关于自定义OCR模板的说明,请参见自定义OCR模板
表 1. task
名称 类型 是否必选 描述
dataId String 检测对象对应的数据ID。

由大小写英文字母、数字、下划线(_)、短划线(-)、英文句号(.)组成,不超过128个字符,可以用于唯一标识您的业务数据。

url String 待检测图片的URL。

返回数据

名称 类型 描述
code Integer 错误码,和HTTP状态码一致。

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

msg String 请求信息的响应信息。
dataId String 检测对象对应的数据ID。
说明 如果在检测请求参数中传入了dataId,则此处返回对应的dataId
taskId String 检测任务的ID。
url String 检测对象的URL。
extras JSONObject 额外调用参数,对应检测请求参数中的extras
说明 该参数可能会被调整,目前请勿依赖该参数的返回值。
results JSONArray 返回结果。调用成功时(code=200),返回结果中包含一个或多个元素,每个元素是个结构体。关于结构体的描述,请参见result
表 2. result
名称 类型 描述
scene String 检测场景,唯一取值:ocr
label String 检测结果的分类,取值:
  • normal:图片中未识别出文字信息。
  • ocr:图片中包含文字信息。
suggestion String 建议用户执行的操作,取值:
  • pass:无需关注返回结果。
  • review:关注识别出的文字信息。
rate Float 在OCR图文识别场景中,可以不用关注该返回值。
customizeOcrInfo JSONArray 识别出来的自定义模板OCR信息,请参见customizeOcrInfo
说明 只有在请求参数extras中指定了{"card":"template"}才会返回该结果。
表 3. customizeOcrInfo
名称 类型 描述
ocrInfo Array 数组中每个结构体是一个识别出来的key:value字段。

示例

请求示例
{
    "scenes": [
        "ocr"
    ],
    "extras": {
        "card": "template",
        "templateId": "xxx"
    },
    "tasks": [
        {
            "dataId": "test_data_xxxx",
            "url": "https://test_image_xxxx.png"
        }
    ]
}
正常返回示例
{
    "msg": "OK",
    "code": 200,
    "data": [
        {
            "msg": "OK",
            "code": 200,
            "dataId": "test_data_xxxx",
            "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://test_image_xxxx.png"
        }
    ],
    "requestId": "8ADA8439-4AD7-49BE-8496-2D57F7FB0387"
}