本文介绍了调用图片同步检测接口(/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。
    • 图片大小限制为20 MB以内(适用于同步和异步调用),高度或者宽度不能超过30,000像素(px),且图像总像素不超过2.5亿px
    • 图片下载时间限制为3秒内,如果下载时间超过3秒,返回下载超时。
    • 图片像素建议不低于256*256,像素过低可能会影响识别效果。
    • 图片检测接口的响应时间依赖图片的下载时间。请保证被检测图片所在的存储服务稳定可靠,建议您使用阿里云OSS存储或者CDN缓存等。

请求参数

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

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

url String https://test_image_xxxx.png 待检测图片的URL。

返回数据

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

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

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