This topic describes the /green/image/scan operation that you can call to submit optical character recognition (OCR) tasks and obtain OCR results in real time. You can submit the OCR tasks to detect and obtain text in images.

Description

Operation: /green/image/scan

You can call this operation to submit synchronous OCR tasks. For more information about how to construct an HTTP request, see Request structure. You can also select an existing HTTP request. For more information, see SDK overview.

  • Billing method:

    You are charged for calling this operation. For more information about the billing method, see Content Moderation Pricing.

  • Response time:

    The maximum response time that is allowed for a synchronous moderation request is 6s. If the moderation is not complete within 6s, a timeout error is returned. If you do not need to obtain moderation results in real time, you can send asynchronous moderation requests. In other cases, we recommend that you send synchronous moderation requests because synchronous moderation operations are easier to call. We recommend that you set the timeout period to 6s for calling synchronous moderation operations.

  • Return results:

    In general, moderation results are returned within 1s after you send a synchronous moderation request. The time may increase in special scenarios where a large number of requests are to be processed in the system, the size of images is large, or the images contain a large number of words. The speed of OCR is inversely proportional to the number of words in images. If the images to be moderated contain a large number of words, we recommend that you send asynchronous moderation requests.

  • Limits on images:
    • The images must use HTTP or HTTPS URLs.
    • The images must be in the PNG, JPG, JPEG, BMP, GIF, or WEBP format.
    • An image can be up to 10 MB in size. This rule is applicable to both synchronous and asynchronous moderation operations. If you have special requirements, for example, you want to moderate images larger than 10 MB in size, submit a ticket to raise the threshold.
    • The duration for downloading an image is limited to 3s. If an image fails to be downloaded within 3s, a timeout error is returned.
    • We recommend that you submit images of at least 256 × 256 pixels to ensure the moderation effects.
    • The response time of an operation for moderating images depends on the duration for downloading these images. Make sure that you use a stable and reliable storage service to store the images to be moderated. We recommend that you use Alibaba Cloud Object Storage Service (OSS) or Content Delivery Network (CDN).

Request parameters

Parameter Type Required Description
bizType String No The business scenario. You can create a business scenario in the Alibaba Cloud Content Moderation console. For more information, see Customize policies for machine-assisted moderation. Alternatively, you can submit a ticket to ask Alibaba Cloud engineers to help you create a business scenario.
scenes String array Yes The moderation scenario. Set the value to ocr.
tasks JSON array Yes The list of OCR tasks. Each element in the JSON array is an OCR task structure, namely, each element corresponds to an image. The JSON array can contain a maximum of 10 elements, namely, you can submit a maximum of 10 images at a time. For more information about the structure of each element, see task.
Table 1. task
Parameter Type Required Description
dataId String No The ID of the image to be moderated. Make sure that each ID is unique in a request.
url String Yes The URL of the image to be moderated.
interval Integer No The interval between two frames that are consecutively captured. This parameter is dedicated for GIF or long image moderation.
  • A GIF image can be regarded as an array of frames. One frame is captured for moderation from every n frames. The n is specified by the interval parameter. The system captures frames from GIF images only when this parameter is specified.
  • Long images can be in portrait or horizontal mode.
    • For a long portrait image, of which the height is greater than 400 pixels and the ratio of height to width is greater than 2.5, you can divide the height by the width and round up the result to the nearest integer as the total number of frames.
    • For a long horizontal image, of which the width is greater than 400 pixels and the ratio of width to height is greater than 2.5, you can divide the width by the height and round up the result to the nearest integer as the total number of frames.

By default, only the first frame of a GIF image or a long image is moderated. Instead of having all the frames moderated, you can use the interval parameter to specify the interval between two frames that the system consecutively captures. This helps reduce moderation costs.

Note The interval and maxFrames parameters must be used in pairs. Assume that the interval parameter is set to 2 and the maxFrames parameter is set to 100 for moderating a GIF image or a long image. In this case, one out of every two frames is moderated and a maximum of 100 frames are moderated. The fee is calculated based on the actual number of moderated frames.
maxFrames Integer No The maximum number of frames to be captured. This parameter is dedicated for GIF or long image moderation. Default value: 1.

If the value of the interval parameter multiplied by that of the maxFrames parameter is smaller than the total number of frames in a GIF image or a long image, the interval for capturing frames is automatically changed to the integer rounded up from the result of dividing the total number of frames in the image by the value of the maxFrames parameter. This helps improve the overall moderation effects.

Response parameters

Parameter Type Description
code Integer The HTTP status code returned for the OCR task.
msg String The message returned for the OCR task.
dataId String The ID of the moderation object.
Note If you specify the dataId parameter in the moderation request, the dataId parameter is returned in the response.
taskId String The ID of the OCR task.
url String The URL of the moderated image.
results Array The return results of the OCR task. If HTTP status code 200 is returned after a successful call, the array in the return results contains one or more elements. Each element is a structure. For more information about the structure of each element, see result.
Table 2. result
Parameter Type Description
scene String The moderation scenario. The value is fixed to ocr.
label String The category of the OCR results. Valid values:
  • normal: The image does not contain text.
  • ocr: The image contains text.
suggestion String The machine-assisted moderation result of the moderated image. Valid values:
  • pass: The image does not require further actions.
  • review: The image requires human review.
rate Floating point The probability that the moderated image falls into the detected category. You can ignore this parameter in the OCR scenario.
ocrLocations Array The information about the single text entry in the moderated static image, which includes the text, text size, and text location. For more information about the structure, see ocrLocation.
ocrData Array The combination of all text in the moderated static image. In general, the text combination is stored as the first element of the array.
frames Array The frames that are captured from the moderated GIF image and the text that is detected in each frame.
Table 3. ocrLocation
Parameter Type Description
text String The single text entry that is detected in the moderated image.
x Floating point The distance between the upper-left corner of the text area and the y-axis, with the upper-left corner of the image being the coordinate origin. Unit: pixels.
y Floating point The distance between the upper-left corner of the text area and the x-axis, with the upper-left corner of the image being the coordinate origin. Unit: pixels.
w Floating point The width of the text area. Unit: pixels.
h Floating point The height of the text area. Unit: pixels.

Examples

Sample requests
{
    "scenes": [
        "ocr"
    ],
    "tasks": [
        {
            "dataId": "test_data_xxxx",
            "url": "https://test_image_xxxx.png"
        }
    ]
}
Sample success responses
{
    "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-1sWeLu",
            "url": "https://test_image_xxxx.png"
        }
    ],
    "msg": "OK",
    "requestId": "C4AB08A9-AD75-4410-859B-0B9EF6DFC3C4"
}