Filtering Images

Available since 3.28.0

1. Filtering Images

Filtering images is easy with the new media filter

1.1. Prerequisites

  • You have contacted CleanSpeak to have the MediaFilter enabled for your license

1.2. Considerations

  • You will be billed per operation

    • An operation on an image is simply the number of enabled filters

    • Animated GIFs are billed using operations := number of filters enabled × number of frames in the GIF

1.3. How to configure CleanSpeak to use this feature

1.3.1. Setup the image filter

  1. Navigate to your application configuration

  2. Enable store content

  3. Click the media tab

  4. Enable the image filter (if the image filter is missing then your license does not have the media filter feature enabled and you will need to contact sales)

  5. Enable at least one filter type [Nudity, Scam, Offensive, Weapon/Alcohol/Drugs]

  6. Select at least one filter action for the enabled filter (if everything is allow then it will treat the filter as disabled)

  7. Click save

1.3.2. Moderate some content

You can now submit content to this application via the moderate endpoint.

Image moderation works exactly the same as text moderation so you will get a filter response when the filter process 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. This is a publicly reachable url to the content.[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 image 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": "image"
    "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].mediaFilterResult.alcoholConfidence [Float]

The confidence that the image contains alcohol imagery.[x].mediaFilterResult.drugsConfidence [Float]

The confidence that the image contains drug imagery.[x].mediaFilterResult.offensiveResults[x].offensiveConfidence [Float]

The confidence that the image contains offensive content.[x].mediaFilterResult.offensiveResults[x].offensiveTag [String]

The tag for the type of offensive content.[x].mediaFilterResult.offensiveResults[x].position [Float]

The frame that the offensive content exists on.[x].mediaFilterResult.partialNudityConfidence [Float]

The confidence that the image contains partial nudity.[x].mediaFilterResult.partialNudityTag [String]

The associated tag for the type of partial nudity.[x].mediaFilterResult.rawNudityConfidence [Float]

The confidence that the image contains raw nudity.[x].mediaFilterResult.scamConfidence [Float]

The confidence that the image is a known scammer image.[x].mediaFilterResult.weaponConfidence [Float]

The confidence that the image contains weapon.[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