调用图片同步检测接口识别通用图文OCR - 内容安全

本文介绍了调用图片同步检测接口识别通用图文OCR的方法。通用图文OCR能够识别并返回图片中的文字内容。

使用说明

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

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

计费信息：
该接口为收费接口。关于计费方式，请参见内容安全产品定价。
检测超时：
同步检测允许的最长检测时间是6秒，如果检测在该时间限制内没有完成，系统会强制返回超时错误码。如果您对实时性要求不高，可以选择异步检测，其他情况下请选择同步检测，同步检测接口的调用相对简单些。对于同步检测接口的调用，建议您将超时时间设置为6秒。
返回结果：
同步检测请求一般会在一秒内返回结果，但在一些特殊场景（例如系统繁忙导致堆积严重、图片较大、含有OCR内容较多等），耗时可能会增加。OCR的处理速度依赖图片中文字的字数，字数越多处理时间越长。如果您检测的场景中文字较多，推荐您使用图片异步检测接口。
图片要求：
- 图片链接支持以下协议：HTTP和HTTPS。
- 图片支持以下格式：PNG、JPG、JPEG、BMP、GIF、WEBP。
- 图片大小限制为20 MB以内（适用于同步和异步调用）。
- 图片下载时间限制为3秒内，如果下载时间超过3秒，返回下载超时。
- 图片像素建议不低于256*256（px），像素过低可能会影响识别效果。
- 图片检测接口的响应时间依赖图片的下载时间。请保证被检测图片所在的存储服务稳定可靠，建议您使用阿里云OSS存储或者CDN缓存等。

QPS限制

本接口的单用户QPS限制为10次/秒。超过限制，API调用会被限流，这可能会影响您的业务，请合理调用。

请求参数

名称	类型	是否必须	示例值	描述
bizType	String	否	default	该字段用于标识您的业务场景。您可以通过内容安全控制台创建业务场景（具体操作，请参见自定义机审标准）。
scenes	StringArray	是	["ocr"]	指定检测场景，取值：ocr。
tasks	JSONArray	是		指定检测对象，JSON数组中的每个元素是一个检测任务结构体。最多支持100个元素，即每次提交100条内容进行检测，支持100个元素的前提是需要将并发任务调整到100个以上。关于每个元素的具体结构描述，请参见task。

表 1. task
名称	类型	是否必须	示例值	描述
dataId	String	否	test_data_xxxx	数据ID。需要保证在一次请求中所有的ID不重复。
url	String	是	https://aliyundoc.com/test_image_xxxx.png	公网HTTP/HTTPS URL，且长度不超过2048个字符。
interval	Integer	否	2	截帧频率，GIF图、长图检测专用。 GIF图可理解为图片数组，interval参数指定了每隔多少张图片抽取一帧进行检测。只有该值存在时，才会对GIF进行截帧。长图分为长竖图和长横图。对长竖图（高大于400像素（px），高宽比大于2.5），按照（高：宽）取整来计算总图数，并进行切割。对长横图（宽大于400像素（px），宽高比大于2.5），按照（宽：高）取整来计算总图数，并进行切割。默认只会检测GIF图、长图的第一帧，interval参数用于指示后台在检测时可按照该间隔跳着检测，以节省检测成本。说明 interval需要与maxFrames参数组合使用。例如，设置interval为2，maxFrames为100，在检测GIF图、长图时，将每间隔1帧检测一次，最多检测100帧，计费则按照实际检测的数量计算。
maxFrames	Integer	否	100	最大截帧数量，GIF图、长图检测专用，默认值为1。当`interval*maxFrames`小于GIF图、长图所包含的图片帧数量时，截帧间隔自动修改为`GIF图、长图所包含的图片帧数/maxFrames`，以提高整体检测效果。

返回数据

名称	类型	示例值	描述
code	Integer	200	错误码，和HTTP的status code一致。
msg	String	OK	请求信息的响应消息。
dataId	String	test_data_xxxx	检测对象对应的数据ID。说明如果在检测请求参数中传入了dataId，则此处返回对应的dataId。
taskId	String	img5A@k7a@B4q@6K@d9nfKgOs-1s****	检测任务的ID。
url	String	https://aliyundoc.com/test_image_xxxx.png	公网HTTP/HTTPS URL，且长度不超过2048个字符。
results	Array		返回结果。调用成功时（code=200），返回结果中包含一个或多个元素。每个元素是个结构体，具体结构描述请参见result。

表 2. result
名称	类型	示例值	描述
scene	String	ocr	检测场景，取值：ocr。
label	String	ocr	检测结果的分类。取值： normal：图片中未识别出文字信息。 ocr：图片中包含文字信息。
suggestion	String	review	建议用户执行的操作，取值： pass：无需关注返回结果。 review：关注识别出的文字信息。
rate	Float	99.91	在OCR图文识别场景中，可以不用关注该返回值。
ocrLocations	Array		静态图（非GIF图片）有文字时，返回识别出来的单条文字信息。具体结构描述请参见ocrLocation。说明如果未识别到文字，则不返回该结果。
ocrData	Array	["hello, this is a test text."]	静态图（非GIF图片）有文字时，返回识别出来的所有文字信息组合。通常文本组合信息存储于数组第一个元素上。说明如果未识别到文字，则不返回该结果。
frames	Array	xxx	动态图（GIF图片）有文字时，返回识别出来的每一帧及对应的文字。说明如果未截取多帧，则不返回该结果。

表 1. ocrLocation
名称	类型	示例值	描述
text	String	hello	识别出来的单条文本信息。
x	Float	41	以图片左上角为坐标原点，文字区域左上角到y轴的距离，单位：像素。
y	Float	84	以图片左上角为坐标原点，文字区域左上角到x轴的距离，单位：像素。
w	Float	83	文字区域的宽度，单位：像素。
h	Float	26	文字区域的高度，单位：像素。

示例

请求示例

http(s)://[Endpoint]/green/image/scan
&<公共请求参数>
{
    "scenes": [
        "ocr"
    ],
    "tasks": [
        {
            "dataId": "test_data_xxxx",
            "url": "https://aliyundoc.com/test_image_xxxx.png"
        }
    ]
}

正常返回示例

{
    "code": 200,
    "data": [
        {
            "code": 200,
            "dataId": "test_data_xxxx",
            "extras": {

            },
            "msg": "OK",
            "results": [
                {
                    "label": "ocr",
                    "ocrData": [
                        "hello, this is a test text."
                    ],
                    "ocrLocations": [
                        {
                            "h": 26,
                            "text": "hello",
                            "w": 83,
                            "x": 41,
                            "y": 84
                        },
                        {
                            "h": 25,
                            "text": " this is a test text.",
                            "w": 95,
                            "x": 78,
                            "y": 114
                        }
                    ],
                    "rate": 99.91,
                    "scene": "ocr",
                    "suggestion": "review"
                }
            ],
            "taskId": "img5A@k7a@B4q@6K@d9nfKgOs-1s****",
            "url": "https://aliyundoc.com/test_image_xxxx.png"
        }
    ],
    "msg": "OK",
    "requestId": "C4AB08A9-AD75-4410-859B-0B9EF6DFC3C4"
}