Submits asynchronous optical character recognition (OCR) tasks and queries asynchronous OCR results. You can call this operation to submit OCR tasks to detect and obtain text in images.

Description

Operation: /green/image/asyncscan

You can call this operation to submit asynchronous 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:

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

  • Response timeout:

    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 most 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:

    If you send asynchronous moderation requests, the moderation results are not returned in real time. To obtain moderation results, you can poll the moderation results at regular intervals or enable callback notification. The moderation results are retained for up to 1 hour.

    • Enable callback notification to obtain OCR results: When you submit asynchronous OCR tasks, you can specify a callback URL for receiving OCR results in the callback parameter of the OCR request. For more information about the callback parameter, see Request parameters.
    • Poll OCR results at regular intervals: You do not need to set the callback parameter when you submit asynchronous OCR tasks. After you submit the tasks, you can call the result query operation to query OCR results. For more information about the operation, see Description about the /green/image/results operation.
  • 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 20 MB in size. The limit for the image size is applicable to both synchronous and asynchronous moderation operations.
    • 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 varies based 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 Object Storage Service (OSS) or Content Delivery Network (CDN).

QPS limit

You can send up to 10 requests per second to call this operation by using your Alibaba Cloud account. If you send an excessive number of requests, throttling is implemented, and your business may be affected.

Request parameters

Parameter Type Required Example Description
bizType String No default The business scenario. You can create a business scenario in the Content Moderation console. For more information, see Customize policies for machine-assisted moderation.
scenes StringArray Yes ["ocr"] The moderation scenario. Set the value to ocr.
callback String No http://www.aliyundoc.com/xx.json The callback URL for notifying you of asynchronous moderation results. HTTP and HTTPS URLs are supported. If you do not set this parameter, you must poll moderation results at regular intervals.
If you set the callback parameter in the moderation request, make sure that the specified HTTP or HTTPS URL meets the following requirements: supports the POST method, uses UTF-8 to encode the transmitted data, and supports the checksum and content parameters. To send moderation results to the specified callback URL, Content Moderation returns the checksum and content parameters in callback notifications based on the following rules and format:
  • checksum: the string in the UID + Seed + Content format that is generated by the Secure Hash Algorithm 256 (SHA-256) algorithm. UID indicates the ID of your Alibaba Cloud account. You can query the ID in the Alibaba Cloud Management Console. To prevent data tampering, you can use the SHA-256 algorithm to generate a string when your server receives a callback notification and verify the string against the received checksum parameter.
    Note UID must be the ID of an Alibaba Cloud account, but not the ID of a RAM user.
  • content: the JSON-formatted string to be parsed to the callback data in the JSON format. For more information about the format of the content parameter, see the sample success responses of each operation that you can call to query asynchronous moderation results.
Note If your server receives a callback notification, the server sends HTTP status code 200 to Content Moderation. If your server fails to receive a callback notification, the server sends other HTTP status codes to Content Moderation. If your server fails to receive a callback notification, Content Moderation continues to push the callback notification until your server receives it. Content Moderation can push a callback notification repeatedly for up to 16 times. After 16 times, Content Moderation stops pushing the callback notification. In this case, we recommend that you check the status of the callback URL.
seed String No aabbcc123 A random string that is used to generate a signature for the callback notification request.

The string can be up to 64 characters in length and can contain letters, digits, and underscores (_). You can customize this string. It is used to verify the callback notification request when Content Moderation pushes callback notifications to your server.

Note This parameter is required if you set the callback parameter.
cryptType String No SHA256 The encryption algorithm used to encrypt the callback content when you enable callback notification. Content Moderation encrypts the returned string based on the encryption algorithm that you specify and then sends the encrypted string to the callback URL. The returned string is in the UID + Seed + Content format. Valid values:
  • SHA256: The HMAC-SHA256 encryption algorithm is used. This is the default value.
  • SM3: The HMAC-SM3 encryption algorithm is used, and a hexadecimal string is returned. The string consists of lowercase letters and digits.

    For example, 66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0 is returned after you encrypt abc by using the HMAC-SM3 encryption algorithm.

tasks JSONArray Yes The list of moderation objects. The JSON array can contain one or more elements. Each element is a structure. The JSON array can contain up to 100 elements. In other words, you can submit up to 100 moderation objects at a time. To submit 100 moderation objects at a time, you must raise the relevant concurrency limit to a number greater than 100. For more information about the structure of each element, see task.
Table 1. task
Parameter Type Required Example Description
dataId String No test_data_xxxx The data ID. Make sure that each ID is unique in a request.
url String Yes https://www.aliyundoc.com/test_image_xxxx.png The URL of the image to be moderated.
interval Integer No 2 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.
    • To moderate a long portrait image, in 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.
    • To moderate a long horizontal image, in 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. 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. For example, 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 example, 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 100 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 Example Description
code Integer 200 The returned HTTP status code.

For more information, see Common HTTP status codes.

msg String OK The message that is returned for the request.
dataId String test_data_xxxx The ID of the moderation object.
Note If you set the dataId parameter in the moderation request, the dataId parameter is returned in the response.
taskId String aaa25f95-4892-4d6b-aca9-7939bc6e9baa-148619876**** The ID of the OCR task.
url String https://www.aliyundoc.com/test_image_xxxx.png The URL of the moderation object.
extras JSONObject xxx The extra parameters that you set in the extras parameter of the moderation request.
Note This parameter may be subject to changes. Use the latest value of this parameter.

Examples

Sample requests
http(s)://[Endpoint]/green/image/asyncscan
&<Common request parameters>
{
    "scenes": [
        "ocr"
    ],
    "tasks": [
        {
            "dataId": "test_data_xxxx",
            "url": "https://www.aliyundoc.com/test_image_xxxx.png"
        }
    ]
}
Sample responses
{
    "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"
        }
    ]
}

Description about the /green/image/results operation

Operation: /green/image/results

You can call this operation to query asynchronous image moderation results. 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:

    This operation is free of charge.

  • Response timeout:

    We recommend that you query moderation results at least 30s after you send an asynchronous moderation request. Content Moderation retains moderation results for up to 4 hours. If you query moderation results after 4 hours, the results are deleted.

QPS limit

You can send up to 10 requests per second to call this operation by using your Alibaba Cloud account. If you send an excessive number of requests, throttling is implemented, and your business may be affected.

Request parameters

Parameter Type Required Example Description
body JSONArray Yes ["aaa25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695"] The list of IDs of asynchronous moderation tasks that you want to query. The array can contain up to 100 elements.

After you submit a moderation task, you can obtain the ID of the task from the response.

Response parameters

Parameter Type Example Description
code Integer 200 The returned HTTP status code.

For more information, see Common HTTP status codes.

msg String OK The message that is returned for the request.
dataId String test_data_xxxx The ID of the moderation object.
Note If you set the dataId parameter in the moderation request, the dataId parameter is returned in the response.
taskId String aaa25f95-4892-4d6b-aca9-7939bc6e9baa-148619876**** The ID of the OCR task.
url String https://www.aliyundoc.com/test_image_xxxx.png The URL of the moderation object.
results Array The returned results. If HTTP status code 200 is returned after a successful call, the array in the returned 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 Example Description
scene String ocr The moderation scenario. The value is fixed to ocr.
label String ocr The category of the OCR result. Valid values:
  • normal: The image does not contain text.
  • ocr: The image contains text.
suggestion String review 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 Float 99.91 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 area size, and text location. For more information about the structure, see ocrLocation.
ocrData Array This topic describes how to call an operation to submit asynchronous image moderation tasks. 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 xxx The frames that are captured from the moderated GIF image and the text that is detected in each frame.
Table 3. ocrLocation
Parameter Type Example Description
text String hello The single text entry that is detected in the moderated image.
x Float 41 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 Float 84 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 Float 83 The width of the text area. Unit: pixels.
h Float 26 The height of the text area. Unit: pixels.

Examples

Sample requests
http(s)://[Endpoint]green/image/results
&<Common request parameters>
[
    "aaa25f95-4892-4d6b-aca9-7939bc6e9baa-148619876****"
]
Sample responses
{
    "code": 200,
    "data": [
        {
            "code": 200,
            "dataId": "test_data_xxxx",
            "extras": {

            },
            "msg": "OK",
            "results": [
                {
                    "label": "ocr",
                    "ocrData": [
                        "This topic describes how to call an operation to submit asynchronous image moderation tasks."
                    ],
                    "ocrLocations": [
                        {
                            "h": 19,
                            "text": "This topic describes how to call an operation to submit asynchronous image moderation tasks.",
                            "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"
}