Content Moderation can send asynchronous notifications to inform you of machine-assisted moderation results and your review results. If you want to use or integrate the results for your business purpose, you can enable callback notifications. This topic describes how to enable callback notifications for the Content Moderation API.

Background information

The Content Moderation API supports callback notifications for machine-assisted moderation results and human review results.
  • Callback notification for machine-assisted moderation results: After a moderation request is processed, Content Moderation sends the machine-assisted moderation results to the specified HTTP callback URL by sending an HTTP POST request.
  • Callback notification for human review results: After you review data or call feedback operations to rectify the machine-assisted moderation results, Content Moderation sends the human review results to the specified HTTP callback URL by sending an HTTP POST request. For more information, see Review machine-assisted moderation results.

Terms

The following table introduces the concepts related to callback notifications.

Concept Description
callback URL The public endpoint of your server that you specify in the Content Moderation console. The callback URL must meet the following requirements:
  • Uses HTTP or HTTPS and is accessible from the Internet.
  • Supports the POST method.
  • Supports UTF-8-encoded data.
  • Supports data that is received in the application/x-www-form-urlencoded format.
  • Supports the checksum and content parameters in callback data.
seed The string that is used to verify whether the POST request is sent from Content Moderation to the specified HTTP callback URL.
callback times The number of times that Content Moderation pushes callback notifications to your server. If your server receives a callback notification, it sends the HTTP status code 200 to Content Moderation. If your server fails to receive a callback notification, it sends other HTTP status codes to Content Moderation. After Content Moderation receives an HTTP status code other than 200, Content Moderation continues to push the callback notification until your server receives it. Content Moderation can repeatedly push a callback notification for up to 16 times.
callback data The content of the callback notification that Content Moderation sends to the specified callback URL. For more information about the parameters in the callback data, see Table 1.
Table 1. Parameters in the callback data
Parameter Type Description
checksum String 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.
Note 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.
content String The JSON-formatted string to be parsed to the callback data in the JSON format. For more information about the callback data that is parsed from the content parameter, see the "Content parameter description" section of this topic.

Callback notification for machine-assisted moderation results

All asynchronous moderation operations of the Content Moderation API support callback notifications, including asynchronous image moderation and asynchronous video moderation. For more information, see Asynchronous image moderation and Asynchronous video moderation. If you call an asynchronous operation and need Content Moderation to return the moderation results, set the callback and seed parameters in your moderation request. The callback parameter specifies the callback URL and the seed parameter specifies a string that is used to verify the callback notification request.

Note If you do not set the preceding parameters when you call an asynchronous operation, you can only poll the asynchronous moderation results at regular intervals.

Procedure

  1. Prepare the HTTP callback URL and verification string that are used to receive moderation results.
  2. When you call an asynchronous operation for content moderation, set the callback and seed parameters in your moderation request. For more information, see the parameter description of the relevant API operation.

Callback notification for human review results

If you send human review requests, the review results are not returned in real time. You must configure callback notifications to receive human review results. Content Moderation allows you to use both the machine-assisted moderation and human review services or use only the human review service. When you configure callback notifications, take note of the following differences.

  • Use both the machine-assisted moderation and human review services
    If you use both the machine-assisted moderation and human review services, you must configure a callback notification for human review results in the Content Moderation console. Perform the following steps:
    1. Log on to the Content Moderation console.
    2. In the left-side navigation pane, choose Settings > Machine audit.
    3. On the Machine audit page, click the Message tab.
    4. On the Message tab, click New notification scheme.
    5. In the New notification scheme dialog box, set the Scheme name, Callback URL, Encryption algorithm, Notification type, and Audit Result parameters. Click OK.

      After you configure the callback notification, the system automatically generates a value for the seed parameter. You can use the value of the seed parameter to verify whether a callback notification request is sent from Alibaba Cloud. Save the generated value of the seed parameter.

      Notice
      • If you have configured a callback notification for machine-assisted moderation results, you can reuse the configurations of the callback notification or configure another callback notification based on your business requirements.
      • You can configure a callback notification for receiving all moderation results or only specified moderation results based on your business scenario.
      • Select Alibaba Cloud Human Review Results for the Notification type parameter.
      • Valid values of the Encryption algorithm parameter:
        • SHA256: The HMAC-SHA256 encryption algorithm is used.
        • National secret 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.

    6. On the Machine audit page, click the BizType Manage tab.
    7. On the BizType Manage tab, find the business scenario that you want to manage and click choose message in the Actions column to associate the Callback notification scheme that you configure with the business scenario.

Content parameter description

After you enable callback notifications, Content Moderation sends the moderation results that are generated by the Content Moderation API in a callback notification to the specified callback URL. The callback notification contains the content parameter. The following tables describe the structure of the content parameter.

Table 2. Structure of the content parameter
Parameter Type Required Description
scanResult JSONObject No The machine-assisted moderation result. The structure of this parameter varies depending on the moderation object, such as images and videos.
  • For images, the structure is the same as that of the results parameter that is returned in response to synchronous operations for image moderation. For more information, see Synchronous image moderation.
  • For videos, the structure is the same as that of the results parameter that is returned in response to asynchronous operations for video moderation. For more information, see Asynchronous video moderation.
auditResult JSONObject No The human review result that is generated by you. This parameter is returned only when human review is performed. For more information, see auditResult.
Note This parameter is not returned if Content Moderation sends only machine-assisted moderation results.
humanAuditResult JSONObject No The human review result that is generated by the human review service of Alibaba Cloud. If you purchased the human review service of Alibaba Cloud, this parameter is returned to send the human review result. For more information, see humanAuditResult.
Table 3. auditResult
Parameter Type Required Description
suggestion String Yes The suggestion that you provided during human review. Valid values:
  • block
  • pass
labels JSONArray No The tag that you set during human review. The return value can be one or more tags. Valid values:
  • porn
  • terrorism
  • ad
  • live
Table 4. humanAuditResult
Parameter Type Required Description
suggestion String Yes The suggestion that is provided by the human review service of Alibaba Cloud. Valid values:
  • block
  • pass
taskId String Yes The ID of the moderation task. You can associate the human review result of the content with the corresponding machine-assisted moderation result based on the task ID.
dataId String Yes The ID of the moderated content.
labels StringArray No The tag that the human review service sets. The return value can contain multiple tags.
Note By default, this parameter is not returned. In addition, you must pay a fee for this parameter. For more information, contact Alibaba Cloud technical support.
Example of the content parameter
{
    "scanResult": {
        "code": 200,
        "msg": "OK",
        "taskId": "fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695",
        "url": "http://1.jpg",
        "results": [
            {
                "rate": 100,
                "scene": "porn",
                "suggestion": "block",
                "label": "porn"
            }
        ]
    },
    "auditResult": {
        "suggestion": "block",
        "labels": [
            "porn",
            "ad",
            "terrorism"
        ]
    },
    "humanAuditResult": {
          "suggestion": "pass",
          "dataId": "yyyy",
          "labels": [
              "Pornographic content",
              "Vulgar content"
        ],
          "taskId": "xxxxxx"
    }
}