WebPurify Image Moderation

Cloudinary is a cloud-based service that provides an end-to-end image management solution including uploads, storage, manipulations, optimizations and delivery.

Cloudinary offers a very rich set of image uploading, manipulation and media library management capabilities. Cloudinary allows you to upload images to the cloud, manipulate them on-the-fly and deliver them to your users optimized and cached via a fast CDN.

WebPurify offers an image moderation service based on human moderator experts. Cloudinary provides an add-on for using WebPurify's image moderation capabilities, fully integrated into Cloudinary's image management and manipulation pipeline.

With WebPurify's image moderation add-on, you can extend Cloudinary's powerful cloud-based image media library and delivery capabilities with automatically moderation of your photos. When using the WebPurify add-on, user uploaded images are automatically moderated, making sure that no adult or offensive photos are displayed to your web and mobile viewers.

Note
The criteria for image moderation can be customized by contacting us.

Automatic image moderation flow

The following list describes the flow of uploading and displaying moderated images using Cloudinary and the WebPurify image moderation add-on:

  • Image upload
    • Your users upload an image to Cloudinary through your application.
    • The uploaded images are set to a 'pending' status, with short term CDN caching.
    • You can decide whether to display the pending image or wait for its approval.
  • Image moderation
    • The uploaded image is sent to WebPurify for asynchronous moderation in the background.
    • The image is either approved or rejected by WebPurify's moderation add-on.
    • An optional notification callback is sent to your application with the image moderation result.
    • If the image is approved, its cache settings are modified to be long-term.
    • A rejected image is removed and the original rejected image is moved to a secondary backup repository, consuming additional storage.
  • Manual override
    • Pending, approved and rejected images can be listed programatically using Cloudinary's API or interactively using our online Media Library Web interface.
    • You can manually override the automatic moderation using the API or Media Library.

Request image moderation

Before you start, if you haven't done so already, please sign-up to a free Cloudinary account. After signing up, you can try the WebPurify image moderation add-on for free and later on subscribe to an add-on plan that best matches your usage requirements.

In order to request moderation of uploaded images, simply set the moderation upload API parameter to webpurify:

Ruby:
Cloudinary::Uploader.upload("local_file.jpg", 
  :moderation => "webpurify")
PHP:
\Cloudinary\Uploader::upload("local_file.jpg", 
  array("moderation" => "webpurify"));
Python:
cloudinary.uploader.upload("local_file.jpg",
  moderation = "webpurify")
Node.js:
cloudinary.v2.uploader.upload("local_file.jpg", 
  { moderation: "webpurify" }),
  function(error, result){console.log(result);});
Java:
cloudinary.uploader().upload("local_file.jpg", 
  ObjectUtils.asMap("moderation", "webpurify"));
.Net:
var uploadParams = new ImageUploadParams(){
  File = new FileDescription(@"local_file.jpg"),
  Moderation = "webpurify"};
var uploadResult = cloudinary.Upload(uploadParams);

Tip
You can use upload presets to centrally define a set of upload options including add-on operations to apply, instead of specifying them in each upload call. You can define multiple upload presets, and apply different presets in different upload scenarios. You can create new upload presets in the Upload page of the Management Console settings or using the Admin API. From the Upload page of the console settings, you can also select a default upload preset to use for all API uploads and a default preset for all Media Library (UI) uploads.

The uploaded image is available for delivery based on the randomly assigned public ID with short-term caching of 10 minutes. Image moderation by the WebPurify add-on is performed asynchronously and should be completed within up to a few minutes.

Important
WebPurify automatically rejects the following images: URLs with no image format extension, images with the image format written in CAPS and any images in the PDF format.

The following snippet shows the response of the upload API call that signifies that the WebPurify moderation is in the pending status.

{
  "public_id": "iswyvngmifc",
  "version": 1393751993,
  "url": "http:/res.cloudinary.com/demo/image/upload/v1393751993/iswyvngmi8avzvomdpfc.jpg",
  "moderation": [{ "status": "pending", "kind": "webpurify" }],
  ...
}

Status notification

Due to the fact that the WebPurify add-on moderates images asynchronously, you might want to get notified when the moderation process is completed.

When calling the upload API with WebPurify image moderation, you can set the notification_url to a public HTTP or HTTPS URL of your online web application. Cloudinary sends a POST request to the specified endpoint when WebPurify moderation is completed.

Ruby:
Cloudinary::Uploader.upload("local_file.jpg", 
  :moderation => "webpurify",
  :notification_url => "https://mysite.example.com/hooks")
PHP:
\Cloudinary\Uploader::upload("local_file.jpg", 
  array(
    "moderation" => "webpurify",
    "notification_url" => "https://mysite.example.com/hooks"));
Python:
cloudinary.uploader.upload("local_file.jpg",
  moderation = "webpurify",
  notification_url = "https://mysite.example.com/hooks")
Node.js:
cloudinary.v2.uploader.upload("local_file.jpg", 
  { moderation: "webpurify",
    notification_url: "https://mysite.example.com/hooks" }),
  function(error, result){console.log(result);});
Java:
cloudinary.uploader().upload("local_file.jpg", 
  ObjectUtils.asMap(
    "moderation", "webpurify",
    "notification_url", "https://mysite.example.com/hooks"));
.Net:
var uploadParams = new ImageUploadParams(){
  File = new FileDescription(@"local_file.jpg"),
  Moderation = "webpurify",
  NotificationUrl = "https://mysite.example.com/hooks"};
var uploadResult = cloudinary.Upload(uploadParams);

The following JSON snippet is an example of a POST request sent to the notification URL when moderation is completed. The moderation_status value in this case can be either approved or rejected:

{
  "moderation_response": "approved",
  "moderation_status": "approved",
  "moderation_kind": "webpurify",
  "moderation_updated_at": "2014-03-02T09:33:43Z",
  "public_id": "l8yvniicjhmyxuuqqyqy",
  "uploaded_at": "2014-03-02T09:33:42Z",
  "version": 1393752822,
  "url": 
    "https://res.cloudinary.com/demo/image/upload/v1393752822/l8yvniicjhmyxuuqqyqy.jpg",
  "secure_url": 
    "https://res.cloudinary.com/demo/image/upload/v1393752822/l8yvniicjhmyxuuqqyqy.jpg",
  "etag": "83340520d28b704ca4f4b019effb33dc",
  "notification_type": "moderation" 
}
{
  "moderation_response": "rejected",
  "moderation_status": "rejected",
  "moderation_kind": "webpurify",
  "moderation_updated_at": "2014-03-02T20:47:48Z",
  "public_id": "nuzn4riqxhhzfyfljjxv",
  "uploaded_at": "2014-03-02T20:47:47Z",
  "version": 1393793267,
  "url":
    "https://res.cloudinary.com/demo/image/upload/v1393793267/nuzn4riqxhhzfyfljjxv.jpg",
  "secure_url":
    "https://res.cloudinary.com/demo/image/upload/v1393793267/nuzn4riqxhhzfyfljjxv.jpg",
  "etag":"06778590d96907b60b5fa83795e7df3b",
  "notification_type":"moderation"
}

The JSON content is signed using the API Secret of your Cloudinary account. For more details regarding Cloudinary's notifications and webhooks, see this blog post.

Image moderation queue

Cloudinary's Admin API can be used to list all moderated images. You can list all approved, pending or rejected images by specifying the value of the second parameter of the resources_by_moderation API method. For example to list all rejected images:

Ruby:
Cloudinary::Api.resources_by_moderation("webpurify", "rejected")
PHP:
$api->resources_by_moderation("webpurify", "rejected");
Python:
cloudinary.api.resources_by_moderation("webpurify", "rejected")
Node.js:
cloudinary.api.resources_by_moderation(webpurify, 'rejected', 
  function(result)  { console.log(result) });
Java:
cloudinary.api().resourcesByModeration("webpurify", "rejected", 
  ObjectUtils.emptyMap());
.Net:
var listResourcesResult = cloudinary.ListResourcesByModerationStatus("webpurify", "rejected");

Example response:

{
 "resources": 
  [{
    "public_id": "q7vcvrfjm9mj4bfp3qc8",
    "format": "jpg",
    "version": 1393794403,
    "resource_type": "image",
    "type": "upload",
    "created_at": "2017-05-04T41:02:23Z",
    "bytes": 120253,
    "width": 864,
    "height": 576,
    "backup": true,
    "url": "http://res.cloudinary.com/demo/image/upload/v1393794403/q7vcvrfjm9mj4bfp3qc8.jpg",
    "secure_url": "https://res.cloudinary.com/demo/image/upload/v1393794403/q7vcvrfjm9mj4bfp3qc8.jpg"
  },
  {
    "public_id": "zp4fgdbabhlwwa7bxu84",
    "format": "jpg",
    ...
  }
  ...
 ]
}

Manual override

While the automatic image moderation of the WebPurify add-on is very accurate, in some cases you may want to manually override the moderation decision. You can either approve a previously rejected image or reject an approved one.

One way to manually override the moderation result is using Cloudinary's Media Library Web interface. From the left navigation menu, select Moderation. Then, from moderation tools list in the top menu, select WebPurify and then select which moderation queue of videos to display (Pending, Rejected, or Approved).

  • When listing the queue of videos rejected by WebPurify, you can click on the green Approve button to revert the decision and recover the original rejected video.
  • When listing the queue of videos approved by WebPurify, you can click on the red Reject button to revert the decision and prevent a certain video from being publicly available to your users.

Alternatively, you can use Cloudinary's Admin API to manually override the moderation result. The following sample code uses the update API method while specifying a public ID of a moderated image and setting the moderation_status parameter to the approved status.

Ruby:
Cloudinary::Api.update("hwepb67oxzh4lrigssld", 
  :moderation_status => "approved")
PHP:
$api->update("hwepb67oxzh4lrigssld", 
  array("moderation_status" => "approved"));
Python:
cloudinary.api.update("hwepb67oxzh4lrigssld",
  moderation_status = "approved")
Node.js:
cloudinary.v2.api.update("hwepb67oxzh4lrigssld", 
  { moderation_status: "approved" }),
  function(error, result){console.log(result);});
Java:
cloudinary.api().update("hwepb67oxzh4lrigssld", 
  ObjectUtils.asMap("moderation_status", "approved"));
.Net:
var updateParams = new UpdateParams("hwepb67oxzh4lrigssld"){
  ModerationStatus = "approved"};
var updateResult = cloudinary.Update(updateParams);