調用圖片同步檢測介面識別通用圖文OCR - Content Moderation

本文介紹了調用圖片同步檢測介面識別通用圖文OCR的方法。通用圖文OCR能夠識別並返回圖片中的文字內容。

使用說明

業務介面：/green/image/scan，表示圖片同步檢測。

您可以調用該介面建立圖片同步檢測任務。關於如何構造HTTP請求，請參見請求結構；您也可以直接選用已構造好的HTTP請求，更多資訊，請參見SDK概覽。

計費資訊：
該介面為收費介面。關於計費方式，請參見Alibaba Content Security Service產品定價。
檢測逾時：
同步檢測允許的最長檢測時間是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	該欄位用於標識您的業務情境。您可以通過Alibaba Content Security Service控制台建立業務情境（具體操作，請參見自訂機審標準）。
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"
}