PicPurify API documentation

The best way to understand the true power of PicPurify's API is to try it by using our online demo. Satisfied with the result? Time to get started!


✔ DEVELOPER?

You'll be pleased to know that our API is one of the most accurate, but also the easiest one to integrate. You can find below all the documentation you need to get started in a few minutes.


✔ NOT A TECH PERSON?

Not familiar with how API keys work and how to integrate them in your code? Just try our online demo yourself to get some insight and see how powerful our solution is. Once convinced, sign up for free and provide your developer with your personal API key and the link to this page.


IMAGE API DOC



General Notes

  • Image formats: JPG / JPEG, PNG, BMP, TIFF, RAW, PDF, ICO, GIF
  • GIF Support (for animated GIF, only the first frame will be processed)
  • Max image size: 4096*4096 | 16 MB



POST requests


Parameters

Parameter Type Description
API_KEY String Personal client API key
task String A task name (or a list of tasks separated by comma).
Moderation tasks: porn_moderation suggestive_nudity_moderation gore_moderation money_moderation weapon_moderation drug_moderation hate_sign_moderation obscene_gesture_moderation qr_code_moderation
Detection tasks: face_detection face_age_detection face_gender_detection face_gender_age_detection
file_image String Path to the image in your local file system
url_image String URL of the image publicly accessible from internet. Only for tests, can increase latency
reference_id String Optional -A unique reference associated to the image in your information system
origin_id String Optional -A reference to retrieve the origin of the image, profile id, account id ...

Examples

Check an image from local file system
curl -X POST 'https://www.picpurify.com/analyse/1.1' -F 'API_KEY=XXX' -F 'task=porn_moderation,drug_moderation,gore_moderation' -F 'origin_id=xxxxxxxxx' -F 'reference_id=yyyyyyyy' -F 'file_image=@/path/to/local/file.jpg'
Check an image from url publicly accessible from internet
curl -X POST 'https://www.picpurify.com/analyse/1.1' -F 'API_KEY=XXX' -F 'task=porn_moderation,drug_moderation,gore_moderation' -F 'origin_id=xxxxxxxxx' -F 'reference_id=yyyyyyyy' -F 'url_image=http://url_image_to_analyse'
Check an image from local file system
picpurify_url = 'https://www.picpurify.com/analyse/1.1'
img_data = {'file_image': open('/path/to/local/file.jpg', 'rb')}
# if you are using non acsii file names, use the following code instead of the previous line
# img_data = {'file_image': (os.path.basename('/path/to/local/file_speciàl_chàr.jpg').encode('ascii', 'replace'),open('/path/to/local/file_speciàl_chàr.jpg'.decode('utf-8'), 'rb').read())}

result_data = requests.post(picpurify_url,files = img_data, data = {"API_KEY":"XXX", "task":"porn_moderation,drug_moderation,gore_moderation", "origin_id":"xxxxxxxxx", "reference_id":"yyyyyyyy" })
print result_data.content
Check an image from url publicly accessible from internet
picpurify_url = 'https://www.picpurify.com/analyse/1.1'
result_url = requests.post(picpurify_url,data = {"url_image":"http://url_image_to_analyse", "API_KEY":"XXX", "task":"porn_moderation,drug_moderation,gore_moderation", "origin_id":"xxxxxxxxx", "reference_id":"yyyyyyyy"})
print result_url.content
Check an image from local file system
var request = require('request'),
    fs = require('fs');
var picpurifyUrl = 'https://www.picpurify.com/analyse/1.1';
var imagePath = '/path/to/local/file.jpg'

var data = {
    file_image: fs.createReadStream(imagePath),
    API_KEY: 'XXX',
    task:"porn_moderation,drug_moderation,gore_moderation",
    origin_id:"xxxxxxxxx", 
    reference_id:"yyyyyyyy" 
   
};

request.post({ url: picpurifyUrl, formData: data }, function (err, httpResponse, body) {
    if (!err && httpResponse.statusCode == 200) {
        console.log(body)
    }
});
Check an image from url publicly accessible from internet
var request = require('request');
var picpurifyUrl = 'https://www.picpurify.com/analyse/1.1';

request.post(
    picpurifyUrl,
    { form: {url_image:'http://url_image_to_analyse',API_KEY: 'XXX',task:"porn_moderation,drug_moderation,gore_moderation", origin_id:"xxxxxxxxx", reference_id:"yyyyyyyy" } },
    function (error, response, body) {
        if (!error && response.statusCode == 200) {
            console.log(body)
        }
    }
);
Check an image from local file system

$ch = curl_init();

$image_path = "/path/to/local/file.png";
$mime = "image/png";

$cfile = curl_file_create($image_path,$mime);
$data = array('file_image' => $cfile,
		'API_KEY' => "XXX",
		'task' => 'porn_moderation,gore_moderation',
		 'origin_id' => "xxxxxx",
		 'reference_id' => "yyyyyy"

);

curl_setopt($ch, CURLOPT_URL,'https://www.picpurify.com/analyse/1.1');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER , true);
curl_setopt($ch,CURLOPT_SAFE_UPLOAD,true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_HEADER, 0);

$output = curl_exec($ch);

echo $output;
Check an image from url publicly accessible from internet

$ch = curl_init();

$data = array('url_image' => "http://url_image_to_analyse",
		'API_KEY' => "XXX",
		'task' => 'porn_moderation,gore_moderation',
		'origin_id' => "xxxxx",
		'reference_id' => "yyyyyy"

);

curl_setopt($ch, CURLOPT_URL,'https://www.picpurify.com/analyse/1.1');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER , true);
curl_setopt($ch,CURLOPT_SAFE_UPLOAD,true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_HEADER, 0);

$output = curl_exec($ch);

echo $output;


Response

Example of successful response:


{  
   "status":"success",
    "final_decision":"OK",
    "confidence_score_decision":0.99155,
   "porn_moderation":{  
      "confidence_score":0.99921,
      "compute_time":0.109,
      "porn_content":false
   },
  
   "drug_moderation":{  
      "drug_content":false,
      "compute_time":0.11,
      "confidence_score":0.99155
   },
   "gore_moderation":{  
      "gore_content":false,
      "compute_time":0.059,
      "confidence_score":1
   },
   "task_call":"porn_moderation,gore_moderation,drug_moderation",
   "reject_criteria":[  

   ],
   "performed":[  
      "porn_moderation",
      "gore_moderation",
      "drug_moderation"
   ],
   "sub_calls":[  
      "porn_moderation",
      "gore_moderation",
      "drug_moderation"
   ],
  
   "media":{  
      "url_image":"http://url_image_to_analyse",
      "file_image":"",
      "media_id":"c4c623de41a52be977233a5bb5c2e8f3",
      "origin_id":"xxxxxxxxx",
      "reference_id":"yyyyyyyy",
   },
   "total_compute_time":0.8219019412994
}

{
    "status": "success",
    "face_detection": {
        "thumbnail": {
            "top": 0,
            "bottom": 355,
            "right": 472,
            "left": 0
        },
        "compute_time": 0.2655,
        "nb_face": 3,
        "results": [
            {
                "gender": {
                    "decision": "male",
                    "confidence_score": 0.99610728025436
                },
                "age_majority": {
                    "decision": "major",
                    "confidence_score": 0.99930393695831
                },
                "face": {
                    "confidence_score": 0.99993479251862,
                    "face_rectangle": {
                        "top": 115,
                        "right": 110,
                        "bottom": 180,
                        "left": 58
                    }
                }
            },
            {
                "gender": {
                    "decision": "female",
                    "confidence_score": 0.99667239189148
                },
                "age_majority": {
                    "decision": "major",
                    "confidence_score": 0.99640697240829
                },
                "face": {
                    "confidence_score": 0.99964475631714,
                    "face_rectangle": {
                        "top": 153,
                        "right": 265,
                        "bottom": 208,
                        "left": 221
                    }
                }
            },
            {
                "gender": {
                    "decision": "male",
                    "confidence_score": 0.8417876958847
                },
                "age_majority": {
                    "decision": "major",
                    "confidence_score": 0.99655044078827
                },
                "face": {
                    "confidence_score": 0.97893571853638,
                    "face_rectangle": {
                        "top": 151,
                        "right": 330,
                        "bottom": 176,
                        "left": 309
                    }
                }
            }
        ],
        "confidence_score": 0.97893571853638
    },
    "nb_units": 3,
    "sub_calls": [
        "face_detection",
        "gender_detection",
        "age_detection"
    ],
    "task_call": "face_gender_age_detection",
    "media": {
        "url_image": "http://url_image_to_analyse",
        "file_image": "",
        "media_id": "aa56e35804bcd54404f6850b8305ca79",

        "origin_id":"xxxxxxxxx",

      "reference_id":"yyyyyyyy"
    },
    "units_consumed": 3,
    "total_compute_time": 0.78411293029785
}


				


Example of error:

{
"status":"failure",
"error":
  {
    "errorCode":30,
    "errorMsg":"File is not an image"
  }
}


Result fields Type Description
status String This field indicates if the image is sucessfully analysed. The value can be either 'success' or 'failure'.
final_decision String The result of the final décision "OK" or " KO".
confidence_score_decision Number This value indicates the confidence of the final decision. The value varies from 0.5 to 1.
1 for being very confident; 0.5 for being unsure. In case of "OK" gives the confidence of the classifier with the smallest score, in case of "KO" gives the confidence of the classifier the more responsible of the KO.
sub_calls Array Array of sub_tasks, called to perform the main task.
task_call String The main tasks called.
total_compute_time String Total server side compute time.
media:file_image String File image name.
media:url_image String URL of the image publicly accessible from internet.
media:media_id String Picpurify internal media_id generated.
media:reference_id String A unique reference associated to the image in your information system.
media:origin_id String A reference to retrieve the origin of the image, profile id, account id ...
money_moderation:money_content Boolean True if the image contains money.
money_moderation:compute_time Number Compute time of the subtask.
money_moderation:confidence_score Number This value indicates the confidence of each classifier on its detection result. The value varies from 0.5 to 1.
1 for being very confident; 0.5 for being unsure.
face_detection:thumbnail Object Json dictionary of the computed thumbnail with the four coordinates under "top", "left", "bottom", "right" keys. In pixel according to the image dimensions.
face_detection:nb_face Number The number of faces detected in the image.
face_detection:results Array Json array containing the informations related to each person in the image.
face_detection:results:face Object Json dictionary containing the informations related to the face detected.
face_detection:results:face:face_rectangle Object Json dictionary containing the face coordinates with "top", "left", "bottom", "right" keys. In pixel according to the image dimensions.
face_detection:results:gender:decision String Gender classification decision : "male" or "female".
face_detection:results:gender:confidence_score Number Confidence relative to the gender decision.
face_detection:results:age_majority:decision String Age classification decision : "major" or "minor".
face_detection:results:age_majority:confidence_score Number Confidence relative to the age decision.
errorCode Number Error codes.
errorCode:10 (API key error)
errorCode:11 (Account error)
errorCode:12 (Parameters error)
errorCode:20 (No url or data information found in the request")
errorCode:30 (Errors in the image to be analysed. E.g., the format is not supported, the size of image is too large, or the size of the file is too big.)
errorCode:50 (Errors of the API service)
errorMsg String Detailed error messages.

VIDEO API DOC

POST request

Parameters

Parameter Type Description
API_KEY String Personal client API key
task String Moderation tasks: porn_moderation suggestive_nudity_moderation gore_moderation money_moderation weapon_moderation drug_moderation hate_sign_moderation obscene_gesture_moderation qr_code_moderation
Detection tasks: face_detection face_age_detection face_gender_detection face_gender_age_detection
file_video String Path to the video in your local file system.
url_video String URL of the video publicly accessible from internet. Only for tests, can increase latency.
frame_interval Decimal Interval in seconds between the analyzed images. The default value is 1, which means that one frame every second will be analyzed. Values less than 1 can be used. For example 0.1 means an image every 100 ms.
reference_id String Optional -A unique reference associated to the image in your information system.
origin_id String Optional -A reference to retrieve the origin of the image, profile id, account id ...

Examples

Check a video from local file system
curl -X POST 'https://www.picpurify.com/analyse_video.php' -F 'API_KEY=XXX' -F 'task=porn_moderation,drug_moderation,gore_moderation' -F 'frame_interval=1' -F 'origin_id=xxxxxxxxx' -F 'reference_id=yyyyyyyy' -F 'file_video=@/path/to/local/file.mp4'
Check a video from url publicly accessible from internet
curl -X POST 'https://www.picpurify.com/analyse_video.php' -F 'API_KEY=XXX' -F 'task=porn_moderation,drug_moderation,gore_moderation' -F 'frame_interval=1' -F 'origin_id=xxxxxxxxx' -F 'reference_id=yyyyyyyy' -F 'url_video=http://url_video_to_analyse'
Check a video from local file system
picpurify_url = 'https://www.picpurify.com/analyse_video.php'
video_data = {'file_video': open('/path/to/local/file.mp4', 'rb')}
# if you are using non acsii file names, use the following code instead of the previous line
# video_data = {'file_video': (os.path.basename('/path/to/local/file_speciàl_chàr.jpg').encode('ascii', 'replace'),open('/path/to/local/file_speciàl_chàr.jpg'.decode('utf-8'), 'rb').read())}

result_data = requests.post(picpurify_url,files = video_data, data = {"API_KEY":"XXX", "task":"porn_moderation,drug_moderation,gore_moderation", "frame_interval":1, "origin_id":"xxxxxxxxx", "reference_id":"yyyyyyyy" })
print result_data.content
Check a video from url publicly accessible from internet
picpurify_url = 'https://www.picpurify.com/analyse_video.php'
result_url = requests.post(picpurify_url,data = {"url_video":"http://url_video_to_analyse", "API_KEY":"XXX", "task":"porn_moderation,drug_moderation,gore_moderation", "frame_interval":1, "origin_id":"xxxxxxxxx", "reference_id":"yyyyyyyy"})
print result_url.content
Check a video from local file system
var request = require('request'),
    fs = require('fs');
var picpurifyUrl = 'https://www.picpurify.com/analyse_video.php';
var videoPath = '/path/to/local/file.mp4'

var data = {
    file_video: fs.createReadStream(videoPath),
    API_KEY: 'XXX',
    task:"porn_moderation,drug_moderation,gore_moderation",
    "frame_interval":1,
    origin_id:"xxxxxxxxx", 
    reference_id:"yyyyyyyy" 
   
};

request.post({ url: picpurifyUrl, formData: data }, function (err, httpResponse, body) {
    if (!err && httpResponse.statusCode == 200) {
        console.log(body)
    }
});
Check a video from url publicly accessible from internet
var request = require('request');
var picpurifyUrl = 'https://www.picpurify.com/analyse_video.php';

request.post(
    picpurifyUrl,
    { form: {url_video:'http://url_video_to_analyse',API_KEY: 'XXX',task:"porn_moderation,drug_moderation,gore_moderation",  "frame_interval":1 , origin_id:"xxxxxxxxx", reference_id:"yyyyyyyy" } },
    function (error, response, body) {
        if (!error && response.statusCode == 200) {
            console.log(body)
        }
    }
);
Check a video from local file system

$ch = curl_init();

$video_path = "/path/to/local/file.mp4";
$mime = "video/mp4";

$cfile = curl_file_create($video_path,$mime);
$data = array('file_image' => $cfile,
		'API_KEY' => "XXX",
		'task' => 'porn_moderation,gore_moderation',
		 'frame_interval':1,
		 'origin_id' => "xxxxxx",
		 'reference_id' => "yyyyyy"

);

curl_setopt($ch, CURLOPT_URL,'https://www.picpurify.com/analyse_video.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER , true);
curl_setopt($ch,CURLOPT_SAFE_UPLOAD,true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_HEADER, 0);

$output = curl_exec($ch);

echo $output;
Check a video from url publicly accessible from internet

$ch = curl_init();

$data = array('url_video' => "http://url_video_to_analyse",
		'API_KEY' => "XXX",
		'task' => 'porn_moderation,gore_moderation',
		'frame_interval':1,
		'origin_id' => "xxxxx",
		'reference_id' => "yyyyyy"

);

curl_setopt($ch, CURLOPT_URL,'https://www.picpurify.com/analyse_video.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER , true);
curl_setopt($ch,CURLOPT_SAFE_UPLOAD,true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_HEADER, 0);

$output = curl_exec($ch);

echo $output;


Result

Example of successful result:


{  
   "task_call": "porn_moderation,gore_moderation",
    "nb_images": 2,
    "final_decision": "OK",
    "confidence_score_decision": 0.90897,
    "nb_images_ok": 2,
    "nb_images_ko": 0,
  
   "media":{  
      "url_video": "",
        "file_video": "file.mp4",
        "media_id": "94fd30ddb3f3ebc37c1c4649f9d3ff16",
        "reference_id": "xxxxxxxx",
        "origin_id": "yyyyyyyyy"
   },
   "total_compute_time": 2.456799030304,
   
   "images_results": [
        {
            "status": "success",
            "porn_moderation": {
                "confidence_score": 0.99996,
                "compute_time": 0.052,
                "porn_content": false
            },
            "confidence_score_decision": 0.81796,
            "gore_moderation": {
                "gore_content": false,
                "compute_time": 0.045,
                "confidence_score": 0.81796
            },
            "task_call": "porn_moderation,gore_moderation",
            "reject_criteria": [],
            "performed": [
                "porn_moderation",
                "gore_moderation"
            ],
            "sub_calls": [
                "porn_moderation",
                "gore_moderation"
            ],
            "final_decision": "OK",
            "media": {
                "url_image": "",
                "file_image": "00000001.jpg",
                "media_id": "f0b9a4d75917e9aa9fadd369a9694b6a",
                "reference_id": "xxxxxxxx",
                "origin_id": "yyyyyyyyy"
            },
            "total_compute_time": 0.49649596214294
        },
        {
            "status": "success",
            "porn_moderation": {
                "confidence_score": 0.99998,
                "compute_time": 0.072,
                "porn_content": false
            },
            "confidence_score_decision": 0.99998,
            "gore_moderation": {
                "gore_content": false,
                "compute_time": 0.069,
                "confidence_score": 1
            },
            "task_call": "porn_moderation,gore_moderation",
            "reject_criteria": [],
            "performed": [
                "porn_moderation",
                "gore_moderation"
            ],
            "sub_calls": [
                "porn_moderation",
                "gore_moderation"
            ],
            "final_decision": "OK",
            "media": {
                "url_image": "",
                "file_image": "00000002.jpg",
                "media_id": "1179cddb6397c8f8fc6c6fc4dc914178",
                "reference_id": "xxxxxxxx",
                "origin_id": "yyyyyyyyy"
            },
            "total_compute_time": 0.4908709526062
        }
    ]
}
				


Example of error:

{
"status":"failure",
"error":
  {
    "errorCode":60,
    "errorMsg":"File is not in the good format"
  }
}


Result fields Type Description
final_decision String The result of the final décision "OK" or " KO".
confidence_score_decision Number This value indicates the confidence of the final decision. The value varies from 0.5 to 1.
1 for being very confident; 0.5 for being unsure.
nb_images Number Number of images analyzed in the video file.
nb_images_ok Number Number of images that do not contain harmful content.
nb_images_ko Number Number of images that contain harmful content.
task_call String The main tasks called.
total_compute_time String Total server side compute time.
media:file_video String File video name.
media:url_video String URL of the video publicly accessible from internet.
media:media_id String Picpurify internal media_id generated.
media:reference_id String A unique reference associated to the image in your information system.
media:origin_id String A reference to retrieve the origin of the image, profile id, account id ...
images_results Array An array with the detail of the results on each frame of the video analyzed.
errorCode Number Error codes.
errorCode:10 (API key error)
errorCode:11 (Account error)
errorCode:12 (Parameters error)
errorCode:20 (No url or data information found in the request")
errorCode:50 (Errors of the API service)
errorCode:60 (Errors in the video to be analysed. E.g., the format is not supported, the size of the video is too large, or the size of the file is too big.)
errorMsg String Detailed error messages.