cookies

This website uses cookies. By continuing to browse, you agree that cookies will be stored on your devices. You can change the cookie settings in your browser.

Developer API

Introduction

The xModerator API aims to provide a convenient way to automate image moderation. Calls are made via POST or GET requests and the response is disposed in the JSON format.

 

Prerequisites

We require an API key to be obtained by registering at https://xmoderator.com/register to be used for authentication on all API calls. Above that, we recommend storing moderated images on your servers permanently; however, this is not strictly necessary.

 

Making calls

The API end-point is https://xmoderator.com/api. Calls can be made in either POST or GET requests and may include the following parameters:

name type description required
api_key 32-character string API key obtained from the customer panel yes
url string Permalink to the moderated image yes, if neither "file" nor "base64" are present
file binary octet stream Moderated image file contents in a POST request encoded as multipart/form-data yes, if neither "url" nor "base64" are present
base64 string Moderated image file contents encoded in base 64 as text yes, if neither "file" nor "url" are present

This means a request needs to supply the API key and the file in at least one of three ways. If the file content is supplemented, the URL can be alongside as well(which is recommended).

With "file" it is necessary for the request to be sent as a POST request encoded as multipart/form-data, as if it was sent from an HTML form with the file input. With all other parameters requests can be sent either as POST or GET.

 

Returned values

Example returned values:

{
  "status": {
    "code": 0,
    "description": "Ok"
  },
  "request": {
    "id": 9IXQk3SyjAnoPBwmXPH2aiNXRDffh29D,
    "timestamp": 1522815971
  },
  "model": {
    "version": "1.0.0",
    "created_at": "2018-03-30"
  },
  "media": {
    "hash": "4b96bd9805ec104e00b1553c91de4af3831bb8a7d6e7c1d5631b9f6ac2bf04e6a0ef4ae7b11f3cb07d37012d2b5dd3b7064906bfb43da6fafc2dd53f8b6c7a32",
    "url": "https://www.example.com/image.jpg"
  },
  "content": {
    "safe": 0.1,
    "unsafe": 0.9
  }
}

Description:

Parameter Description
status.code Status code, possible values later described in detail. Status code 0 denotes successful moderation.
status.description Short description of the status code.
request.id Identifier for the request. Only supplied, if the moderation was successful.
request.timestamp UNIX timestamp with the time of the request.
model.version Version of the API making the assessment.
model.created_at Creation date of this version of the API.
media.hash SHA512 of provided image. Supplied only if image upload was successful.
media.url URL of the image. Mirrors "url" parameter of the request.
content.safe Floating point number from 0 to 1 denoting the API's assessment on safety of this image. 0 is definitely unsafe, 1 is definitely safe. Provided only if "status.code" = 0.
content.unsafe Floating point number from 0 to 1 denoting the API's assessment regarding the lack of safety of this image. Inverse of "content.safe". Provided only if "status.code" = 0.

Status codes may be as following:

Code Description
0 Assessment was successful.
1 Request did not provide file in any way.
2 An error occurred while trying to read the file. The URL may be dead, or if file contents were supplied, then they might be corrupt.
3 An error occurred while trying to process the file. The API could read the file, but could not make an assessment.
4 Invalid URL. This may occur if file contents were not supplied, and the URL seems not to be valid.
5 Authorization error – API key was not supplied.
6 Authorization error – API key is invalid.
7 Authorization error – admin blocked this API key from making calls.
8 Free trial limit of 55,555 moderations was exceeded, and the user needs to agree to further invoicing of API calls in the customer panel.
9 An internal server error has occurred.
10 File too large. Provided file size can not exceed 50 MB.
11 Too many requests No more than 2 requests per second are allowed with free plan.
31 An error occurred while reading the file from the local storage.
32 An error occurred while decoding the file.
33 An error occurred while pre-processing the file.
34 An error occurred while processing the file by the AI model.

 

Example implementation

 

PHP with file_get_contents

$request = array(
    'api_key' => 'YOUR API KEY',
    'url' => 'https://www.example.com/image.jpg'
);
$result_json = file_get_contents('https://xmoderator.com/api?'.http_build_query($request));
print($result_json);
$result = json_decode($result_json);

 

PHP with cURL

POST request. Base64 encoded file

$data = file_get_contents('example.jpg');
$data = array('api_key' => 'YOUR API KEY', 'base64' => base64_encode($data));

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://xmoderator.com/api');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
$json = curl_exec($ch);
curl_close($ch);
$result = json_decode($json, true);
$safeScore = $result['content']['safe'];
echo 'safe score: '.$safeScore;

 

JavaScript with jQuery's $.ajax

const api_endpoint = "https://xmoderator.com/api";
var api_key = "YOUR API KEY";
var url = "https://www.example.com/image.jpg";
var result;
$.ajax({
    url: api_endpoint,
    data: {
        api_key: api_key,
        url: url
    },
    success: function(msg) {
        result = msg;
    }
});

 

Python

GET request

import requests
params = [('api_key','YOUR API KEY'),('url','http://example.com.image.jpg')]
response = requests.get('https://xmoderator.com/api', params)
print(response.text)

 

Python with requests_toolbelt

POST request with binary octet stream

import requests
from requests_toolbelt.multipart.encoder import MultipartEncoder

with open("example.jpg", "rb") as image_file:
    multipart_data = MultipartEncoder(
        fields={
                'api_key': 'YOUR_API_KEY',                 
                'file': ('file', image_file.read(), 'application/octet-stream'),                            
               }
    )
    
response = requests.post('https://xmoderator.com/api', data=multipart_data,
                  headers={'Content-Type': multipart_data.content_type})
                  
print(response.text)