Filtering Videos

Available since 3.16.0

1. Filtering Videos

Using Amazon Rekognition to filter videos automatically is a huge improvement that allows videos to be handled quickly and efficiently by a machine learning service. This can also be used in conjunction with the existing moderation as a pre-moderation step to reduce the load on moderators by rejecting videos that very obviously contain adult content.

1.1. Prerequisites

  • Your content is stored in S3 and in a region that Rekognition is supported

  • You have the ability to create new IAM users, roles, SNS Topics, SQS Queues in your Amazon account.

1.2. How to configure CleanSpeak to use this feature

The following steps need to be followed very closely in order to get a working solution.

  1. Go to Amazon Console and create an IAM user.

    1. Under Select AWS access type choose Programmatic access

    2. On that users permissions page choose Attach existing policies directly and add the following permissions:

      • AmazonSQSFullAccess

      • AmazonRekognitionFullAccess

      • AmazonS3ReadOnlyAccess

    3. Store this users access key and their secret access key for later.

  2. Create an IAM service role - This will be used to allow Rekognition to post status messages to a SNS Topic which CleanSpeak will listen to through SQS. Note its ARN, you will use it in CleanSpeak settings and creating a policy within the role itself.

    1. This role needs the following inline policy to work: (You can give the policy any name you like)

    "Version": "2012-10-17",
    "Statement": [
            "Sid": "MySid",
            "Effect": "Allow",
            "Action": "iam:PassRole",
            "Resource": "arn:Service role ARN (created above)"
  1. Go to SNS Console

    1. Create a new topic with a name prefixed with AmazonRekognition (This is REQUIRED!! Amazon Rekognition will not post messages to a topic that is not prefixed with AmazonRekognition and will fail silently from CleanSpeaks point of view)

    2. Note the ARN on this topic and store it for later.

  2. Go to SQS Console

    1. Create a new SQS queue.

    2. Subscribe that queue to the SNS you created in step 3.

    3. Check that SNS is allowed to send messages to SQS.

    4. Keep that queues url for later.

  3. Open SystemGlobal Configuration and click Filter

    1. For Video Filter Provider select Amazon Rekognition

    2. Insert the IAM users credentials you used in step 1

    3. Select a region (likely the same region CleanSpeak is hosted in, but keep in mind that Rekognition does not work in all regions so you may have to select a region that is not the same as CleanSpeaks)

    4. Copy the SQS URL from step 4

    5. Copy the SNS ARN from step 3

    6. Copy the Role ARN from step 2

    7. Save

  4. Open SystemApplications select the application you plan to use or create a new one.

    1. Open the Image / Video tab and check Enable Video Filter

    2. Choose the actions, score adjustments, and alert settings you would like to use for each tier of content score. (Using all allow effectively bypasses the filter)

    3. Save

  5. Submit content with a content part type of video with a content body of a S3 url (See below for an example)

1.3. How to quickly test your configuration

You can quickly check your configuration and settings by going to the management interface and opening the verify tool. This can be reached by clicking FiltersVerification. Now you must open the advanced menu and select Video under Content Type. If Video is not available then your AWS system settings must be missing.

To test a video, remember to use an s3 url that has the same region as your aws credentials AND that the region selected supports Rekognition. You can now paste your s3 url into the text box and press verify. Your video will be filtered and the results will return when Rekognition is complete.

1.4. Example usage of the filter


POST /content/item/moderate

For persistent content you will need to provide a unique identifier (UUID) on the API request. When using this API with persistent content you’ll need to first ensure your Application configuration is set to Persistent Content Type. If you have not done this the API request will fail with an error message indicating you have not yet configured your Application.


POST /content/item/moderate/{contentItemId}

Table 1. Request Parameters

contentItemId [UUID] Required

The Id of the Content Item.

Table 2. Request Body

content [Object] Required

The piece of content being moderated.

content.applicationId [UUID] Required

The Id of the application that corresponds to the content source.

content.createInstant [Long] Required

The instant that the content was generated.

content.location [String] Optional

Specifies the location within the application that the content was generated. For example, you might use a chat room name, area Id for a game, or a thread Id for a forum. This parameter is used by CleanSpeak to display conversational views of content with the [Context View] feature. [Array] Required

An array that contains one to many content parts. If your content only has a single part, such as a chat message, the array will only contain a single text entry. The reason you would send in multiple content parts within a single request is to ensure the moderation decision affects each part.

For example, you may send in an image for moderation, the image has a title and a description field. You would send this to CleanSpeak with three content parts, the image and two text parts. If the content of the image title is rejected the entire content needs to be rejected wholesale, the title, description and the image. In this case it would make sense to treat all three parts as an atomic unit of content.

If individual content parts are not related and can be rejected or approved separately then you should send them to CleanSpeak as separate requests.[x].content [String] Required

The content to be filtered. For videos this is a fully qualified S3 URL of the video to be displayed.[x].name [String] Optional

The name of the content part. This value is optional an intended to better identify the context when you have more than one content part. For example this could be Title, Message Body or Image.[x].type [String] Required

The type of this content part. Use video for this filter.

Other possible values:

  • text

  • bbcode

  • html Available Since 3.19.0

  • attribute

  • hyperlink

  • image

  • video

  • audio

content.receiverDisplayName [String] Optional

The display name of the user that received the content. This parameter should only be set if this piece of content was a private message between two users.

content.receiverId [UUID] Optional

The Id of the user that received of the content. This parameter should only be set if this piece of content was a private message between two users.

content.senderDisplayName [String] Optional

The display name (username or whatever is displayed to other users in the game/forum) that generated the content.

content.senderId [UUID] Required

The Id of the user that generated the content. This parameter is required so that CleanSpeak can analyze and associate the content with the user that generated it.

moderation [String] Optional

Tells CleanSpeak to forcibly put the content into a queue (Approval, User Alert or Content Alert). This overrides the configuration you have setup for the Application in the Management Interface.

  • requiresApproval

  • generatesAlert

  • generatesContentAlert

Example Request JSON
  "content": {
    "applicationId": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
    "createInstant": 13405983821,
    "location": "page296",
    "parts": [
        "content": "",
        "name": "Body",
        "type": "video"
    "senderDisplayName": "PapaSmurf",
    "senderId": "f6d3df91-ed4b-48ad-810f-05a367d328c2"

1.5. Response

Table 3. Response Codes
Code Description


The request was successful. The response will contain a JSON body.


The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.


You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.


Your license has expired. The response will be empty. Contact for assistance.


There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 4. Response Body

content [Object]

The piece of content being moderated. [UUID]

The id of the piece of content. This might have been passed in on the request or generated by CleanSpeak. [Array]

The list of parts of content.[x].name [String]

The name of the part of the content.[x].replacement [String]

The replacement text generated by CleanSpeak after applying the filter rules to this part.

contentAction [String]

The action that the client should take with the content. Possible values:

Content Actions

Action Description


The content should be allowed.


The content should be allowed but only the author of the content should be allowed to view the content.


The content should be allowed, but utilize the replacement text provided in the response.


The content has been queued for approval and should not be displayed to other users until it has been approved by a moderator.


The content should be rejected.

moderationAction [String]

The action that was taken on the content. Possible values:

  • requiresApproval

  • generatesAlert

  • generatesContentAlert

stored [Boolean]

This value indicates if the content was stored by CleanSpeak.

Example Response JSON
  "content": {
    "id": "99f2c4e8-961a-4a34-b9b9-43fc3f3b43ec"
  "contentAction": "allow",
  "stored": true