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 notification. This topic describes how to enable callback notification for the Content Moderation API.

Background information

The Content Moderation API supports callback notification 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 data.

Concepts

The following table introduces the concepts related to callback notification.

Concept Description
callback URL The public endpoint of your server that you specify in the Alibaba Cloud 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 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 push a callback notification repeatedly 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 notification, including asynchronous image moderation and asynchronous video moderation. For more information, see Moderate images asynchronously and Moderate videos asynchronously. If you call an asynchronous operation and need Content Moderation to return the moderation results, specify 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 specify 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 for receiving moderation results.
  2. When you call an asynchronous operation for content moderation, specify 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

  1. Log on to the Alibaba Cloud Content Moderation console.
  2. In the left-side navigation pane, choose Settings > Moderation API.
  3. On the Moderation API page, click the Message tab.
  4. On the Message tab, click Settings or View. If you have not specified a callback URL, the Settings button appears. If you have specified a callback URL, the View button appears.
  5. In the API Callback Notification Settings panel, set the Callback URL parameter and click OK.
    After the callback URL is specified, 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 to the callback URL. Save and use the value of the seed parameter based on your business needs.Specify a callback URL

Content parameter description

After callback notification is enabled, 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 JSON object 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 Moderate images synchronously.
  • 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 Moderate videos asynchronously.
auditReult JSON object No The human review result that is generated by you. This parameter is returned only when human review is performed. For more information, see auditReult.
Note This parameter is not returned if Content Moderation sends only machine-assisted moderation results.
humanAuditResult JSON object 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. auditReult
Parameter Type Required Description
suggestion String Yes The suggestion that you provided during human review. Valid values:
  • block
  • pass
labels JSON array Yes 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 String array No The tag that the human review service sets. The return value can contain multiple tags.
Note By default, this parameter is not returned. If this parameter needs to be returned, submit a ticket. 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"
            }
        ]
    },
    "auditReult": {
        "suggestion": "block",
        "labels": [
            "porn",
            "ad",
            "terrorism"
        ]
    },
    "humanAuditResult": {
          "suggestion": "pass",
          "dataId": "yyyy",
          "labels": [
              "Pornographic content",
              "Vulgar content"
        ],
          "taskId": "xxxxxx"
    }
}