调用图片同步检测接口实现通用图文OCR-内容安全-阿里云

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

通用图文OCR识别分为普通版本和高精度版本。

普通版本适用于识别影视画面、互联网图片等文字较少的场景。
高精度版本适用于复杂的文档图片识别以及图片中有高密度文字的场景，能够返回单字信息。

说明

通用图文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）。
  说明
  其中，GIF格式的图片，图像总像素不超过4,194,304（px），高度或者宽度不能超过30,000像素（px）。
- 图片下载时间限制为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。
extras	JSONObject	否	{"type":"advanced"}	不传入extras参数表示使用普通版本OCR识别。如果使用高精度OCR识别，需要传入该参数，格式为`{"type":"${ocrType}"}`。`ocrType`取值：`advanced`，表示高精度OCR。

表 1. task
名称	类型	是否必须	示例值	描述
dataId	String	否	test_data_xxxx	数据ID。需要保证在一次请求中所有的ID不重复。
url	String	是	https://aliyundoc.com/test_image_xxxx.png	检测对象的URL。公网HTTP/HTTPS URL，且长度不超过2048个字符。阿里云OSS提供的文件路径。您需要先授权内容安全访问OSS存储空间，仅限相同区域的OSS空间。更多信息，请参见授权内容安全访问OSS存储空间。文件路径格式：oss://<bucket-name>.<endpoint>/<object-name>
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	检测对象的URL。公网HTTP/HTTPS URL，且长度不超过2048个字符。阿里云OSS提供的文件路径。您需要先授权内容安全访问OSS存储空间，仅限相同区域的OSS空间。更多信息，请参见授权内容安全访问OSS存储空间。文件路径格式：oss://<bucket-name>.<endpoint>/<object-name>
extras	JSONObject	{"type":"advanced"}	额外调用参数，对应检测请求参数中的extras。说明该参数可能会被调整，目前请勿依赖该参数的返回值。
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图片）有文字时，返回识别出来的每一帧及对应的文字。说明如果未截取多帧，则不返回该结果。
ocrDetailInfo	Object		高精度全文识别结果的详细文字信息，具体结构描述请参见ocrDetailInfo。说明只有在请求参数extras中传入了`{"type":"advanced"}`才会返回该结果。

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

表 3. ocrDetailInfo
名称	类型	示例值	描述
wordNum	Integer	2	字块数量。
wordsInfo	Object		字块信息。具体结构描述请参见wordsInfo。

表 4. wordsInfo
名称	类型	示例值	描述
charInfo	Array		单字信息。具体结构描述请参见charInfo。
direction	Integer	0	文字方向。取值： 0：横行 1：竖行
pos	Array		坐标信息。具体结构描述请参见pos。
prob	Integer	99	置信度。
word	String	林下漏光	字块包含的文字内容。

表 2. charInfo
名称	类型	示例值	描述
h	Integer	20	文字高度，单位：像素。
prob	Integer	99	置信度。
w	Integer	20	文字宽度，单位：像素。
word	String	林	单字内容。
x	Integer	39	单字在x轴上的坐标，单位：像素。
y	Integer	86	单字在y轴上的坐标，单位：像素。

表 3. pos
名称	类型	示例值	描述
x	Integer	73	当前字块在x轴上的坐标，单位：像素。
y	Integer	113	当前字块在y轴上的坐标，单位：像素。

示例

普通图文OCR

请求示例

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"
}

高精度图文OCR

请求示例

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

正常返回示例

{
    "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": "img5A@k7a@B4q@6K@d9nfKgOs-1s****",
            "url": "https://aliyundoc.com/test_image_xxxx.png"
        }
    ],
    "requestId": "03E6B458-8DDD-4D44-8856-3216E660201E"
}