NAV Navbar
shellpythonjavascriptphp
  • Introduction
  • Image moderation
  • Video and Stream Moderation
  • Feedback
  • Errors
  • Introduction

    API endpoint

    https://api.sightengine.com/1.0
    
    https://api.sightengine.com/1.0
    
    https://api.sightengine.com/1.0
    
    https://api.sightengine.com/1.0
    

    The Sightengine API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP verbs, which are understood by off-the-shelf HTTP clients.

    We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors.

    Authentication

    Authentication is performed by adding two parameters to all your API requests: api_user and api_secret.

    Both parameters are strings provided in your account information.

    Versioning

    API endpoint

    https://api.sightengine.com/1.0
    

    Versioning is performed through the API URL. The current version of the API documented here is 1.0. If we make backwards-incompatible changes we will bump this version number and let you know that a new version is available through a new URL.

    We may perform backwards-compatible changes to this version of the API. Changes that may be performed are:

    You should therefore make sure that your code does not break if new properties are added or if the order of existing properties is changed.

    Image moderation

    Image moderation works by submitting an image to the moderation API. Our moderation engine will then analyze the image and provide a moderation score.

    Several models are available for you to choose from:

    The API accepts both standard still images: JPEG, PNG, WEBP etc. and multi-frame GIF images. Please keep in mind that when submitting a GIF image you will receive a single result and that all frames will be reviewed. The number of operations performed will therefore be proportional to the number of frames.

    Requests

    Requests are performed via GET or POST.

    GET requests are used to submit a public url to the image that needs to be analyzed POST requests are used to directly submit the content of an image that needs to be analyzed

    Responses

    Example response

    {
      "status": "success",
      "request": {
        "id": "req_VjyxevVQYXQZ1HMbnwtn",
        "timestamp": 1471762434.0244,
        "operations": 1
      },
      "media": {
        "id": "med_KWmB2GQZ29N4MVpVdq5K",
        "uri": "https://sightengine.com/assets/img/examples/example2.jpg"
      }
      ...  
    }
    

    All API responses are JSON formatted. JSONP is also available, in which case a callback parameter must be added to your request.

    As shown in the example response, all responses to image moderation requests will contain the following fields:

    ParameterTypeDescription
    statusstringsuccess if the request was successfully handled, failure otherwise
    requestobjecta JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed)
    media objecta JSON dictionary describing the image received

    Nudity detection

    GET https://api.sightengine.com/1.0/nudity.json
    POST https://api.sightengine.com/1.0/nudity.json
    

    The Nudity endpoint helps you determine if an image contains some kind of nudity and what "level" of nudity it contains. We distinguish three main levels of nudity:

    Request arguments (GET)

    Example request

    curl -X GET \
      'https://api.sightengine.com/1.0/nudity.json?api_user={api_user}&api_secret={api_secret}&url=https://sightengine.com/assets/img/examples/example2.jpg'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('nudity').set_url('https://sightengine.com/assets/img/examples/example2.jpg')
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['nudity']).set_url('https://sightengine.com/assets/img/examples/example2.jpg').then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    
    $output = $client->check(['nudity'])->set_url('https://sightengine.com/assets/img/examples/example2.jpg');
    

    To analyze an image that is publicly accessible over HTTP, you can perform a GET request:

    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    urlyesPublic URL to the image to be moderated

    Request arguments (POST)

    Example request

    curl -X POST 'https://api.sightengine.com/1.0/nudity.json' \
    -F 'api_user={api_user}' \
    -F 'api_secret={api_secret}' \
    -F 'media=@/path/to/local/file.jpg'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('nudity').set_file('/path/to/local/file.jpg')
    
    # binary image
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('nudity').set_bytes(binary_image)
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['nudity']).set_file('/full/path/to/image.jpg').then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    // binary image
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['nudity']).set_bytes(binary_image).then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['nudity'])->set_file('/path/to/local/file.jpg');
    
    // binary image
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['nudity'])->set_bytes($binary_image);
    

    To analyze an image that is not publicly accessible, you should perform a POST request:

    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    mediayesThe image (local file) to be moderated

    Response

    Example response

    {
      "status": "success",
      "request": {
        "id": "req_VjyxevVQYXQZ1HMbnwtn",
        "timestamp": 1471762434.0244,
        "operations": 1
      },
      "nudity": {
        "raw": 0.000757,
        "partial": 0.000763,
        "safe": 0.999243
      },
      "media": {
        "id": "med_KWmB2GQZ29N4MVpVdq5K",
        "uri": "https://sightengine.com/assets/img/examples/example2.jpg"
      }
    }
    

    This request will return a JSON response containing the following parameters:

    ParameterTypeDescription
    statusstringsuccess if the request was successfully handled, failure otherwise
    requestobjecta JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed)
    nudityobject a JSON dictionary containing information on the nudity content of the image, see below for more
    media objecta JSON dictionary describing the image received

    The Nudity object contains the following parameters:

    ParameterTypeDescription
    rawfloatthe probability that the image contains raw nudity
    partialfloatthe probability that the image contains partial nudity
    partial_tagstring if the image contains partial nudity, this string will describe the type of partial nudity. Possible values are bikini, cleavage, chest. Other values may be added in future evolutions so make sure you gracefuly handle them.
    safefloatthe probability that the image does not contain nudity

    Weapons Alcohol Drugs detection

    GET https://api.sightengine.com/1.0/weapon-alcohol-drugs.json
    POST https://api.sightengine.com/1.0/weapon-alcohol-drugs.json
    

    This endpoint is useful to determine if an image contains weapons, alcohol or drugs.

    Request arguments (GET)

    Example request

    curl -X GET \
      'https://api.sightengine.com/1.0/weapon-alcohol-drugs.json?api_user={api_user}&api_secret={api_secret}&url=https://sightengine.com/assets/img/examples/example2.jpg'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('wad').set_url('https://sightengine.com/assets/img/examples/example2.jpg')
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['wad']).set_url('https://sightengine.com/assets/img/examples/example2.jpg').then(function(result) {
      // read the output
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['wad'])->set_url('https://sightengine.com/assets/img/examples/example2.jpg');
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    urlyesPublic URL to the image to be moderated

    Request arguments (POST)

    Example request

    curl -X POST 'https://api.sightengine.com/1.0/weapon-alcohol-drugs.json' \
    -F 'api_user={api_user}' \
    -F 'api_secret={api_secret}' \
    -F 'media=@/path/to/local/file.jpg'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('wad').set_file('/path/to/local/file.jpg')
    
    # binary image
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('wad').set_bytes(binary_image)
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['wad']).set_file('/path/to/local/file.jpg').then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    // binary image
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['wad']).set_bytes(binary_image).then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['wad'])->set_file('/path/to/local/file.jpg');
    
    // binary image
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['wad'])->set_bytes($binary_image);
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    mediayesThe image (local file) to be moderated

    Response

    Example response

    {
        "status": "success",
        "request": {
            "id": "req_0zr9H3yIrEQTCKai01nbF",
            "timestamp": 1491402200.1025,
            "operations": 1
        },
        "weapon": 0.773,
        "alcohol": 0.001,
        "drugs": 0,
        "media": {
            "id": "med_0zr9P0dw3pBYUzuT2jKaP",
            "uri": "https://d3m9459r9kwism.cloudfront.net/img/examples/example-tt-1000.jpg"
        }
    }
    

    This request will return a JSON response containing the following parameters:

    ParameterTypeDescription
    statusstringsuccess if the request was successfully handled, failure otherwise
    requestobjecta JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed)
    weaponfloatthe probability that the image contains weapons
    alcoholfloatthe probability that the image contains alcohol
    drugsfloatthe probability that the image contains drugs
    media objecta JSON dictionary describing the image received

    Faces Attributes detection

    GET https://api.sightengine.com/1.0/check.json?models=face-attributes
    POST https://api.sightengine.com/1.0/check.json?models=face-attributes
    

    The Face endpoint helps you determine if an image contains nobody, one or multiple people.

    Request arguments (GET)

    Example request

    curl -X GET \
      'https://api.sightengine.com/1.0/check.json?models=face-attributes&api_user={api_user}&api_secret={api_secret}&url=https://sightengine.com/assets/img/examples/example7.jpg'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('face-attributes').set_url('https://sightengine.com/assets/img/examples/example7.jpg')
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['face-attributes']).set_url('https://sightengine.com/assets/img/examples/example7.jpg').then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    
    $output = $client->check(['face-attributes'])->set_url('https://sightengine.com/assets/img/examples/example7.jpg');
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    urlyesPublic URL to the image to be moderated

    Request arguments (POST)

    Example request

    curl -X POST 'https://api.sightengine.com/1.0/check.json' \
    -F 'models=face-attributes' \
    -F 'api_user={api_user}' \
    -F 'api_secret={api_secret}' \
    -F 'media=@/path/to/local/file.jpg'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('face-attributes').set_file('/to/local/file.jpg')
    
    # binary image
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('face-attributes').set_bytes(binary_image)
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['face-attributes']).set_file('/to/local/file.jpg').then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    // binary image
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['face-attributes']).set_bytes(binary_image).then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['face-attributes'])->set_file('/to/local/file.jpg');
    
    // binary image
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['face_attributes'])->set_bytes($binary_image);
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    mediayesThe image (local file) to be moderated

    Response

    Example response

    {
        "status": "success",
        "request": {
            "id": "req_0MsK5ptZx713xt5aRmckl",
            "timestamp": 1494406445.3718,
            "operations": 1
        },
        "faces": [
            {
                "x1": 0.5121,
                "y1": 0.1879,
                "x2": 0.6926,
                "y2": 0.6265,
                "features": {
                    "left_eye": {
                        "x": 0.6438,
                        "y": 0.3634
                    },
                    "right_eye": {
                        "x": 0.5578,
                        "y": 0.3714
                    },
                    "nose_tip": {
                        "x": 0.6047,
                        "y": 0.4801
                    },
                    "left_mouth_corner": {
                        "x": 0.6469,
                        "y": 0.5305
                    },
                    "right_mouth_corner": {
                        "x": 0.5719,
                        "y": 0.5332
                    }
                },
                "attributes": {
                    "female": 0.96,
                    "male": 0.04,
                    "minor": 0.01,
                    "sunglasses": 0.01
                }
            }
        ],
        "media": {
            "id": "med_0MsK3A6i2vNxQgHkc11j9",
            "uri": "https://sightengine.com/assets/img/examples/example7.jpg"
        }
    }
    

    This request will return a JSON response containing the following parameters:

    ParameterTypeDescription
    statusstringsuccess if the request was successfully handled, failure otherwise
    requestobjecta JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed)
    facesobject a JSON dictionary containing information on the presence of people / faces in the image, see below for more
    media objecta JSON dictionary describing the image received

    The Face object contains the following parameters:

    ParameterTypeDescription
    x1floatThe bounding box's left X coordinate (expressed as a share of image width in the range [0,1])
    y1floatThe bounding box's top Y coordinate (expressed as a share of image height in the range [0,1])
    x2floatThe bounding box's right X coordinate (expressed as a share of image width in the range [0,1])
    y2float The bounding box's bottom Y coordinate (expressed as a share of image height in the range [0,1])
    featuresobjectPositioning of the elements of the face (expressed as a share of image dimensions, in the range [0,1])
    attributesobjectDescription of the face attributes (see below)

    The Face Attributes object contains the following parameters:

    ParameterTypeDescription
    female  float probability that the face belongs to a female
    male  float probability that the face belongs to a male
    minor floatprobability that the face belongs to a person under 18 years old
    sunglasses  float probability of presence of sunglasses

    Celebrity detection

    GET https://api.sightengine.com/1.0/check.json?models=celebrities
    POST https://api.sightengine.com/1.0/check.json?models=celebrities
    

    This endpoint is useful to determine if an image contains a celebrity.

    Request arguments (GET)

    Example request

    curl -X GET \
      'https://api.sightengine.com/1.0/check.json?models=celebrities&api_user={api_user}&api_secret={api_secret}&url=https://sightengine.com/assets/img/examples/example-craig-300.jpg'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('celebrities').set_url('https://sightengine.com/assets/img/examples/example-craig-300.jpg')
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['celebrities']).set_url('https://sightengine.com/assets/img/examples/example-craig-300.jpg').then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    
    $output = $client->check(['celebrities'])->set_url('https://sightengine.com/assets/img/examples/example-craig-300.jpg');
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    urlyesPublic URL to the image to be moderated

    Request arguments (POST)

    Example request

    curl -X POST 'https://api.sightengine.com/1.0/check.json' \
    -F 'models=celebrities' \
    -F 'api_user={api_user}' \
    -F 'api_secret={api_secret}' \
    -F 'media=@/path/to/local/file.jpg'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('celebrities').set_file('/path/to/local/file.jpg')
    
    # binary image
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('celebrities').set_bytes(binary_image)
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['celebrities']).set_file('/path/to/local/file.jpg').then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    // binary image
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['celebrities']).set_bytes(binary_image).then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['celebrities'])->set_file('/path/to/local/file.jpg');
    
    // binary image
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['celebrities'])->set_bytes($binary_image);
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    mediayesThe image (local file) to be moderated

    Response

    Example response

    {
        "status": "success",
        "request": {
            "id": "req_0MtAXnNu1zHLs6CZXMVaw",
            "timestamp": 1494409587.8202,
            "operations": 1
        },
        "faces": [
            {
                "x1": 0.293,
                "y1": 0.1491,
                "x2": 0.7035,
                "y2": 0.8158,
                "features": {
                    "left_eye": {
                        "x": 0.61,
                        "y": 0.4378
                    },
                    "right_eye": {
                        "x": 0.43,
                        "y": 0.4016
                    },
                    "nose_tip": {
                        "x": 0.5167,
                        "y": 0.5663
                    },
                    "left_mouth_corner": {
                        "x": 0.5667,
                        "y": 0.6787
                    },
                    "right_mouth_corner": {
                        "x": 0.4133,
                        "y": 0.6466
                    }
                },
                "celebrity": [
                    {
                        "name": "Daniel Craig",
                        "prob": 0.99
                    },
                    {
                        "name": "Dean Wareham",
                        "prob": 0.06
                    },
                    {
                        "name": "Ben Daniels",
                        "prob": 0.06
                    },
                    {
                        "name": "Graham Fellows",
                        "prob": 0.05
                    }
                ]
            }
        ],
        "media": {
            "id": "med_0MtAtt9ud8Jaz93Ohb9UE",
            "uri": "https://sightengine.com/assets/img/examples/example-craig-300.jpg"
        }
    }
    

    This request will return a JSON response containing the following parameters:

    ParameterTypeDescription
    statusstringsuccess if the request was successfully handled, failure otherwise
    requestobjecta JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed)
    facesobject a JSON dictionary containing information on the presence of people / faces in the image, see below for more
    media objecta JSON dictionary describing the image received

    The Face object contains the following parameters:

    ParameterTypeDescription
    x1floatThe bounding box's left X coordinate (expressed as a share of image width in the range [0,1])
    y1floatThe bounding box's top Y coordinate (expressed as a share of image height in the range [0,1])
    x2floatThe bounding box's right X coordinate (expressed as a share of image width in the range [0,1])
    y2float The bounding box's bottom Y coordinate (expressed as a share of image height in the range [0,1])
    featuresobjectPositioning of the elements of the face (expressed as a share of image dimensions, in the range [0,1])
    celebrityobjectList of celebrities matching this face (could be empty)

    The celebrity list contains objects with the following parameters:

    ParameterTypeDescription
    name string Name of the matching celebrity
    prob floatProbability that the face belongs to said celebrity (0 to 1)

    Scammer detection

    GET https://api.sightengine.com/1.0/check.json?models=scam
    POST https://api.sightengine.com/1.0/check.json?models=scam
    

    This endpoint is useful to determine if an image contains a scammer.

    Request arguments (GET)

    Example request

    curl -X GET \
      'https://api.sightengine.com/1.0/check.json?models=scam&api_user={api_user}&api_secret={api_secret}&url=https://d3m9459r9kwism.cloudfront.net/img/examples/example-scam1-1000.jpg'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('scam').set_url('https://d3m9459r9kwism.cloudfront.net/img/examples/example-scam1-1000.jpg')
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['scam']).set_url('https://d3m9459r9kwism.cloudfront.net/img/examples/example-scam1-1000.jpg').then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    
    $output = $client->check(['scam'])->set_url('https://d3m9459r9kwism.cloudfront.net/img/examples/example-scam1-1000.jpg');
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    urlyesPublic URL to the image to be moderated

    Request arguments (POST)

    Example request

    curl -X POST 'https://api.sightengine.com/1.0/check.json' \
    -F 'models=scam' \
    -F 'api_user={api_user}' \
    -F 'api_secret={api_secret}' \
    -F 'media=@/path/to/local/file.jpg'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('scam').set_file('/path/to/local/file.jpg')
    
    # binary image
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('scam').set_bytes(binary_image)
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['scam']).set_file('/path/to/local/file.jpg').then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    // binary image
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['scam']).set_bytes(binary_image).then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['scam'])->set_file('/path/to/local/file.jpg');
    
    // binary image
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['scam'])->set_bytes($binary_image);
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    mediayesThe image (local file) to be moderated

    Response

    Example response

    {
        "status": "success",
        "request": {
            "id": "req_0RNttFqUKWhGSAlcENj3Z",
            "timestamp": 1495636774.8524,
            "operations": 1
        },
        "scam": {
            "prob": 0.9895
        },
        "faces": [
            {
                "x1": 0.4186,
                "y1": 0.2417,
                "x2": 0.6152,
                "y2": 0.6698,
                "features": {
                    "left_eye": {
                        "x": 0.5326,
                        "y": 0.3969
                    },
                    "right_eye": {
                        "x": 0.4512,
                        "y": 0.4219
                    },
                    "nose_tip": {
                        "x": 0.4805,
                        "y": 0.525
                    },
                    "left_mouth_corner": {
                        "x": 0.5501,
                        "y": 0.5573
                    },
                    "right_mouth_corner": {
                        "x": 0.4811,
                        "y": 0.5813
                    }
                }
            }
        ],
        "media": {
            "id": "med_0RNtVu0azEaBwPgZI0fur",
            "uri": "https://d3m9459r9kwism.cloudfront.net/img/examples/example-scam1-1000.jpg"
        }
    }
    

    This request will return a JSON response containing the following parameters:

    ParameterTypeDescription
    statusstringsuccess if the request was successfully handled, failure otherwise
    requestobjecta JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed)
    facesobject a JSON dictionary containing information on the presence of people / faces in the image, see below for more
    scam objecta JSON dictionary containing the probability that there is a scammer on the image
    media objecta JSON dictionary describing the image received

    The Face object contains the following parameters:

    ParameterTypeDescription
    x1floatThe bounding box's left X coordinate (expressed as a share of image width in the range [0,1])
    y1floatThe bounding box's top Y coordinate (expressed as a share of image height in the range [0,1])
    x2floatThe bounding box's right X coordinate (expressed as a share of image width in the range [0,1])
    y2float The bounding box's bottom Y coordinate (expressed as a share of image height in the range [0,1])
    featuresobjectPositioning of the elements of the face (expressed as a share of image dimensions, in the range [0,1])

    Type detection

    GET https://api.sightengine.com/1.0/type.json
    POST https://api.sightengine.com/1.0/type.json
    

    The Type endpoint helps you determine if an image is a natural photograph or an illustration.

    An illustration could be a drawing, a painting, a logo, a clipart or any such image that does not look like a natural photograph.

    Request arguments (GET)

    Example request

    curl -X GET \
      'https://api.sightengine.com/1.0/type.json?api_user={api_user}&api_secret={api_secret}&url=https://sightengine.com/assets/img/examples/example2.jpg'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('type').set_url('https://sightengine.com/assets/img/examples/example2.jpg')
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['type']).set_url('https://sightengine.com/assets/img/examples/example2.jpg').then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    
    $output = $client->check(['type'])->set_url('https://sightengine.com/assets/img/examples/example2.jpg');
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    urlyesPublic URL to the image to be moderated

    Request arguments (POST)

    Example request

    curl -X POST 'https://api.sightengine.com/1.0/type.json' \
    -F 'api_user={api_user}' \
    -F 'api_secret={api_secret}' \
    -F 'media=@/path/to/local/file.jpg'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('type').set_file('/path/to/local/file.jpg')
    
    # binary image
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('type').set_bytes(binary_image)
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['type']).set_file('/path/to/local/file.jpg').then(function(result) {
     // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    // binary image
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['type']).set_bytes(binary_image).then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['type'])->set_file('/path/to/local/file.jpg');
    
    // binary image
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['type'])->set_bytes($binary_image);
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    mediayesThe image (local file) to be moderated

    Response

    Example response

    {
      "status": "success",
      "request": {
        "id": "req_VjyxevVQYXQZ1HMbnwtn",
        "timestamp": 1471762434.0244,
        "operations": 1
      },
      "type": {
        "illustration": 0.000757,
        "photo": 0.999243
      },
      "media": {
        "id": "med_KWmB2GQZ29N4MVpVdq5K",
        "uri": "https://sightengine.com/assets/img/examples/example2.jpg"
      }
    }
    

    This request will return a JSON response containing the following parameters:

    ParameterTypeDescription
    statusstringsuccess if the request was successfully handled, failure otherwise
    requestobjecta JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed)
    typeobject a JSON dictionary containing information on the type of the image
    media objecta JSON dictionary describing the image received

    The Type object contains the following parameters:

    ParameterTypeDescription
    illustrationfloatthe probability that the image is an illustration
    photofloatthe probability that the image is a natural photograph

    Text detection

    GET https://api.sightengine.com/1.0/check.json?models=text
    POST https://api.sightengine.com/1.0/check.json?models=text
    

    The Text endpoint can help you determine if an image contains natural text or artificial text. Artificial text is defined as being text that has been added to the image after post-processing, while natural text is text that naturally occurs in the photo.

    Request arguments (GET)

    Example request

    curl -X GET \
      'https://api.sightengine.com/1.0/check.json?models=text&api_user={api_user}&api_secret={api_secret}&url=https://sightengine.com/assets/img/examples/example2.jpg'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('text').set_url('https://sightengine.com/assets/img/examples/example2.jpg')
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['text']).set_url('https://sightengine.com/assets/img/examples/example2.jpg').then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    
    $output = $client->check(['text'])->set_url('https://sightengine.com/assets/img/examples/example2.jpg');
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    urlyesPublic URL to the image to be moderated

    Request arguments (POST)

    Example request

    curl -X POST 'https://api.sightengine.com/1.0/check.json' \
    -F 'models=text' \
    -F 'api_user={api_user}' \
    -F 'api_secret={api_secret}' \
    -F 'media=@/path/to/local/file.jpg'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('text').set_file('/path/to/local/file.jpg')
    
    # binary image
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('text').set_bytes(binary_image)
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['text']).set_file('/path/to/local/file.jpg').then(function(result) {
     // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    // binary image
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['text']).set_bytes(binary_image).then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['text'])->set_file('/path/to/local/file.jpg');
    
    // binary image
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['text'])->set_bytes($binary_image);
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    mediayesThe image (local file) to be moderated

    Response

    Example response

    {
        "status": "success",
        "request": {
            "id": "req_23WtCoW0Q6lPzGdPdjJjZ",
            "timestamp": 1512737637.4493,
            "operations": 1
        },
        "text": {
            "has_artificial": 0.15003,
            "has_natural": 0.75014,
            "boxes": [
                {
                    "x1": 0.23051,
                    "y1": 0.55917,
                    "x2": 0.37446,
                    "y2": 0.6446,
                    "label": "text-natural"
                }
            ]
        },
        "media": {
            "id": "med_23WtF44uHImHV66pOcnUU",
            "uri": "https://sightengine.com/assets/img/examples/text2-1200.jpg"
        }
    }
    

    This request will return a JSON response containing the following parameters:

    ParameterTypeDescription
    statusstringsuccess if the request was successfully handled, failure otherwise
    requestobjecta JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed)
    textobject a JSON dictionary containing information on the presence of text in the image
    media objecta JSON dictionary describing the image received

    The Text object contains the following parameters:

    ParameterTypeDescription
    has_artificialfloatthe probability that the image contains artificial text
    has_naturalfloatthe probability that the image contains natural text
    boxesarrayan array of JSON dictionaries. Each JSON dictionary contains information describing the type and location of text in the image. See below for more

    The boxes object contains JSON dictionaries with the following content:

    ParameterTypeDescription
    x1floatThe bounding box's left X coordinate (expressed as a share of image width in the range [0,1])
    y1floatThe bounding box's top Y coordinate (expressed as a share of image height in the range [0,1])
    x2floatThe bounding box's right X coordinate (expressed as a share of image width in the range [0,1])
    y2float The bounding box's bottom Y coordinate (expressed as a share of image height in the range [0,1])
    labelstringThe type of text present in the box (for instance text-artificial or text-natural)

    Offensive content detection

    GET https://api.sightengine.com/1.0/check.json?models=offensive
    POST https://api.sightengine.com/1.0/check.json?models=offensive
    

    This endpoint is useful to determine if an image contains offensive content.

    Offensive content includes: - offensive gestures, such as middle-fingers - offensive flags, such as the nazi, confederate, ISIS flags - offensive symbols, such as nazi, KKK or SS symbols

    Request arguments (GET)

    Example request

    curl -X GET \
      'https://api.sightengine.com/1.0/check.json?models=offensive&api_user={api_user}&api_secret={api_secret}&url=https://sightengine.com/assets/img/examples/conf2.jpg'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('offensive').set_url('https://sightengine.com/assets/img/examples/conf2.jpg')
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['offensive']).set_url('https://sightengine.com/assets/img/examples/conf2.jpg').then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    
    $output = $client->check(['offensive'])->set_url('https://sightengine.com/assets/img/examples/conf2.jpg');
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    urlyesPublic URL to the image to be moderated

    Request arguments (POST)

    Example request

    curl -X POST 'https://api.sightengine.com/1.0/check.json' \
    -F 'models=offensive' \
    -F 'api_user={api_user}' \
    -F 'api_secret={api_secret}' \
    -F 'media=@/path/to/local/file.jpg'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('offensive').set_file('/path/to/local/file.jpg')
    
    # binary image
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('offensive').set_bytes(binary_image)
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['offensive']).set_file('/path/to/local/file.jpg').then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    // binary image
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['offensive']).set_bytes(binary_image).then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['offensive'])->set_file('/path/to/local/file.jpg');
    
    // binary image
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['offensive'])->set_bytes($binary_image);
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    mediayesThe image (local file) to be moderated

    Response

    Example response

    {
        "status": "success",
        "request": {
            "id": "req_2e254SVW693XMTtD3MvlA",
            "timestamp": 1515064879.7939,
            "operations": 1
        },
        "offensive": {
            "prob": 0.92529,
            "boxes": [
                {
                    "x1": 0,
                    "y1": 0,
                    "x2": 0.91699,
                    "y2": 0.72794,
                    "label": "confederate",
                    "prob": 0.92529
                }
            ]
        },
        "media": {
            "id": "med_2e256k0jvwwnQsWYF0H5x",
            "uri": "https://sightengine.com/assets/img/examples/conf2.jpg"
        }
    }
    

    This request will return a JSON response containing the following parameters:

    ParameterTypeDescription
    statusstringsuccess if the request was successfully handled, failure otherwise
    requestobjecta JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed)
    offensiveobjecta JSON dictionary containing information on the offensive content of the image
    media objecta JSON dictionary describing the image received

    The offensive object contains the following parameters:

    ParameterTypeDescription
    probfloatthe probability that the image contains offensive content
    boxesarrayan array of JSON dictionaries. Each JSON dictionary contains information describing the type, position and probability of offensive content in the image. See below for more

    The boxes object contains JSON dictionaries with the following content:

    ParameterTypeDescription
    x1floatThe bounding box's left X coordinate (expressed as a share of image width in the range [0,1])
    y1floatThe bounding box's top Y coordinate (expressed as a share of image width in the range [0,1])
    x2floatThe bounding box's right X coordinate (expressed as a share of image width in the range [0,1])
    y2floatThe bounding box's bottom Y coordinate (expressed as a share of image width in the range [0,1])
    labelstringthe type of offensive content detected in the given bounding box. The label can be: swastika, ssbolts, confederate, kkk, middlefinger, isisflag, ironcross
    probfloatthe probability level for the given bounding box and its label

    Image Properties

    GET https://api.sightengine.com/1.0/properties.json
    POST https://api.sightengine.com/1.0/properties.json
    

    The Properties endpoint helps you determine the quality of an image (bluriness, contrast, brightness) along with the main colors

    Request arguments (GET)

    Example request

    curl -X GET \
      'https://api.sightengine.com/1.0/properties.json?api_user={api_user}&api_secret={api_secret}&url=https://sightengine.com/assets/img/examples/example2.jpg'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('properties').set_url('https://sightengine.com/assets/img/examples/example2.jpg')
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['properties']).set_url('https://sightengine.com/assets/img/examples/example2.jpg').then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    
    $output = $client->check(['properties'])->set_url('https://sightengine.com/assets/img/examples/example2.jpg');
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    urlyesPublic URL to the image to be moderated

    Request arguments (POST)

    Example request

    curl -X POST 'https://api.sightengine.com/1.0/properties.json' \
    -F 'api_user={api_user}' \
    -F 'api_secret={api_secret}' \
    -F 'media=@/path/to/local/file.jpg'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('properties').set_file('/path/to/local/file.jpg')
    
    # binary image
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('properties').set_bytes(binary_image)
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['properties']).set_file('/path/to/local/file.jpg').then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    // binary image
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['properties']).set_bytes(binary_image).then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['properties'])->set_file('/path/to/local/file.jpg');
    
    // binary image
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['properties'])->set_bytes($binary_image);
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    mediayesThe image (local file) to be moderated

    Response

    Example response

    {
        "status": "success",
        "request": {
            "id": "req_0zrbHDeitGYY7wEGncAne",
            "timestamp": 1491402308.4762,
            "operations": 0
        },
        "sharpness": 0.995,
        "contrast": 0.886,
        "brightness": 0.522,
        "colors": {
            "dominant": {
                "r": 135,
                "g": 127,
                "b": 84,
                "hex": "#877f54"
            },
            "accent": [
                {
                    "r": 163,
                    "g": 149,
                    "b": 41,
                    "hex": "#a39529"
                },
                {
                    "r": 119,
                    "g": 127,
                    "b": 32,
                    "hex": "#777f20"
                }
            ],
            "other": [
                {
                    "r": 50,
                    "g": 48,
                    "b": 20,
                    "hex": "#323014"
                },
                {
                    "r": 232,
                    "g": 222,
                    "b": 204,
                    "hex": "#e8decc"
                },
                {
                    "r": 218,
                    "g": 198,
                    "b": 145,
                    "hex": "#dac691"
                },
                {
                    "r": 84,
                    "g": 62,
                    "b": 25,
                    "hex": "#543e19"
                }
            ]
        },
        "media": {
            "id": "med_0zrbk8nlp4vwI5WxIqQ4u",
            "uri": "https://d3m9459r9kwism.cloudfront.net/img/examples/example-prop-c1.jpg"
        }
    }
    

    This request will return a JSON response containing the following parameters:

    ParameterTypeDescription
    statusstringsuccess if the request was successfully handled, failure otherwise
    requestobjecta JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed)
    sharpness floata value between 0 (very blurry) and 1 (very sharp)
    contrast floata value between 0 (low contrast) and 1 (high contrast)
    brightness floata value between 0 (very dark) and 1 (very bright)
    colors objecta JSON dictionary describing the colors of the image received
    media objecta JSON dictionary describing the image received

    The Colors object contains the following parameters:

    ParameterTypeDescription
    dominantobjectdominant color, defined by its RGB values and HEX code
    accentarrayarray of accent colors
    otherarrayarray of secondary colors

    Custom Check

    GET https://api.sightengine.com/1.0/check.json
    POST https://api.sightengine.com/1.0/check.json
    

    Use this endpoint to perform a custom check using a combination of models. One single request for instance to detect both nudity and weapons.

    Request arguments (GET)

    Example request

    curl -X GET \
      'https://api.sightengine.com/1.0/check.json?models=nudity,wad,properties,face,type,celebrities,face-attributes,scam,text,offensive&api_user={api_user}&api_secret={api_secret}&url=https://sightengine.com/assets/img/examples/example2.jpg'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('nudity','wad','properties','face','type','celebrities','face-attributes', 'scam','text','offensive').set_url('https://sightengine.com/assets/img/examples/example2.jpg')
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['nudity', 'type', 'properties','wad','face','scam','text','offensive']).set_url('https://sightengine.com/assets/img/examples/example2.jpg').then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    
    $output = $client->check(['nudity', 'type', 'properties','wad','face','scam','text','offensive'])->set_url('https://sightengine.com/assets/img/examples/example2.jpg');
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    modelsyesString list of models (see below for details)
    urlyesPublic URL to the image to be moderated

    Request arguments (POST)

    Example request

    curl -X POST 'https://api.sightengine.com/1.0/check.json' \
    -F 'api_user={api_user}' \
    -F 'api_secret={api_secret}' \
    -F 'media=@/path/to/local/file.jpg' \
    -F 'models=nudity,wad,properties,face,type,celebrities,face-attributes,scam,text,offensive'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('nudity','wad','properties','face','type','celebrities','face-attributes','scam','text','offensive').set_file('/path/to/local/file.jpg')
    
    # binary image
    client = SightengineClient("{api_user}", "{api_secret}")
    output = client.check('nudity','wad','properties','face','type','celebrities','face-attributes','scam','text','offensive').set_bytes(binary_image)
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['nudity', 'type', 'properties','wad','face','scam','text','offensive']).set_file('/path/to/local/file.jpg').then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    // binary image
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['nudity', 'type','properties','wad','face','scam','text','offensive']).set_bytes(binary_image).then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['nudity', 'type', 'properties','wad','face','scam','text','offensive'])->set_file('/path/to/local/file.jpg');
    
    // binary image
    $client = new SightengineClient('{api_user}', '{api_secret}');
    $output = $client->check(['nudity', 'type', 'properties','wad','face','scam','text','offensive'])->set_bytes($binary_image);
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    modelsyesString list of models (see below for details)
    mediayesThe image (local file) to be moderated

    List of models

    The models string is a comma-separated list of the models you want to apply. The string denominations for each model is:

    To apply all models, the models parameter should therefore be nudity, wad, properties, face, type, celebrities, face-attributes, scam, text, offensive

    Response

    Example response

    {
        "status": "success",
        "request": {
            "id": "req_0GxfxHCu3efMEReZrhCZ9",
            "timestamp": 1493039362.0472,
            "operations": 7
        },
        "weapon": 0.004,
        "alcohol": 0.003,
        "drugs": 0.003,
        "nudity": {
            "raw": 0.000187,
            "partial": 0.00029,
            "safe": 0.999523
        },
        "type": {
            "photo": 0.99571,
            "illustration": 0.00429
        },
        "face": {
            "single": 0.99513,
            "multiple": 0.266678
        },
        "scam": {
            "prob": 0.01
        },
        "text": {
            "has_artificial": 0.01,
            "has_natural": 0.01
        },
        "offensive": {
            "prob": 0.92529,
            "boxes": [
                {
                    "x1": 0,
                    "y1": 0,
                    "x2": 0.91699,
                    "y2": 0.72794,
                    "label": "confederate",
                    "prob": 0.92529
                }
            ]
        },
        "faces": [
            {
                "x1": 0.0603,
                "y1": 0.193,
                "x2": 0.7414,
                "y2": 0.7839,
                "features": {
                    "left_eye": {
                        "x": 0.4727,
                        "y": 0.455
                    },
                    "right_eye": {
                        "x": 0.1818,
                        "y": 0.4233
                    },
                    "nose_tip": {
                        "x": 0.2591,
                        "y": 0.5635
                    },
                    "left_mouth_corner": {
                        "x": 0.45,
                        "y": 0.6455
                    },
                    "right_mouth_corner": {
                        "x": 0.1591,
                        "y": 0.6243
                    }
                },
                "attributes": {
                    "minor": 0.02,
                    "sunglasses": 0.01
                },
                "celebrity": [
                    {
                        "name": "Ryan Gosling",
                        "prob": 0.99
                    },
                    {
                        "name": "Sophia Rokhlin",
                        "prob": 0.41
                    },
                    {
                        "name": "Timothy Balme",
                        "prob": 0.02
                    },
                    {
                        "name": "Uncle Kracker",
                        "prob": 0.01
                    }
                ]
            }
        ],
        "sharpness": 0.981,
        "contrast": 0.838,
        "brightness": 0.626,
        "colors": {
            "dominant": {
                "r": 180,
                "g": 140,
                "b": 132,
                "hex": "#b48c84"
            },
            "accent": [
                {
                    "r": 144,
                    "g": 76,
                    "b": 74,
                    "hex": "#904c4a"
                }
            ],
            "other": [
                {
                    "r": 214,
                    "g": 218,
                    "b": 225,
                    "hex": "#d6dae1"
                },
                {
                    "r": 52,
                    "g": 38,
                    "b": 31,
                    "hex": "#34261f"
                },
                {
                    "r": 106,
                    "g": 66,
                    "b": 54,
                    "hex": "#6a4236"
                },
                {
                    "r": 239,
                    "g": 211,
                    "b": 185,
                    "hex": "#efd3b9"
                }
            ]
        },
        "media": {
            "id": "med_0Gxf31gS1QsOfT4MVurQ9",
            "uri": "https://upload.wikimedia.org/wikipedia/commons/thumb/4/46/Ryan_Gosling_Cannes_2014.jpg/220px-Ryan_Gosling_Cannes_2014.jpg"
        }
    }
    

    This request will return a JSON response containing part of the following parameters, depending on which models you requested:

    ParameterTypeDescription
    statusstringsuccess if the request was successfully handled, failure otherwise
    requestobjecta JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed)
    weaponfloatthe probability that the image contains weapons
    alcoholfloatthe probability that the image contains alcohol
    drugsfloatthe probability that the image contains drugs
    nudityobject an object containing information on the nudity content of the image
    typeobject a JSON dictionary containing information on the type of the image
    facesobject a JSON dictionary containing information on the presence of faces / celebrities in the image
    sharpness floata value between 0 (very blurry) and 1 (very sharp)
    contrast floata value between 0 (low contrast) and 1 (high contrast)
    brightness floata value between 0 (very dark) and 1 (very bright)
    scam objectthe probability that the image contains scammers
    text object a JSON dictionary containing information on the presence of text in the image
    offensive object a JSON dictionary containing information on the presence of offensive content in the image
    celebrity objecta JSON dictionary with the probability that the image contains a celebrity
    colors objecta JSON dictionary describing the colors of the image received
    media objecta JSON dictionary describing the image received

    Video and Stream Moderation

    Video and Stream Moderation is useful if you need to moderate video content. The service works both for static videos - stored as video files for instance - and for live video streams that need to be moderated in realtime, as they are being recorded or as they are being streamed.

    To moderate a video, you should submit the video or stream's URL to the Moderation API. Our Moderation Engine will then start consuming this video stream and moderate it in real-time.

    Introduction

    You can perform either synchronous or asynchronous Video Moderation.

    Sightengine can consume videos and streams delivered over all major protocols (http, https, rtmp, rtsp, rtp...) and supports all major video formats (mpg, mov, avi, ogg, mkv, mp4, webm, flv...). Moderation can be done both on live streams and past streams (i.e. stored videos).

    Synchronous Moderation

    GET https://api.sightengine.com/1.0/video/check-sync.json
    

    The first step to moderate a video stream is to submit the video stream to the API.

    Request arguments

    Example request

    curl -X GET \
      'https://api.sightengine.com/1.0/video/check-sync.json?models=nudity,wad,faces,face-attributes,celebrities&stream_url=https://sightengine.com/assets/stream/examples/funfair.mp4&api_user={api_user}&api_secret={api_secret}'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    client.check('nudity', 'wad', 'faces', 'face-attributes', 'celebrities').video_sync('https://sightengine.com/assets/stream/examples/funfair.mp4')
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['nudity', 'wad', 'faces', 'face-attributes', 'celebrities']).video_sync('https://sightengine.com/assets/stream/examples/funfair.mp4').then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    
    $client->check(['nudity', 'wad', 'faces', 'face-attributes', 'celebrities'])->video_sync('https://sightengine.com/assets/stream/examples/funfair.mp4');
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    modelsyesString list of models (see below for details)
    stream_urlyesPublic URL to the video to be moderated (could be http, https, rtmp, rtsp, rtp...)

    List of models

    The models string is a comma-separated list of the models you want to apply. The string denominations for each model is:

    To apply all models, the models parameter should therefore be nudity, wad, properties, faces, type, celebrities, face-attributes, scam

    Response

    Example response

    {
        "status": "success",
        "request": {
            "id": "req_1ML249NoEZ8j12op9Lipg",
            "timestamp": 1508774201.3177
        },
        "media": {
            "id": "med_1ML2wKmVgucuNPBN6xT33",
            "uri": "https://sightengine.com/assets/stream/examples/funfair.mp4"
        },
        "data": {
          "frames" : [
            {
                "info": {
                    "id": "med_1ML2wKmVgucuNPBN6xT33_1",
                    "position": 0
                },
                "nudity": {
                    "raw": 0.01,
                    "safe": 0.98,
                    "partial": 0.01
                }
            },
            {
                "info": {
                    "id": "med_1ML2wKmVgucuNPBN6xT33_2",
                    "position": 1000
                },
                "nudity": {
                    "raw": 0.01,
                    "safe": 0.98,
                    "partial": 0.01
                }
            }
          ]
        }
    }
    

    This request will return a JSON response containing the following parameters:

    ParameterTypeDescription
    statusstring"success" if the request was successfully handled
    requestobjectJSON dictionary containing the request ID and timestamp
    mediaobjectJSON dictionary containing the media ID and URI
    data objectJSON dictionary describing the moderation results

    The frames property in the data object is an array of successive frames. For each frames, "info" contains its id and position (in milliseconds) along with moderation results.

    Asynchronous Moderation

    GET https://api.sightengine.com/1.0/video/check.json
    

    The first step to moderate a video stream is to submit the video stream to the API.

    Request arguments

    Example request

    curl -X GET \
      'https://api.sightengine.com/1.0/video/check.json?models=nudity,wad,faces,face-attributes,celebrities&stream_url=https://sightengine.com/assets/stream/examples/funfair.mp4&callback_url=protocol://yourcallback&api_user={api_user}&api_secret={api_secret}'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    client.check('nudity', 'wad', 'faces', 'face-attributes', 'celebrities').video('https://sightengine.com/assets/stream/examples/funfair.mp4', 'https://example.com/yourcallback')
    
    var sightengine = require('sightengine')("{api_user}", "{api_secret}");
    
    sightengine.check(['nudity', 'wad', 'faces', 'face-attributes', 'celebrities']).video('https://sightengine.com/assets/stream/examples/funfair.mp4', 'https://example.com/yourcallback').then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    
    $client->check(['nudity', 'wad', 'faces', 'face-attributes', 'celebrities'])->video('https://sightengine.com/assets/stream/examples/funfair.mp4', 'https://example.com/yourcallback');
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    modelsyesString list of models (see below for details)
    stream_urlyesPublic URL to the video to be moderated (could be http, https, rtmp, rtsp, rtp...)
    callback_urlyesCallback URL where moderation events will be posted
    callthreshold_nudity_rawnoMinimum nudity_raw probability to generate a callback. Should be a float between 0 and 1. Default is 0.5.
    callthreshold_nudity_partialnoMinimum nudity_partial probability to generate a callback. Should be a float between 0 and 1. Default is 0.5.
    callthreshold_weaponnoMinimum weapon probability to generate a callback. Should be a float between 0 and 1. Default is 0.5.
    callthreshold_alcoholnoMinimum alcohol probability to generate a callback. Should be a float between 0 and 1. Default is 0.5.
    callthreshold_drugsnoMinimum drugs probability to generate a callback. Should be a float between 0 and 1. Default is 0.5.

    The moderation engine will send a POST request to the callback URL each time a frame is detected with nudity_raw or nudity_partial levels above the defined thresholds. See below for more details.

    List of models

    The models string is a comma-separated list of the models you want to apply. The string denominations for each model is:

    To apply all models, the models parameter should therefore be nudity, wad, properties, face, type, celebrities, face-attributes, scam

    Response

    Example response

    {
        "status": "success",
        "request": {
            "id": "req_1ML249NoEZ8j12op9Lipg",
            "timestamp": 1508774201.3177
        },
        "media": {
            "id": "med_1ML2wKmVgucuNPBN6xT33",
            "uri": "https://sightengine.com/assets/stream/examples/funfair.mp4"
        },
        "callback": "https://yourdomain.com/your/callback/path",
        "callthreshold_nudity_raw": 0.2,
        "callthreshold_nudity_partial": 0.5,
        "callthreshold_weapon": 0.5,
        "callthreshold_alcohol": 0.5,
        "callthreshold_drugs": 0.5
    }
    

    This request will return a JSON response containing the following parameters:

    ParameterTypeDescription
    statusstring"success" if the request was successfully handled
    requestobjectJSON dictionary containing the request ID and timestamp
    mediaobjectJSON dictionary containing the media ID and URI
    callbackstringcallback URL where events will be posted
    callthreshold_nudity_rawfloat raw nudity threshold that will generate an event and be posted back to the callback
    callthreshold_nudity_partialfloat partial nudity threshold that will generate an event and be posted back to the callback
    callthreshold_weaponfloat weapon threshold that will generate an event and be posted back to the callback
    callthreshold_alcoholfloat alcohol threshold that will generate an event and be posted back to the callback
    callthreshold_drugsfloat drugs threshold that will generate an event and be posted back to the callback

    Results

    Once you have submitted a video stream and received a 200 HTTP status code, our Moderation Engine will start consuming the stream and will assign a moderation score to relevant frames and send moderation results to your callback URL.

    To avoid sending too many callback events, the engine will send callbacks only when one of the following happens:

    Callback content

    Example response

    {
       "media": {
           "id": "med_1N0OMfhDR6lkfa8uzgLop", "uri": "https://sightengine.com/assets/stream/examples/funfair.mp4"
        },
        "request": "req_1N0ONgcBn6j5WozgPM0Es",
        "data": {
            "status": "finished",
            "started": 1508832872.0789,
            "frames": [ {
                "info": {
                    "position": 0, "id": "med_1N0OMfhDR6lkfa8uzgLop_1"
                },
                "alcohol": 0.003,
                "drugs": 0.003,
                "nudity": {
                    "raw": 0.04187, "safe": 0.949647, "partial": 0.008483
                },
                "weapon": 0.003,
                "face": {
                    "single": 0.166772, "multiple": 0.056846
                },
                "faces": []
            },
            {
                "info": {
                    "position": 1000, "id": "med_1N0OMfhDR6lkfa8uzgLop_2"
                },
                "alcohol": 0.003,
                "drugs": 0.003,
                "nudity": {
                    "raw": 0.04658, "safe": 0.943894, "partial": 0.009526
                },
                "weapon": 0.002,
                "face": {
                    "single": 0.165451, "multiple": 0.057799
                },
                "faces": []
            }
    
         ],
         "last_update": 1508832873.1822,
         "operations": 2
      }
    }
    

    Callbacks are sent as POST requests with a Content-Type:application/json, all data being sent within this JSON.

    ParameterTypeDescription
    mediaobjecta JSON dictionary describing the media (id and uri)
    requeststringid of the request that generated this event
    dataobjecta JSON dictionary describing the current live moderation results. See below for more details.

    The data object has the following content:

    ParameterTypeDescription
    statusstringongoing if the stream consumption is still on-going, finished if the consumption is finished or failure if an error occurred. A status of finished means that the moderation has finished and there will not be anymore updates
    startedfloattimestamp of the start of the consumption of the stream. If the stream is a live stream, this is useful since it means that frames before this timestamp have not been moderated
    last_updatefloattimestamp of the last update to the moderation result
    framesarrayarray of moderation objects. Each moderation object refers to a specific frame. Objects are ordered in chronological order and begin at the stream consumption start (which may differ from the stream start if the stream is realtime and started before moderation was launched). Each frame has an id and a position (in milliseconds) set in the info object and the moderation probabilities set in the nudity object.
    operationsint number of operations counted for this stream at this stage

    Callback Recommendations

    Acknowledging receipt

    To acknowledge receipt of a callback, your endpoint should return a 2xx HTTP status code. Any other information returned in the request headers or request body is ignored. All response codes outside this range, including 3xx codes, will indicate to Sightengine that you did not receive the callback. This does mean that a URL redirection or a "Not Modified" response will be treated as a failure.

    If your callback script performs complex logic, or makes network calls, it's possible the script would timeout before Sightengine sees its complete execution. For that reason, you may want to have your callback endpoint immediately acknowledge receipt by returning a 2xx HTTP status code, and then perform the rest of its duties.

    Verifying callbacks

    As an extra security measure, you should check that the media id value returned in the callback matches the media id returned in the initial API response. This is can be helpful if you have several streams moderated at the same time and need to verify what media each callback refers to.

    HTTPS

    If you use an HTTPS URL for your callback endopint, please make sure that your server is correctly configured to support HTTPS with a valid server certificate. Sightengine will valide that the connection to your server is secure before sending the data.

    Idempotency

    Keep in mind that your callback may occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent.

    Feedback

    GET https://api.sightengine.com/1.0/feedback.json
    POST https://api.sightengine.com/1.0/feedback.json
    

    If you ever come across misclassifications, you can report them.

    Image classes

    In order to report a misclassification, you need to report the image that was misclassified, along with the correct class of the image.

    For each model, there are different classes that you may report. Here are the details:

    The nudity model has 6 classes:

    The wad model has 6 classes:

    The text model has 3 classes:

    The offensive model has 2 classes:

    The scam model has 2 classes:

    The gender model has 2 classes:

    The minor model has 2 classes:

    The celebrities model has 2 classes:

    The face model has 3 classes:

    The type model has 2 classes:

    Request arguments (GET)

    Example request

    # Example 1: a safe image wrongly classified as containing nudity
    curl -X GET \
      'https://api.sightengine.com/1.0/feedback.json?model=nudity&class=safe&url=http://example.com/yourimage.jpg&api_user={api_user}&api_secret={api_secret}'
    
    # Example 2: an image that contains a weapon that was not properly identified
    curl -X GET \
      'https://api.sightengine.com/1.0/feedback.json?model=wad&class=weapons&url=http://example.com/yourimage.jpg&api_user={api_user}&api_secret={api_secret}'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    
    # Example 1: a safe image wrongly classified as containing nudity
    client.feedback("nudity","safe", "http://example.com/yourimage.jpg")
    # Example 2: an image that contains a weapon that was not properly identified
    client.feedback("wad","weapons", "http://example.com/yourimage.jpg")
    
    sightengine.feedback("nudity","safe", "http://example.com/yourimage.jpg").then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    
    // Example 1: a safe image wrongly classified as containing nudity
    $client->feedback("nudity","safe", "http://example.com/yourimage.jpg");
    
    // Example 2: an image that contains a weapon that was not properly identified
    $client->feedback("wad","weapons", "http://example.com/yourimage.jpg");
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    urlyesPublic URL to the image to be moderated
    modelyes Model for which you want to perform a correction. Could be nudity, face, type, wad, celebrities
    classyes The correct class for this image. For the nudity model, possible classes would be raw, partial and safe

    Request arguments (POST)

    Example request

    curl -X POST 'https://api.sightengine.com/1.0/feedback.json' \
    -F 'api_user={api_user}' \
    -F 'api_secret={api_secret}' \
    -F 'model=nudity' \
    -F 'class=safe' \
    -F 'media=@/path/to/local/file.jpg'
    
    from sightengine.client import SightengineClient
    
    client = SightengineClient("{api_user}", "{api_secret}")
    client.feedback("nudity","safe", "/full/path/to/image.jpg")
    
    sightengine.feedback("nudity","safe", "/full/path/to/image.jpg").then(function(result) {
      // read the output (result)
    }).catch(function(err) {
      // handle the error
    });
    
    <?php
    use \Sightengine\SightengineClient;
    
    $client = new SightengineClient('{api_user}', '{api_secret}');
    
    $client->feedback("nudity","safe", "/full/path/to/image.jpg");
    
    ParameterRequiredDescription
    api_useryesYour API user
    api_secretyesYour API secret
    mediayesThe image (local file) to be moderated
    modelyes Model for which you want to perform a correction. Could be nudity, face, type
    classyes The correct class for this image. For the nudity model, possible classes would be raw, partial and safe

    Response

    Example response

    {
      "status": "success",
      "request": {
        "id": "req_VjyxevVQYXQZ1HMbnwtn",
        "timestamp": 1471762434.0244,
        "operations": 0
      },
      "media": {
        "id": "med_KWmB2GQZ29N4MVpVdq5K",
        "uri": "https://sightengine.com/assets/img/examples/example2.jpg"
      },
      "message": "Thank you!"
    }
    

    This request will return a JSON response containing the following parameters:

    ParameterTypeDescription
    statusstringsuccess if the request was successfully handled, failure otherwise
    requestobjecta JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed)
    mediaobjecta JSON dictionary describing the media (id and uri)

    Errors

    Example response

    {
      "status": "failure",
      "request": {
        "id": "req_t0OtSYcMHup3KrstGElG",
        "timestamp": 1471871564.1513,
        "operations": 0
      },
      "error": {
        "type": "credentials_error",
        "code": 1,
        "message": "Incorrect API user or API secret"
      }
    }
    

    The API returns conventional HTTP response codes. 2xx status codes indicate that the request was properly handled, while 4xx status codes indicate that the API was not correctly used (e.g. invalid API secret key, submitted file is not a valid image etc...).

    Error messages can be detected by the fact that:

    More information on the nature of the error can be found through the error object. This object contains the following parameters:

    ParameterTypeDescription
    typestringType of the error. Common types are credentials_error, media_error, usage_limit, plan_error, argument_error
    codeintSightengine-specific code describing the error. Useful if you need to communicate with our support.
    messagestringHuman-readable description of the error.