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
VIDEO API DOC
API SDK

IMAGE API DOC



General Notes

  • Image formats: JPG / JPEG, WEBP, 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


Latency Optimization

The latency can be significantly reduced by decreasing the size of the image before the request.

  • Optimal image size for image moderation tasks: 300x300
  • Optimal image size for detection tasks: create a thumbnail (keep the aspect ratio) with a target size of 800x800


Rate Limits

By instituting rate limits, we can ensure the overall stability of the system, while also making sure that the API is protected from abuse. When you hit the rate limit you will receive a 429 error code in the response.
This limit can be increased upon request for legitimate reasons.

  • Max requests per second: 5



POST requests


Image API Endpoint

https://www.picpurify.com/analyse/1.1


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
Complete profile moderation task (full check of moderation and detection tasks - 12 units): content_moderation_profile
file_image Object Image data loaded from 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 
const fetch = require('node-fetch');
const fs = require('fs');
const FormData = require('form-data');
var picpurifyUrl = 'https://www.picpurify.com/analyse/1.1';
var imagePath = '/path/to/local/file.jpg'

const form = new FormData();
const stats = fs.statSync(imagePath);
const file = fs.createReadStream(imagePath);
form.append('file_image', file, { knownLength: stats.size });
form.append('API_KEY','XXX');
form.append('task','porn_moderation,drug_moderation,gore_moderation');
form.append('origin_id',"xxxxxxxxx");
form.append('reference_id',"yyyyyyyy");

fetch(picpurifyUrl, {
    method: 'POST',
    body: form
}).then((response) => {
    return response.json();
}).then((json) => {
    console.log(json);
}).catch((error) => {
    console.log(error.message);
})
Check an image from url publicly accessible from internet
const fetch = require('node-fetch');
const fs = require('fs');
const FormData = require('form-data');
var picpurifyUrl = 'https://www.picpurify.com/analyse/1.1';

const form = new FormData();
form.append('url_image', 'https://url_image_to_analyse');
form.append('API_KEY','XXX');
form.append('task','porn_moderation,drug_moderation,gore_moderation');
form.append('origin_id',"xxxxxxxxx");
form.append('reference_id',"yyyyyyyy");

fetch(picpurifyUrl, {
    method: 'POST',
    body: form
}).then((response) => {
    return response.json();
}).then((json) => {
    console.log(json);
}).catch((error) => {
    console.log(error.message);
})
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 successfully analysed. The value can be either 'success' or 'failure'.
final_decision String The result of the final decision "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)
errorCode:429 (Too many requests)
errorMsg String Detailed error messages.
VIDEO API DOC



General Notes

Our video moderation is an image per image analysis, so the cost depends on the video size and the 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.

There is no time constraint for videos, but the longer they are, the longer the processing time will be. For faster processing, please apply a resolution reduction to the video.

  • Video type: URL or file.
  • Max video size: 50Mo for video file. 1Go for video URL.


Rate Limits

When you hit the rate limit you will receive a 429 error code in the response.
This limit can be increased upon request for legitimate reasons.

  • Max requests per second: 1



POST request


Video API Endpoint

https://www.picpurify.com/analyse_video/1.0


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
Complete profile moderation task (full check of moderation and detection tasks - 12 units): content_moderation_profile
file_video Object Video data loaded from 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/1.0' -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/1.0' -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/1.0'
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/1.0'
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 
const fetch = require('node-fetch');
const fs = require('fs');
const FormData = require('form-data');
var picpurifyUrl = 'https://www.picpurify.com/analyse_video/1.0';
var videoPath = '/path/to/local/file.mp4'

const form = new FormData();
const stats = fs.statSync(videoPath);
const file = fs.createReadStream(videoPath);
form.append('file_video', file, { knownLength: stats.size });
form.append('API_KEY','XXX');
form.append('frame_interval',1);
form.append('task','porn_moderation,drug_moderation,gore_moderation');
form.append('origin_id',"xxxxxxxxx");
form.append('reference_id',"yyyyyyyy");

fetch(picpurifyUrl, {
    method: 'POST',
    body: form
}).then((response) => {
    return response.json();
}).then((json) => {
    console.log(json);
}).catch((error) => {
    console.log(error.message);
})
Check a video from url publicly accessible from internet
const fetch = require('node-fetch');
const fs = require('fs');
const FormData = require('form-data');
var picpurifyUrl = 'https://www.picpurify.com/analyse_video/1.0';

const form = new FormData();
form.append('url_video', 'https://url_video_to_analyse');
form.append('API_KEY','XXX');
form.append('frame_interval',1);
form.append('task','porn_moderation,drug_moderation,gore_moderation');
form.append('origin_id',"xxxxxxxxx");
form.append('reference_id',"yyyyyyyy");

fetch(picpurifyUrl, {
    method: 'POST',
    body: form
}).then((response) => {
    return response.json();
}).then((json) => {
    console.log(json);
}).catch((error) => {
    console.log(error.message);
})
Check a video from local file system 

$ch = curl_init();

$video_path = "/path/to/local/file.mp4";
$filename = basename($video_path);
$mime = "video/mp4";

$cfile = curl_file_create($video_path,$mime,$filename);
$data = array('file_video' => $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/1.0');
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/1.0');
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.)
errorCode:429 (Too many requests)
errorMsg String Detailed error messages.
ANY ISSUE? CONTACT US!