調用/green/image/asyncscan識別通用圖文OCR - Content Moderation

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

（圖片非同步檢測）使用說明

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

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

計費資訊：
該介面為收費介面。關於計費方式，請參見Alibaba Content Security Service產品定價。
檢測逾時：
同步檢測允許的最長檢測時間是6秒，如果檢測在該時間限制內沒有完成，系統會強制返回逾時錯誤碼。如果您對即時性要求不高，可以選擇非同步檢測，其他情況下請選擇同步檢測，同步檢測介面的調用相對簡單些。對於同步檢測介面的調用，建議您將逾時時間設定為6秒。
返回結果：
非同步檢測任務不會即時返回檢測結果，您需要通過callback或者輪詢的方式擷取檢測結果。檢測結果最長保留一小時。
- callback擷取檢測結果：提交非同步檢測任務時，在請求參數中傳入callback參數，用來自動接收檢測結果，具體請參見（非同步檢測）請求參數。
- 輪詢擷取檢測結果：提交非同步檢測任務時，無需傳入callback參數；提交非同步檢測任務後，調用結果查詢介面擷取檢測結果，具體請參見（圖片非同步檢測結果查詢）使用說明。
圖片要求：
- 圖片連結支援以下協議：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。
callback	String	否	http://www.aliyundoc.com/xx.json	檢測結果回調通知您的URL，支援使用HTTP和HTTPS協議的地址。該欄位為空白時，您必須定時輪詢檢測結果。 callback介面必須支援POST方法、UTF-8編碼的傳輸資料，以及表單參數checksum和content。Alibaba Content Security Service按照以下規則和格式設定checksum和content，調用您的callback介面返回檢測結果。 checksum：字串格式，由`使用者uid + seed + content`拼成字串，通過SHA256演算法產生。使用者UID即阿里雲帳號ID，可以在阿里雲控制台查詢。為防篡改，您可以在擷取到推送結果時，按上述演算法產生字串，與checksum做一次校正。說明使用者UID必須是阿里雲帳號的UID，而不是RAM使用者的UID。 content：JSON字串格式，請自行解析反轉成JSON對象。關於content結果的樣本，請參見查詢檢測結果的返回樣本。說明您的服務端callback介面收到Alibaba Content Security Service推送的結果後，如果返回的HTTP狀態代碼為200，則表示接收成功，其他的HTTP狀態代碼均視為接收失敗。接收失敗時，Alibaba Content Security Service將最多重複推送16次檢測結果，直到接收成功。重複推送16次後仍未接收成功，則不再推送，建議您檢查callback介面的狀態。
seed	String	否	aabbcc123	隨機字串，該值用於回調通知請求中的簽名。由英文字母、數字、底線（_）組成，不超過64個字元。由您自訂，用於在接收到Alibaba Content Security Service的回調通知時校正請求由阿里雲Alibaba Content Security Service服務發起。說明當使用callback時，該欄位必須提供。
cryptType	String	否	SHA256	使用回調通知時（callback），設定對回調通知內容進行加密的演算法。Alibaba Content Security Service會將返回結果（由`使用者uid + seed + content`拼接的字串）按照您設定的密碼編譯演算法加密後，再發送到您的回調通知地址。取值： SHA256（預設）：使用SHA256密碼編譯演算法。 SM3：使用國密HMAC-SM3密碼編譯演算法，返回十六進位的字串，且字串由小寫字母和數字組成。例如，abc經國密SM3加密後返回66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0。
tasks	JSONArray	是		指定檢測對象，JSON數組中的每個元素是一個檢測任務結構體。最多支援100個元素，即每次提交100條內容進行檢測，支援100個元素的前提是需要將並發任務調整到100個以上。關於每個元素的具體結構描述，請參見task。

表 1. task
名稱	類型	是否必須	樣本值	描述
dataId	String	否	test_data_xxxx	資料ID。需要保證在一次請求中所有的ID不重複。
url	String	是	https://www.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狀態代碼一致。更多資訊，請參見公用錯誤碼。
msg	String	OK	請求資訊的響應訊息。
dataId	String	test_data_xxxx	檢測對象對應的資料ID。說明如果在檢測請求參數中傳入了dataId，則此處返回對應的dataId。
taskId	String	aaa25f95-4892-4d6b-aca9-7939bc6e9baa-148619876****	檢測任務的ID。
url	String	https://www.aliyundoc.com/test_image_xxxx.png	公網HTTP/HTTPS URL，且長度不超過2048個字元。
extras	JSONObject	xxx	額外調用參數，對應檢測請求參數中的extras。說明該參數可能會被調整，目前請勿依賴該參數的傳回值。

（非同步檢測）樣本

請求樣本

http(s)://[Endpoint]/green/image/asyncscan
&<公用請求參數>
{
    "scenes": [
        "ocr"
    ],
    "tasks": [
        {
            "dataId": "test_data_xxxx",
            "url": "https://www.aliyundoc.com/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-148619876****",
            "url": "https://www.aliyundoc.com/test_image_xxxx.png"
        }
    ]
}

（圖片非同步檢測結果查詢）使用說明

業務介面：/green/image/results，表示查詢圖片非同步檢測結果。

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

計費資訊：
該介面不計費。
查詢逾時：
建議您將查詢間隔設定為30秒（即在提交非同步檢測任務30秒後查詢結果），最長不能超出4個小時，否則結果將會丟失。

QPS限制

本介面的單使用者QPS限制為10次/秒。超過限制，API調用會被限流，這可能會影響您的業務，請合理調用。

（結果查詢）請求參數

名稱	類型	是否必須	樣本值	描述
body	JSONArray	是	["aaa25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695"]	要查詢的檢測任務的taskId列表。數組中的元素個數不超過100個。您在提交檢測任務後，可以從返回資料中擷取檢測任務的taskId。

（結果查詢）返回資料

名稱	類型	樣本值	描述
code	Integer	200	錯誤碼，和HTTP狀態代碼一致。更多資訊，請參見公用錯誤碼。
msg	String	OK	請求資訊的響應訊息。
dataId	String	test_data_xxxx	檢測對象對應的資料ID。說明如果在檢測請求參數中傳入了dataId，則此處返回對應的dataId。
taskId	String	aaa25f95-4892-4d6b-aca9-7939bc6e9baa-148619876****	檢測任務的ID。
url	String	https://www.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	本文提供了調用圖片非同步檢測任務的具體內容，	靜態圖（非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/results
&<公用請求參數>
[
    "aaa25f95-4892-4d6b-aca9-7939bc6e9baa-148619876****"
]

正常返回樣本

{
    "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-148619876****",
            "url": "https://www.aliyundoc.com/test_image_xxxx.png"
        }
    ],
    "msg": "OK",
    "requestId": "992C7849-AA45-4055-8F82-8D44D64C15E3"
}