Content Moderation RESTful API Callback Service

Last updated 2022/06/17 03:34:48

The Agora Content Moderation service sends a message notification callback of content moderation or screenshots to your application server in the form of an HTTPS POST request. The data format is JSON, and the character encoding is UTF-8.

After receiving a notification callback, your server needs to respond, and the body format of the response must be JSON. In any of the following cases, the Agora Content Moderation service considers the notification a failure:

After sending the message notification, it does not receive a response from your server within 5 seconds.
The response HTTP status code is not 200, or the response body format is not JSON.

The Agora Content Moderation service retries immediately after the first notification failure and sends a message notification again. A total of three notification attempts are made.

The callback of Content Moderation

In a content moderation scenario, the Agora Content Moderation service sends the results of content moderation to the specified server address in the form of an HTTP request.

HTTP request

Request header

Field name	Value
`Content-Type`	`application/json;charset=utf-8`

Request body

The request body is in the JSON Object type and contains the following fields:

Field name	Category	Description
`requestId`	String	The notification ID, which identifies the notification callback when the event occurs.
`"callbackParam": {`	JSON Object	Customize the incoming fields in the callback; currently only the cname field, which is the channel name.
`callbackData`	String	String data transparently transmitted by the content moderation module in the SDK.
`checksum`	String	The MD5 value calculated from the four parameter values of `callbackAddr`, `code`, `object`, and `requestId`, which is used to verify whether this callback notification comes from the Agora Content Moderation service.
`object`	String	The file name of the screenshot inspected in this callback. The naming rules for this file: `<OSS prefix>/<year month day>/<sid>_<cname>__uid_s_<uid>__uid_e_<type>_utc.jpg`。 The meaning of each field is as follows: `<sid>`: The ID of the content moderation process. The unique identification of the current content moderation process. `<cname>`: The name of the channel to which the identified user belongs. `<uid>`: The user ID. The User ID set when joining the channel. `<type>`: The file type. Only `video` is supported. `<utc>`: The Unix timestamp (s) of the content moderation. UTC time, consisting of years, months, days, hours, minutes, and seconds. For example, if the start time of content moderation is 11:32:25 UTC on October 18, 2021, the Unix timestamp is 1634527945.
`code`	Number	The status code of the content moderation process. `200` means that the content moderation is completed.
`msg`	String	The status of the content moderation process. `"Moderation complete"` means that the content moderation process is completed.
`channelName`	String	The name of the channel to which the identified user belongs, which is the same as the one contained in the object file name.
`userId`	String	The user ID of the user in the content moderation process, which is the same as the one contained in the object file name.
`results`	JSON Object	The result of the content moderation.
`results.porn`	JSON Object	The content moderation output data.
`results.porn.outputs`	JSON Object	The possibility that the screenshot is a neutral, sexually suggestive, or pornographic image.
`results.porn.outputs.neutral`	Float	The possibility that the screenshot is a neutral image. This result means that there is no inappropriate content contained in the image, but there may be normal and moderate body nudity and body curves.
`results.porn.outputs.porn`	Float	The possibility that the image is pornographic. This result means the image contains nudity that includes genitals, sexual behaviors and cues, or puts excessive emphasis on sexual characteristics.
`results.porn.outputs.sexy`	Float	The possibility that the screenshot is sexually suggestive. This result means the image contains substantial nudity or the outline of the male or female sexual features, but no genital exposure.
`results.porn.scene`	String	Content moderation results. The content moderation result is based on the three floating-point values in`outputs` to determine the nature of an image. `scene` returns the following values: `neutral`: Neutral image `porn`: Pornographic image `sexy`: Sexually suggestive image
`suggestion`	String	The processing comments of a image. This contains the following fields: `pass`: Neutral image; no processing needed. `block`: Pornographic image that failed to pass the content moderation process; block the image. `review`: Sexually suggestive image; process according to your criteria. For images that turn out to be sexually suggestive, you can either consider them to be neutral according to your own scenarios, with no processing needed, or you can prompt a manual inspection. For example, for social applications with a higher tolerance for sexual suggestiveness, the images may be considered to be neutral; for education applications where this is not appropriate, the images likely need human moderation.
`timestamp`	Int	The Unix timestamp (s) of the content moderation. UTC time, which is the same as the one contained in t the object file name.``

Request example

{
    "requestId": "38f8e3cfdc474cd56fc1ceba380d7e1a_1652693284_b5813fe2ae4fa5cdfe5abd8fef82526f",
    "callbackParam": {
        "cname": "httpClient463224"
    },
    "callbackData": "",
    "checksum": "75ee98849119c2ad4ec2aef58f178fd8",
    "object": "xiaozuke/20201216/38f8e3cfdc474cd56fc1ceba380d7e1a_httpClient463224__uid_s_91__uid_e_video_20200413081128672.jpg",
    "code": 200,
    "msg": "Moderation complete",
    "channelName": "httpClient463224",
    "userId": "91",
    "results": {
        "porn": {
            "outputs": {
                "neutral": 0.915607393,
                "porn": 0.082511887,
                "sexy": 0.00188077823
            },
            "scene": "neutral"
        }
    },
    "suggestion": "pass",
    "timestamp": 20190611073246070
}

The screenshot callback

In the screenshot-only scenario, the Agora Content Moderation service only accepts pictures uploaded by the SDK; it does not review them. The Agora Content Moderation cloud server sends the moderation results to the server you specify in the form of an HTTP request.

HTTP request

Request header

Field name	Value
`Content-Type`	`application/json;charset=utf-8`

Request body

The request body is in the JSON Object type and contains the following fields:

Field name	Category	Description
`requestId`	String	The notification ID, which identifies the notification callback when the event occurs.
`"callbackParam": {`	JSON Object	Customize the incoming fields in the callback``; currently only the cname field, which is the channel name.
`callbackData`	String	String data transparently transmitted by the content moderation module in the SDK.
`checksum`	String	The MD5 value calculated from the four parameter values of `callbackAddr`, `code`, `object`, and `requestId`, which is used to verify whether this callback notification comes from the Agora Content Moderation service.
`object`	String	The file name of the screenshot inspected in this callback. The files are named by combining the following fields: `<OSS prefix>/<year month day>/<sid>_<cname>__uid_s_<uid>__uid_e_<type>_utc.jpg`. The meaning of each field is as follows: `<sid>`: The screenshot ID. The unique identification of the current screenshot. `<cname>`: The name of the channel to which the user whose content was screenshot belongs. `<uid>`: The user ID. The user ID set when joining the channel. `<type>`: The file type. Only `video` is supported. `<utc>`: The Unix timestamp (s) of the screenshot. UTC time, consisting of years, months, days, hours, minutes, and seconds. For example, when `utc` is `20190611073246073`, it indicates that the slice file starts at 07:32:46.073 a.m., June 11, 2019.
`code`	Number	The status code of the screenshot process. `200` means that the screenshot is complete.
`msg`	String	The status of the screenshot process. `"Supervise complete"` means that the screenshot process is completed.
`channelName`	String	The name of the channel to which the user whose content was screenshot belongs. This is the same as `object.cname`.
`userId`	String	The user ID of the user whose content was screenshot. This is the same as `object.uid`.
`timestamp`	Int	The Unix timestamp (s) of the screenshot. UTC time, which is the same as `object.utc`.

Request example

{
    "requestId": "38f8e3cfdcXXXXXXXXX1ceba380d7e1a_1652693284_b5813fe2ae4fa5cdfe5abd8fef82526f",
    "callbackParam": {
        "cname": "httpClient463224"
    },
    "callbackData": "",
    "checksum": "75ee988XXXXXXc2ad4ec2aef58f178fd8",
    "object": "test/20201216/38f8e3cfdc474cd56fc1ceba380d7e1a_httpClient463224__uid_s_91__uid_e_video_20200413081128672.jpg",
    "code": 200,
    "msg": "Supervise complete",
    "channelName": "httpClient463224",
    "userId": "91",
    "timestamp": 20190611073246070
}

Status code

Code	Description
`200`	The request succeeds.
`201`	The request has been fulfilled, resulting in the creation of a new resource.
`206`	No user in the channel sent a stream during the content moderation process, or some of the screenshots are uploaded to the Agora cloud backup instead of the third-party cloud storage.
`400`	The request has a syntax error (such as a parameter error) that the server cannot understand.
`401`	Unauthorized (App ID or Customer Certificate mismatch).
`404`	The requested resource could not be found.
`500`	The server has an internal error and cannot process the request.
`504`	Internal server error. The gateway or proxy server did not receive a timely request from the upstream server.

Is this page helpful?

Yes