本文介紹了調用圖片同步檢測接口識別自定義模板OCR的方法。自定義模板OCR能夠滿足您自定義識別圖片中的特定字段的需求，通過創建OCR模板，您可以定制需要識別的文字并以key-value的形式返回。

使用說明

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

您可以調用該接口創建圖片同步檢測任務。關于如何構造HTTP請求，請參見請求結構；您也可以直接選用已構造好的HTTP請求，更多信息，請參見SDK概覽。

您已經通過內容安全控制臺創建了自定義模板。更多信息，請參見自定義OCR模板。

  • 計費信息：

    該接口為收費接口。關于計費方式，請參見內容安全產品定價。

  • 檢測超時：

    同步檢測允許的最長檢測時間是6秒，如果檢測在該時間限制內沒有完成，系統會強制返回超時錯誤碼。如果您對實時性要求不高，可以選擇異步檢測，其他情況下請選擇同步檢測，同步檢測接口的調用相對簡單些。對于同步檢測接口的調用，建議您將超時時間設置為6秒。

  • 返回結果：

    同步檢測請求一般會在一秒內返回結果，但在一些特殊場景（例如系統繁忙導致堆積嚴重、圖片較大、含有OCR內容較多等），耗時可能會增加。OCR的處理速度依賴圖片中文字的字數，字數越多處理時間越長。如果您檢測的場景中文字較多，推薦您使用圖片異步檢測接口。

  • 圖片要求：
    • 圖片鏈接支持以下協議：HTTP和HTTPS。
    • 圖片支持以下格式：PNG、JPG、JPEG、BMP、GIF、WEBP。
    • 圖片大小限制為20 MB以內（適用于同步和異步調用），高度或者寬度不能超過30,000像素（px），且圖像總像素不超過2.5億（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 是 {"card":"template","templateId":"xxx"} 指定要應用的OCR模板，格式為{"card":"template","templateId":"xxx"}。templateId填寫您在內容安全控制臺創建的模板ID。關于自定義OCR模板的說明，請參見自定義OCR模板。
表 1. task
名稱 類型 是否必選 示例值 描述
dataId String 否 est_data_xxxx 檢測對象對應的數據ID。

由大小寫英文字母、數字、下劃線（_）、短劃線（-）、英文句號（.）組成，不超過128個字符，可以用于唯一標識您的業務數據。
url String 是 https://aliyundoc.com/test_image_xxxx.png 待檢測圖片的URL。

返回數據

名稱 類型 示例值 描述
code Integer 200 錯誤碼，和HTTP狀態碼一致。

更多信息，請參見公共錯誤碼。

msg String OK 請求信息的響應信息。
dataId String test_data_xxxx 檢測對象對應的數據ID。
說明 如果在檢測請求參數中傳入了dataId，則此處返回對應的dataId。
taskId String imgCjxO0DeXTC7phcds6yrEm-1q**** 檢測任務的ID。
url String http://aliyundoc.com/test_image_xxxx.png 檢測對象的URL。
extras JSONObject XXX 額外調用參數，對應檢測請求參數中的extras。
說明 該參數可能會被調整，目前請勿依賴該參數的返回值。
results JSONArray 返回結果。調用成功時（code=200），返回結果中包含一個或多個元素，每個元素是個結構體。關于結構體的描述，請參見result。
表 2. result
名稱 類型 示例值 描述
scene String ocr 檢測場景，唯一取值：ocr。
label String ocr 檢測結果的分類，取值：
  • normal：圖片中未識別出文字信息。
  • ocr：圖片中包含文字信息。
suggestion String review 建議用戶執行的操作，取值：
  • pass：無需關注返回結果。
  • review：關注識別出的文字信息。
rate Float 99.91 在OCR圖文識別場景中，可以不用關注該返回值。
customizeOcrInfo JSONArray 識別出來的自定義模板OCR信息，請參見customizeOcrInfo。
說明 只有在請求參數extras中指定了{"card":"template"}才會返回該結果。
表 3. customizeOcrInfo
名稱 類型 示例值 描述
ocrInfo Array [{"生日":"1981.08.03"},{"有效期":"2012.12.12-2022.12.11"}] 數組中每個結構體是一個識別出來的key：value字段。

示例

請求示例
http(s)://[Endpoint]/green/image/scan
&<公共請求參數>
{
    "scenes": [
        "ocr"
    ],
    "extras": {
        "card": "template",
        "templateId": "xxx"
    },
    "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": [
                {
                    "rate": 99.91,
                    "suggestion": "review",
                    "customizeOcrInfo": {
                        "ocrInfo": [
                            {
                                "生日": "1981.08.03"
                            },
                            {
                                "有效期": "2012.12.12-2022.12.11"
                            }
                        ]
                    },
                    "label": "ocr",
                    "scene": "ocr"
                }
            ],
            "taskId": "imgCjxO0DeXTC7phcds6yrEm-1q****",
            "url": "http://aliyundoc.com/test_image_xxxx.png"
        }
    ],
    "requestId": "8ADA8439-4AD7-49BE-8496-2D57F7FB0387"
}