本文介绍了调用图片异步检测接口(/green/image/asyncscan)进行通用图文OCR识别的方法。通用图文OCR能够识别并返回图片中的文字内容。

通用图文OCR识别分为普通版本和高精度版本。
  • 普通版本适用于识别影视画面、互联网图片等文字较少的场景。
  • 高精度版本适用于复杂的文档图片识别以及图片中有高密度文字的场景,能够返回单字准确率。

图片异步检测接口说明

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

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

  • 计费信息

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

  • 检测超时

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

  • 返回结果

    异步检测任务不会实时返回检测结果,您需要通过callback或者轮询的方式获取检测结果。检测结果最长保留一小时。

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

(异步检测)请求参数

名称 类型 是否必须 描述
bizType 字符串 该字段用于标识您的业务场景。您可以通过内容安全控制台创建业务场景(具体操作,请参见自定义机审标准),或者提交工单联系我们帮助您创建业务场景。
scenes 字符串数组 指定检测场景,取值:ocr
callback 字符串 异步检测结果回调通知您的URL,支持使用HTTP和HTTPS协议的地址。该字段为空时,您必须定时轮询检测结果。
callback接口必须支持POST方法、UTF-8编码的传输数据,以及表单参数checksumcontent。内容安全按照以下规则和格式设置checksumcontent,调用您的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 字符串 随机字符串,该值用于回调通知请求中的签名。

由英文字母、数字、下划线(_)组成,不超过64个字符。由您自定义,用于在接收到内容安全的回调通知时校验请求由阿里云内容安全服务发起。

说明 当使用callback时,该字段必须提供。
tasks JSON数组 指定检测对象,JSON数组中的每个元素是一个OCR图文检测任务结构体。最多支持100个元素,即对100张图片进行识别。每个元素的具体结构描述请参见task
extras JSON结构体 不传入extras参数表示使用普通版本OCR识别。

如果使用高精度OCR识别,需要传入该参数,格式为{"type":"${ocrType}"}ocrType取值:advanced,表示高精度OCR。

表 1. task
名称 类型 是否必须 描述
dataId 字符串 数据ID。需要保证在一次请求中所有的ID不重复。
url 字符串 待检测图片的URL。
interval 整型 截帧频率,GIF图、长图检测专用。
  • GIF图可理解为图片数组,interval参数指定了每隔多少张图片抽取一帧进行检测。只有该值存在时,才会对GIF进行截帧。
  • 长图分为长竖图和长横图。
    • 对长竖图(高大于400像素,高宽比大于2.5),按照(高:宽)取整来计算总图数,并进行切割。
    • 对长横图(宽大于400像素,宽高比大于2.5),按照(宽:高)取整来计算总图数,并进行切割。

默认只会检测GIF图、长图的第一帧,interval参数用于指示后台在检测时可按照该间隔跳着检测,以节省检测成本。

说明 interval需要与maxFrames参数组合使用。例如,设置interval为2,maxFrames为100,在检测GIF图、长图时,将每间隔1帧检测一次,最多检测100帧,计费则按照实际检测的数量计算。
maxFrames 整型 最大截帧数量,GIF图、长图检测专用,默认值为1

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

(异步检测)返回数据

名称 类型 描述
code 整型 错误码,和HTTP状态码一致。
msg 字符串 错误描述信息。
dataId 字符串 检测对象对应的数据ID。
说明 如果在检测请求参数中传入了dataId,则此处返回对应的dataId
taskId 字符串 检测任务的ID。
url 字符串 检测对象的URL。
extras JSON结构体 额外调用参数,对应检测请求参数中的extras
说明 该参数可能会被调整,目前请勿依赖该参数的返回值。

(异步检测)示例

请求示例
{
    "scenes": [
        "ocr"
    ],
    "tasks": [
        {
            "dataId": "test_data_xxxx",
            "url": "https://test_image_xxxx.png"
        }
    ]
}
正常返回示例
{
    "code": 200,
    "msg": "OK",
    "requestId": "92AD868A-F5D2-4AEA-96D4-E1273B8E074C",
    "data": [
        {
            "code": 200,
            "msg": "OK",
            "dataId": "test_data_xxxx",
            "taskId": "aaa25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695",
            "url": "https://test_image_xxxx.png"
        }
    ]
}

图片异步检测结果查询接口说明

业务接口:/green/image/results,表示查询图片异步检测结果。

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

  • 计费信息

    该接口不计费。

  • 查询超时

    建议您将查询间隔设置为30秒(即在提交异步检测任务30秒后查询结果),最长不能超出4个小时,否则结果将会丢失。

(结果查询)请求参数

名称 类型 是否必须 描述
body JSON数组 要查询的异步检测任务的taskId列表。数组中的元素个数不超过100个。

(结果查询)返回数据

名称 类型 描述
code 整型 错误码,和HTTP的status code一致。
msg 字符串 错误描述信息。
dataId 字符串 检测对象对应的数据ID。
说明 如果在检测请求参数中传入了dataId,则此处返回对应的dataId
taskId 字符串 检测任务的ID。
url 字符串 检测对象的URL。
extras JSON结构体 额外调用参数,对应检测请求参数中的extras
说明 该参数可能会被调整,目前请勿依赖该参数的返回值。
results 数组 返回结果。调用成功时(code=200),返回结果中包含一个或多个元素。每个元素是个结构体,具体结构描述请参见result
表 2. result
名称 类型 描述
scene 字符串 检测场景,取值:ocr
label 字符串 检测结果的分类。取值:
  • normal:图片中未识别出文字信息。
  • ocr:图片中包含文字信息。
suggestion 字符串 建议用户执行的操作,取值:
  • pass:无需关注返回结果。
  • review:关注识别出的文字信息。
rate 浮点数 在OCR图文识别场景中,可以不用关注该返回值。
ocrLocations 数组 静态图(非GIF图片)有文字时,返回识别出来的单条文字信息,具体结构描述请参见ocrLocation
ocrData 数组 静态图(非GIF图片)有文字时,返回识别出来的所有文字信息组合。通常文本组合信息存储于数组第一个元素上。
frames 数组 动态图(GIF图片)有文字时,返回识别出来的每一帧及对应的文字。
ocrDetailInfo 结构体 高精度全文识别结果的详细文字信息,具体结构描述请参见ocrDetailInfo
说明 只有在异步检测任务的请求参数extras中传入了{"type":"advanced"}才会返回该结果。
表 3. ocrLocation
名称 类型 描述
text 字符串 识别出来的单条文本信息。
x 浮点数 以图片左上角为坐标原点,文字区域左上角到y轴的距离,单位:像素。
y 浮点数 以图片左上角为坐标原点,文字区域左上角到x轴的距离,单位:像素。
w 浮点数 文字区域的宽度,单位:像素。
h 浮点数 文字区域的高度,单位:像素。
表 4. ocrDetailInfo
名称 类型 描述
wordNum 整型 字块数量。
wordsInfo 结构体 字块信息。具体结构描述请参见wordsInfo
表 5. wordsInfo
名称 类型 描述
charInfo 数组 单字信息。具体结构描述请参见charInfo
direction 整型 文字方向。取值:
  • 0:横行
  • 1:竖行
pos 数组 坐标信息。具体结构描述请参见pos
prob 整型 置信度。
word 字符串 字块包含的文字内容。
表 6. charInfo
名称 类型 描述
h 整型 文字高度,单位:像素。
prob 整型 置信度。
w 整型 文字宽度,单位:像素。
word 字符串 单字内容。
x 整型 单字在x轴上的坐标,单位:像素。
y 整型 单字在y轴上的坐标,单位:像素。
表 7. pos
名称 类型 描述
x 整型 当前字块在x轴上的坐标,单位:像素。
y 整型 当前字块在y轴上的坐标,单位:像素。

(结果查询)示例

请求示例
[
    "aaa25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695"
]
正常返回示例
  • 普通图文OCR
    {
        "code": 200,
        "data": [
            {
                "code": 200,
                "dataId": "test_data_xxxx",
                "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": "aaa25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695",
                "url": "https://test_image_xxxx.png"
            }
        ],
        "msg": "OK",
        "requestId": "992C7849-AA45-4055-8F82-8D44D64C15E3"
    }
  • 高精度图文OCR
    {
         "msg": "OK",
         "code": 200,
         "data": [
              {
                   "msg": "OK",
                   "code": 200,
                   "dataId": "test_data_xxxx",
                   "extras": {
    
                },
                   "results": [
                        {
                             "ocrData": [
                                  "林下漏光 疏疏如残雪 "
                        ],
                             "ocrDetailInfo": {
                                  "wordsInfo": [
                                       {
                                            "prob": 99,
                                            "pos": [
                                                 {
                                                      "x": 37,
                                                      "y": 86
                                        },
                                                 {
                                                      "x": 123,
                                                      "y": 86
                                        },
                                                 {
                                                      "x": 123,
                                                      "y": 109
                                        },
                                                 {
                                                      "x": 37,
                                                      "y": 109
                                        }
                                    ],
                                            "word": "林下漏光",
                                            "charInfo": [
                                                 {
                                                      "prob": 99,
                                                      "w": 20,
                                                      "h": 20,
                                                      "x": 39,
                                                      "y": 86,
                                                      "word": "林"
                                        },
                                                 {
                                                      "prob": 99,
                                                      "w": 5,
                                                      "h": 20,
                                                      "x": 63,
                                                      "y": 86,
                                                      "word": "下"
                                        },
                                                 {
                                                      "prob": 99,
                                                      "w": 17,
                                                      "h": 20,
                                                      "x": 72,
                                                      "y": 86,
                                                      "word": "漏"
                                        },
                                                 {
                                                      "prob": 99,
                                                      "w": 17,
                                                      "h": 20,
                                                      "x": 103,
                                                      "y": 86,
                                                      "word": "光"
                                        }
                                    ],
                                            "direction": 0
                                },
                                       {
                                            "prob": 99,
                                            "pos": [
                                                 {
                                                      "x": 73,
                                                      "y": 113
                                        },
                                                 {
                                                      "x": 174,
                                                      "y": 113
                                        },
                                                 {
                                                      "x": 174,
                                                      "y": 136
                                        },
                                                 {
                                                      "x": 73,
                                                      "y": 136
                                        }
                                    ],
                                            "word": "疏疏如残雪",
                                            "charInfo": [
                                                 {
                                                      "prob": 99,
                                                      "w": 19,
                                                      "h": 20,
                                                      "x": 74,
                                                      "y": 113,
                                                      "word": "疏"
                                        },
                                                 {
                                                      "prob": 99,
                                                      "w": 16,
                                                      "h": 20,
                                                      "x": 97,
                                                      "y": 113,
                                                      "word": "疏"
                                        },
                                                 {
                                                      "prob": 99,
                                                      "w": 13,
                                                      "h": 20,
                                                      "x": 117,
                                                      "y": 113,
                                                      "word": "如"
                                        },
                                                 {
                                                      "prob": 99,
                                                      "w": 16,
                                                      "h": 20,
                                                      "x": 134,
                                                      "y": 113,
                                                      "word": "残"
                                        },
                                                 {
                                                      "prob": 99,
                                                      "w": 16,
                                                      "h": 20,
                                                      "x": 154,
                                                      "y": 113,
                                                      "word": "雪"
                                        }
                                    ],
                                            "direction": 0
                                }
                            ],
                                  "wordNum": 2
                        },
                        "scene": "ocr",
                        "label": "ocr",
                        "suggestion": "review",
                    }
                ],
                   "taskId": "aaa25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695",
                   "url": "https://test_image_xxxx.png"
            }
        ],
         "requestId": "03E6B458-8DDD-4D44-8856-3216E660201E"
    }