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:
- Adding new API resources
- Adding new optional parameters to existing API calls
- Adding new properties to existing API responses
- Changing the order of properties in existing API responses
- Changing the length of returned strings (such as ids and codes)
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:
- Nudity detection (i.e. detect adult or suggestive content)
- Weapons/Alcohol/Drugs detection
- Offensive content detection (i.e. detect offensive gestures or hate symbols)
- OCR-based Text moderation (i.e. detect profanity or personal information such as email addresses and phone numbers in images)
- QR code Moderation
- Artificial Text detection
- Face/People detection (i.e. detect if the image contains a person or several people or nobody, along with the positions of those faces)
- Face Attributes detection (get the age group and gender, determine if a face is covered with sunglasses...)
- Celebrity detection
- Image type detection (i.e. detect if the image is a natural photograph or an illustration)
- Gore and Graphic Violence detection
- Image Properties (i.e. determine the quality of an image along with its main colors)
- Scammer detection
For more details on each model, please head to our Model Reference
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 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:
| Parameter | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled, failure otherwise |
| request | object | a JSON dictionary containing meta-data describing the request (request id, timestamp and number of operations performed) |
| media | object | a 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:
- Raw nudity, e.g. images containing X-rated content, genitals, breasts etc.
- Partial nudity, e.g. images containing women in bikini, lingerie, bare-chested male, cleavages, miniskirts. This content may be OK for some uses and may be inacceptable in other contexts, which is why we handle them separately.
- No nudity, also referred to as "safe"
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:
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| url | yes | Public 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:
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| media | yes | The 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 attributes:
| Attribute | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled, failure otherwise |
| request | object | a JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed) |
| nudity | object | a JSON dictionary containing information on the nudity content of the image, see below for more |
| media | object | a JSON dictionary describing the image received |
The Nudity object contains the following Attributes:
| Attribute | Type | Description |
|---|---|---|
| raw | float | the probability that the image contains raw nudity |
| partial | float | the probability that the image contains partial nudity |
| partial_tag | string | if the image contains partial nudity, this string will describe the type of partial nudity. Possible values are bikini, lingerie, cleavage, chest, miniskirt. Other values may be added in future evolutions so make sure you gracefuly handle them. |
| safe | float | the 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');
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| url | yes | Public 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);
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| media | yes | The 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 attributes:
| Attribute | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled, failure otherwise |
| request | object | a JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed) |
| weapon | float | the probability that the image contains weapons |
| alcohol | float | the probability that the image contains alcohol |
| drugs | float | the probability that the image contains drugs |
| media | object | a 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');
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| url | yes | Public 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);
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| media | yes | The 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 attributes:
| Attribute | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled, failure otherwise |
| request | object | a JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed) |
| faces | object | a JSON dictionary containing information on the presence of people / faces in the image, see below for more |
| media | object | a JSON dictionary describing the image received |
The Face object contains the following attributes:
| Attribute | Type | Description |
|---|---|---|
| x1 | float | The bounding box's left X coordinate (expressed as a share of image width in the range [0,1]) |
| y1 | float | The bounding box's top Y coordinate (expressed as a share of image height in the range [0,1]) |
| x2 | float | The bounding box's right X coordinate (expressed as a share of image width in the range [0,1]) |
| y2 | float | The bounding box's bottom Y coordinate (expressed as a share of image height in the range [0,1]) |
| features | object | Positioning of the elements of the face (expressed as a share of image dimensions, in the range [0,1]) |
| attributes | object | Description of the face attributes (see below) |
The Face Attributes object contains the following attributes:
| Attribute | Type | Description |
|---|---|---|
| female | float | probability that the face belongs to a female |
| male | float | probability that the face belongs to a male |
| minor | float | probability 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');
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| url | yes | Public 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);
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| media | yes | The 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 attributes:
| Attribute | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled, failure otherwise |
| request | object | a JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed) |
| faces | object | a JSON dictionary containing information on the presence of people / faces in the image, see below for more |
| media | object | a JSON dictionary describing the image received |
The Face object contains the following attributes:
| Attribute | Type | Description |
|---|---|---|
| x1 | float | The bounding box's left X coordinate (expressed as a share of image width in the range [0,1]) |
| y1 | float | The bounding box's top Y coordinate (expressed as a share of image height in the range [0,1]) |
| x2 | float | The bounding box's right X coordinate (expressed as a share of image width in the range [0,1]) |
| y2 | float | The bounding box's bottom Y coordinate (expressed as a share of image height in the range [0,1]) |
| features | object | Positioning of the elements of the face (expressed as a share of image dimensions, in the range [0,1]) |
| celebrity | object | List of celebrities matching this face (could be empty) |
The celebrity list contains objects with the following attributes:
| Atribute | Type | Description |
|---|---|---|
| name | string | Name of the matching celebrity |
| prob | float | Probability 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');
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| url | yes | Public 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);
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| media | yes | The 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 attributes:
| Attribute | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled, failure otherwise |
| request | object | a JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed) |
| faces | object | a JSON dictionary containing information on the presence of people / faces in the image, see below for more |
| scam | object | a JSON dictionary containing the probability that there is a scammer on the image |
| media | object | a JSON dictionary describing the image received |
The Face object contains the following Attributes:
| Attribute | Type | Description |
|---|---|---|
| x1 | float | The bounding box's left X coordinate (expressed as a share of image width in the range [0,1]) |
| y1 | float | The bounding box's top Y coordinate (expressed as a share of image height in the range [0,1]) |
| x2 | float | The bounding box's right X coordinate (expressed as a share of image width in the range [0,1]) |
| y2 | float | The bounding box's bottom Y coordinate (expressed as a share of image height in the range [0,1]) |
| features | object | Positioning 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');
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| url | yes | Public 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);
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| media | yes | The 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 attributes:
| Attribute | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled, failure otherwise |
| request | object | a JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed) |
| type | object | a JSON dictionary containing information on the type of the image |
| media | object | a JSON dictionary describing the image received |
The Type object contains the following Attributes:
| Attribute | Type | Description |
|---|---|---|
| illustration | float | the probability that the image is an illustration |
| photo | float | the probability that the image is a natural photograph |
Text Moderation in Images
GET https://api.sightengine.com/1.0/check.json?models=text-content
POST https://api.sightengine.com/1.0/check.json?models=text-content
The Text Moderation for Images endpoint can help you determine if an image contains profanity, links, social accounts or personal information such as email addresses, phone numbers and more.
Request arguments (GET)
Example request
curl -X GET \
'https://api.sightengine.com/1.0/check.json?models=text-content&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-content').set_url('https://sightengine.com/assets/img/examples/example2.jpg')
var sightengine = require('sightengine')("{api_user}", "{api_secret}");
sightengine.check(['text-content']).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-content'])->set_url('https://sightengine.com/assets/img/examples/example2.jpg');
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| url | yes | Public URL to the image to be moderated |
| opt_lang | no | Language to be used for profanity moderation (ISO 639-1 code), default is en (english) |
| opt_countries | no | Comma separated list of country codes for phone number detection (ISO 3166-1 alpha-2 code), default is us,gb,fr (United States, United Kingdom, France) |
| opt_textlist | no | ID of the custom textlist (blacklist, whitelist) to customize moderation |
Available languages (set through the opt_lang parameter) are:
- English (default), iso code
en - Chinese (simplified or traditional), iso code
zh - Dutch, iso code
nl - French, iso code
fr - German, iso code
de - Italian, iso code
it - Portuguese, iso code
pt - Spanish, iso code
es - Swedish, iso code
sv
Available countries (set through the opt_countries parameter) are:
- Brazil, iso code
br - France, iso code
fr - Germany, iso code
de - Italy, iso code
it - Spain, iso code
es - United Kingdom, iso code
gb - United States, iso code
us
Request arguments (POST)
Example request
curl -X POST 'https://api.sightengine.com/1.0/check.json' \
-F 'models=text-content' \
-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-content').set_file('/path/to/local/file.jpg')
# binary image
client = SightengineClient("{api_user}", "{api_secret}")
output = client.check('text-content').set_bytes(binary_image)
var sightengine = require('sightengine')("{api_user}", "{api_secret}");
sightengine.check(['text-content']).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-content']).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-content'])->set_file('/path/to/local/file.jpg');
// binary image
$client = new SightengineClient('{api_user}', '{api_secret}');
$output = $client->check(['text-content'])->set_bytes($binary_image);
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| media | yes | The image (local file) to be moderated |
| opt_lang | no | Language to be used for profanity moderation (ISO 639-1 code), default is en (english) |
| opt_countries | no | Comma separated list of country codes for phone number detection (ISO 3166-1 alpha-2 code), default is us,gb,fr (United States, United Kingdom, France) |
| opt_textlist | no | ID of the custom textlist (blacklist, whitelist) to customize moderation |
Available languages (set through the opt_lang parameter) are:
- English (default), iso code
en - Spanish, iso code
es - French, iso code
fr - German, iso code
de - Chinese, iso code
zh
Available countries (set through the opt_countries parameter) are:
- Brazil, iso code
br - France, iso code
fr - Germany, iso code
de - Italy, iso code
it - Spain, iso code
es - United Kingdom, iso code
gb - United States, iso code
us
Response
Example response
{
"status": "success",
"request": {
"id": "req_23WtCoW0Q6lPzGdPdjJjZ",
"timestamp": 1512737637.4493,
"operations": 1
},
"text": {
"profanity": [
{
"type": "sexual",
"match": "f*ck"
}
],
"personal": [
{
"type": "phone_number_us",
"match": "+1 800 232 2322"
}
],
"social": [],
"link": [],
"ignored_text": false
},
"media": {
"id": "med_23WtF44uHImHV66pOcnUU",
"uri": "https://example.com/example-image.jpg"
}
}
This request will return a JSON response containing the following attributes:
| Attribute | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled, failure otherwise |
| request | object | a JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed) |
| text | object | a JSON dictionary containing information on the presence of profanity or personal information in the image (see below) |
| media | object | a JSON dictionary describing the image received |
The Text object contains the following Attributes:
| Attribute | Type | Description |
|---|---|---|
| profanity | array | an array of JSON dictionaries. Each dictionary describes the type of profanity and the actual text match |
| personal | array | an array of JSON dictionaries. Each dictionary describes the type of personal information and the actual text match |
| link | array | an array of JSON dictionaries. Each dictionary describes the link found |
| social | array | an array of JSON dictionaries. This array lists any mentions of social accounts |
| ignored_text | boolean | true if the image was found to contain dense text, and was thus ignored |
The profanity, personal and link array contains JSON dictionaries with the following attributes:
| Attribute | Type | Description |
|---|---|---|
| type | string | type of profanity or personal detail found. Please see below for the list of types |
| match | string | the word or string that was found to be objectionable |
The type string can be used to obtain more details on the type of objectionable content found. Possible values depend on the category:
- Profanity:
sexual,insult,discriminatory,inappropriate,other_profanity - Personal Details:
email,ipv4,ipv6,phone_number_us,phone_number_uk,phone_number_fr,ssn - Links/URLS:
url
Embedded 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 (also called embedded 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');
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| url | yes | Public 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);
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| media | yes | The 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 attributes:
| Attribute | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled, failure otherwise |
| request | object | a JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed) |
| text | object | a JSON dictionary containing information on the presence of text in the image |
| media | object | a JSON dictionary describing the image received |
The Text object contains the following Attributes:
| Attribute | Type | Description |
|---|---|---|
| has_artificial | float | the probability that the image contains artificial text |
| has_natural | float | the probability that the image contains natural text |
| boxes | array | an 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:
| Attribute | Type | Description |
|---|---|---|
| x1 | float | The bounding box's left X coordinate (expressed as a share of image width in the range [0,1]) |
| y1 | float | The bounding box's top Y coordinate (expressed as a share of image height in the range [0,1]) |
| x2 | float | The bounding box's right X coordinate (expressed as a share of image width in the range [0,1]) |
| y2 | float | The bounding box's bottom Y coordinate (expressed as a share of image height in the range [0,1]) |
| label | string | The type of text present in the box (for instance text-artificial or text-natural) |
QR Code Moderation in Images
GET https://api.sightengine.com/1.0/check.json?models=qr-content
POST https://api.sightengine.com/1.0/check.json?models=qr-content
The QR Code Moderation for Images endpoint can help you determine if an image contains QR codes with profanity, links, social accounts or personal information such as email addresses, phone numbers and more.
Request arguments (GET)
Example request
curl -X GET \
'https://api.sightengine.com/1.0/check.json?models=qr-content&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('qr-content').set_url('https://sightengine.com/assets/img/examples/example2.jpg')
var sightengine = require('sightengine')("{api_user}", "{api_secret}");
sightengine.check(['qr-content']).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(['qr-content'])->set_url('https://sightengine.com/assets/img/examples/example2.jpg');
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| url | yes | Public URL to the image to be moderated |
| opt_lang | no | Language to be used for profanity moderation (ISO 639-1 code), default is en (english) |
| opt_countries | no | Comma separated list of country codes for phone number detection (ISO 3166-1 alpha-2 code), default is us,gb,fr (United States, United Kingdom, France) |
| opt_textlist | no | ID of the custom textlist (blacklist, whitelist) to customize moderation |
Available languages (set through the opt_lang parameter) are:
- English (default), iso code
en - Chinese (simplified or traditional), iso code
zh - Dutch, iso code
nl - French, iso code
fr - German, iso code
de - Italian, iso code
it - Portuguese, iso code
pt - Spanish, iso code
es - Swedish, iso code
sv
Available countries (set through the opt_countries parameter) are:
- Brazil, iso code
br - France, iso code
fr - Germany, iso code
de - Italy, iso code
it - Spain, iso code
es - United Kingdom, iso code
gb - United States, iso code
us
Request arguments (POST)
Example request
curl -X POST 'https://api.sightengine.com/1.0/check.json' \
-F 'models=qr-content' \
-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('qr-content').set_file('/path/to/local/file.jpg')
# binary image
client = SightengineClient("{api_user}", "{api_secret}")
output = client.check('qr-content').set_bytes(binary_image)
var sightengine = require('sightengine')("{api_user}", "{api_secret}");
sightengine.check(['qr-content']).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(['qr-content']).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(['qr-content'])->set_file('/path/to/local/file.jpg');
// binary image
$client = new SightengineClient('{api_user}', '{api_secret}');
$output = $client->check(['qr-content'])->set_bytes($binary_image);
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| media | yes | The image (local file) to be moderated |
| opt_lang | no | Language to be used for profanity moderation (ISO 639-1 code), default is en (english) |
| opt_countries | no | Comma separated list of country codes for phone number detection (ISO 3166-1 alpha-2 code), default is us,gb,fr (United States, United Kingdom, France) |
| opt_textlist | no | ID of the custom textlist (blacklist, whitelist) to customize moderation |
Available languages (set through the opt_lang parameter) are:
- English (default), iso code
en - Chinese (simplified or traditional), iso code
zh - Dutch, iso code
nl - French, iso code
fr - German, iso code
de - Italian, iso code
it - Portuguese, iso code
pt - Spanish, iso code
es - Swedish, iso code
sv
Available countries (set through the opt_countries parameter) are:
- Brazil, iso code
br - France, iso code
fr - Germany, iso code
de - Italy, iso code
it - Spain, iso code
es - United Kingdom, iso code
gb - United States, iso code
us
Response
Example response
{
"status": "success",
"request": {
"id": "req_23WtCoW0Q6lPzGdPdjJjZ",
"timestamp": 1512737637.4493,
"operations": 1
},
"qr": {
"profanity": [
{
"type": "sexual",
"match": "f*ck"
}
],
"personal": [
{
"type": "phone_number_us",
"match": "+1 800 232 2322"
}
],
"social": [],
"link": []
},
"media": {
"id": "med_23WtF44uHImHV66pOcnUU",
"uri": "https://example.com/example-image.jpg"
}
}
This request will return a JSON response containing the following attributes:
| Attribute | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled, failure otherwise |
| request | object | a JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed) |
| text | object | a JSON dictionary containing information on the presence of profanity or personal information in the image (see below) |
| media | object | a JSON dictionary describing the image received |
The Text object contains the following Attributes:
| Attribute | Type | Description |
|---|---|---|
| profanity | array | an array of JSON dictionaries. Each dictionary describes the type of profanity and the actual text match |
| personal | array | an array of JSON dictionaries. Each dictionary describes the type of personal information and the actual text match |
| link | array | an array of JSON dictionaries. Each dictionary describes the link found |
| social | array | an array of JSON dictionaries. This array lists any mentions of social accounts |
The profanity, personal and link array contains JSON dictionaries with the following attributes:
| Attribute | Type | Description |
|---|---|---|
| type | string | type of profanity or personal detail found. Please see below for the list of types |
| match | string | the word or string that was found to be objectionable |
The type string can be used to obtain more details on the type of objectionable content found. Possible values depend on the category:
- Profanity:
sexual,insult,discriminatory,inappropriate,other_profanity - Personal Details:
email,ipv4,ipv6,phone_number_us,phone_number_uk,phone_number_fr,ssn - Links/URLS:
url
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');
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| url | yes | Public 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);
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| media | yes | The 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 attributes:
| Attribute | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled, failure otherwise |
| request | object | a JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed) |
| offensive | object | a JSON dictionary containing information on the offensive content of the image |
| media | object | a JSON dictionary describing the image received |
The offensive object contains the following Attributes:
| Attribute | Type | Description |
|---|---|---|
| prob | float | the probability that the image contains offensive content |
| boxes | array | an 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:
| Attribute | Type | Description |
|---|---|---|
| x1 | float | The bounding box's left X coordinate (expressed as a share of image width in the range [0,1]) |
| y1 | float | The bounding box's top Y coordinate (expressed as a share of image width in the range [0,1]) |
| x2 | float | The bounding box's right X coordinate (expressed as a share of image width in the range [0,1]) |
| y2 | float | The bounding box's bottom Y coordinate (expressed as a share of image width in the range [0,1]) |
| label | string | the type of offensive content detected in the given bounding box. The label can be: swastika, ssbolts, confederate, kkk, middlefinger, isisflag, ironcross, sonnenrad, sturmabteilung... See the model page for a full list |
| prob | float | the probability level for the given bounding box and its label |
Gore and Graphic content
GET https://api.sightengine.com/1.0/check.json?models=gore
POST https://api.sightengine.com/1.0/check.json?models=gore
This endpoint is useful to determine if an image contains graphic violence or gore imagery such as wounds, blood or human skulls.
Request arguments (GET)
Example request
curl -X GET \
'https://api.sightengine.com/1.0/check.json?models=gore&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('gore').set_url('https://sightengine.com/assets/img/examples/example2.jpg')
var sightengine = require('sightengine')("{api_user}", "{api_secret}");
sightengine.check(['gore']).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(['gore'])->set_url('https://sightengine.com/assets/img/examples/example2.jpg');
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| url | yes | Public 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=gore' \
-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('gore').set_file('/path/to/local/file.jpg')
# binary image
client = SightengineClient("{api_user}", "{api_secret}")
output = client.check('gore').set_bytes(binary_image)
var sightengine = require('sightengine')("{api_user}", "{api_secret}");
sightengine.check(['gore']).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(['gore']).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(['gore'])->set_file('/path/to/local/file.jpg');
// binary image
$client = new SightengineClient('{api_user}', '{api_secret}');
$output = $client->check(['gore'])->set_bytes($binary_image);
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| media | yes | The image (local file) to be moderated |
Response
Example response
{
"status": "success",
"request": {
"id": "req_2e254SVW693XMTtD3MvlA",
"timestamp": 1515064879.7939,
"operations": 1
},
"gore": {
"prob": 0.92529,
},
"media": {
"id": "med_2e256k0jvwwnQsWYF0H5x",
"uri": "https://sightengine.com/assets/img/examples/example2.jpg"
}
}
This request will return a JSON response containing the following attributes:
| Attribute | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled, failure otherwise |
| request | object | a JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed) |
| gore | object | a JSON dictionary containing information on the gore content of the image |
| media | object | a JSON dictionary describing the image received |
The gore object contains the following Attributes:
| Attribute | Type | Description |
|---|---|---|
| prob | float | the probability that the image contains gore content or graphic violence |
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');
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| url | yes | Public 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);
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| media | yes | The 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 attributes:
| Attribute | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled, failure otherwise |
| request | object | a JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed) |
| sharpness | float | a value between 0 (very blurry) and 1 (very sharp) |
| contrast | float | a value between 0 (low contrast) and 1 (high contrast) |
| brightness | float | a value between 0 (very dark) and 1 (very bright) |
| colors | object | a JSON dictionary describing the colors of the image received |
| media | object | a JSON dictionary describing the image received |
The Colors object contains the following Attributes:
| Attribute | Type | Description |
|---|---|---|
| dominant | object | dominant color, defined by its RGB values and HEX code |
| accent | array | array of accent colors |
| other | array | array 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');
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| models | yes | String list of models (see below for details) |
| url | yes | Public 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);
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| models | yes | String list of models (see below for details) |
| media | yes | The 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:
nudityfor the nudity detectionwadfor the weapons-alcohol-drugs detectionoffensivefor offensive detectiongorefor graphic violence and gore detectionpropertiesfor image propertiesfacefor face detectionface-attributesfor face-attributes detectioncelebritiesfor celebrity detectiontypefor type detectionscamfor scammers detectiontextfor embedded text detectiontext-contentfor text moderation in images (profanity and PII detection)
Head to the Model Page for more details on all the available models.
To apply all models, the models parameter should therefore be nudity, wad, offensive, gore, properties, face, face-attributes, celebrities, type, scam, text, text-content
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 Attributes, depending on which models you requested:
| Attribute | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled, failure otherwise |
| request | object | a JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed) |
| weapon | float | the probability that the image contains weapons |
| alcohol | float | the probability that the image contains alcohol |
| drugs | float | the probability that the image contains drugs |
| nudity | object | an object containing information on the nudity content of the image |
| type | object | a JSON dictionary containing information on the type of the image |
| faces | object | a JSON dictionary containing information on the presence of faces / celebrities in the image |
| sharpness | float | a value between 0 (very blurry) and 1 (very sharp) |
| contrast | float | a value between 0 (low contrast) and 1 (high contrast) |
| brightness | float | a value between 0 (very dark) and 1 (very bright) |
| scam | object | the 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 | object | a JSON dictionary with the probability that the image contains a celebrity |
| colors | object | a JSON dictionary describing the colors of the image received |
| media | object | a JSON dictionary describing the image received |
Image Moderation Workflows
Image Moderation Workflows are an easy way to create your own custom rules and actions, directly from your online dashboard.
The standard API endpoint require that you specify in each request what models (moderation filters) should be applied and then analyze the results and confidence thresholds to decide how each media should be treated.
Workflows remove this complexity by letting you define your own rules once and then letting our engine apply those rules and decide how each image should be treated: accept or reject.
To create a new workflow, navigate to the Workflow page of your dashboard. You will be able to select the rules that should be applied, and what actions should be taken based on those rules: ACCEPT or REJECT.
Request arguments
Example request
curl -X POST 'https://api.sightengine.com/1.0/check-workflow.json' \
-F 'api_user={api_user}' \
-F 'api_secret={api_secret}' \
-F 'workflow={workflow_id}' \
-F 'media=@/path/to/local/image.jpg'
# this example uses requests
import requests
import json
params = {
'workflow': '{workflow_id}',
'api_user': '{api_user}',
'api_secret': '{api_secret}'
}
files = {'media': open('/local/path/to/image', 'rb')}
r = requests.post('https://api.sightengine.com/1.0/check-workflow.json', files=files, data=params)
output = json.loads(r.text)
// this example uses axios and form-data
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
data = new FormData();
data.append('media', fs.createReadStream('/local/path/to/image'));
data.append('workflow', '{workflow_id}');
data.append('api_user', '{api_user}');
data.append('api_secret', '{api_secret}');
axios({
method: 'post',
url:'https://api.sightengine.com/1.0/check-workflow.json',
data: data,
headers: data.getHeaders()
})
.then(function (response) {
// on success: handle response
console.log(response.data);
})
.catch(function (error) {
// handle error
if (error.response) console.log(error.response.data);
else console.log(error.message);
});
$params = array(
'media' => new CurlFile('/local/path/to/image'),
'workflow' => '{workflow_id}',
'api_user' => '{api_user}',
'api_secret' => '{api_secret}',
);
// this example uses cURL
$ch = curl_init('https://api.sightengine.com/1.0/check-workflow.json');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
$response = curl_exec($ch);
curl_close($ch);
$output = json_decode($response, true);
Once you have created a Workflow in your online dashboard, copy your workflow id (starts with wfl_) and use it to perform requests.
You can create multiple workflows. This is useful for instance if you have different categories of images that need to be treated differently, or if you want to test different rules.
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| workflow | yes | Id of your workflow. Starts with wfl_ |
| media | yes | The image (local file) to be moderated |
Response
Example response
{
"status": "success",
"request": {
"id": "req_81pP7cRqEvbdZ457WNQ2O",
"timestamp": 1597952947.216626,
"operations": 1
},
"summary": {
"action": "reject",
"reject_prob": 0.82,
"reject_reason": [
{
"text": "Alcohol"
}
]
},
"weapon": 0.0055,
"alcohol": 0.819,
"drugs": 0.001,
"workflow": {
"id": "wfl_81jOFDxdI8un4sm38y4Kw"
}
}
This request will return a JSON response containing part of the following Attributes, depending on which models you requested:
| Attribute | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled, failure otherwise |
| request | object | a JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed) |
| summary | object | a JSON dictionary describing the moderation decision |
| media | object | a 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 can either submit the video or stream's URL to the Moderation API, or send the raw bytes through a direct upload to the API. Our Moderation Engine will then start consuming this video stream and moderate it in real-time.
Introduction
You can perform either sequential or continuous Video Moderation.
- Sequential Moderation is simple and easy: the Moderation result is provided directly in the response to your API request. Sequential Moderation is only available for videos that are less than 1 minute long.
- Continuous Moderation is available for any video or stream. Moderation results are provided through a so-called callback mechanism. You define a callback URL and the Moderation Engine will send back moderation events to that URL in realtime.
Sharing the video with the API is done either by sending a URL pointing to the video or uploading the raw bytes of the video.
- Raw Bytes: this works for any video that is less than 50MB in size. You upload the video to the API and it gets moderated once the upload is over. This is best for static videos (i.e. not live videos) that are less than 50MB in size
- URL: this works for any video. Instead of sending the raw bytes to the API you send a URL. The Sightengine API will then retrieve the video from this URL and moderate it in real-time as it is being consumed. This is best for live videos and for videos that are long and/or big. If you cannot make the video accessible through a public URL and need to set up some type of authentication or request filtering to grant access to our API, please let us know: support@sightengine.com
Sightengine can consume videos and streams delivered over all major protocols: HTTP Live Streaming (HLS) http, https and also rtmp, rtsp, rtp... Sightengine further 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).
Sequential Moderation
Via raw byte upload
POST https://api.sightengine.com/1.0/video/check-sync.json
The first step to moderate a video stream is to submit the video to the API.
Request arguments
Example request
curl -X POST 'https://api.sightengine.com/1.0/video/check-sync.json' \
-F 'api_user={api_user}' \
-F 'api_secret={api_secret}' \
-F 'models=nudity,wad,faces,face-attributes,celebrities' \
-F 'media=@/path/to/local/video.mp4'
# this example uses requests
import requests
import json
params = {
# specify the models you want to apply
'models': 'nudity,wad,faces,face-attributes,celebrities',
'api_user': '{api_user}',
'api_secret': '{api_secret}'
}
files = {'media': open('/path/to/video', 'rb')}
r = requests.post('https://api.sightengine.com/1.0/video/check-sync.json', files=files, data=params)
output = json.loads(r.text)
// this example uses axios and form-data
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
data = new FormData();
data.append('media', fs.createReadStream('/path/to/video'));
// specify the models you want to apply
data.append('models', 'nudity,wad,faces,face-attributes,celebrities');
data.append('api_user', '{api_user}');
data.append('api_secret', '{api_secret}');
axios({
method: 'post',
url:'https://api.sightengine.com/1.0/video/check-sync.json',
data: data,
headers: data.getHeaders()
})
.then(function (response) {
// on success: handle response
console.log(response.data);
})
.catch(function (error) {
// handle error
if (error.response) console.log(error.response.data);
else console.log(error.message);
});
<?php
$params = array(
'media' => new CurlFile('/path/to/video'),
// specify the models you want to apply
'models' => 'nudity,wad,faces,face-attributes,celebrities',
'api_user' => '{api_user}',
'api_secret' => '{api_secret}',
);
// this example uses cURL
$ch = curl_init('https://api.sightengine.com/1.0/video/check-sync.json');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
$response = curl_exec($ch);
curl_close($ch);
$output = json_decode($response, true);
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| models | yes | String list of models (see below for details) |
| media | yes | The video (local file) to be moderated |
Via URL upload
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');
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| models | yes | String list of models (see below for details) |
| stream_url | yes | Public 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:
nudityfor the nudity detectionwadfor the weapons-alcohol-drugs detectionoffensivefor offensive content detectiongorefor graphic violence or gore detectionpropertiesfor video propertiesfacesfor face detection, face positions and face featuresface-attributesfor face-attributes detectioncelebritiesfor celebrity detectiontypefor type detectiontext-contentfor profanity or PII detection within text in the videotextfor embedded text detection
Head to the Model Page for more details on all the available models.
To apply all models, the models parameter should therefore be nudity, wad, offensive, gore, properties, faces, face-attributes, celebrities, type, text-content, text
Response
Example response
{
"status": "success",
"request": {
"id": "req_1ML249NoEZ8j12op9Lipg",
"timestamp": 1508774201.3177
},
"media": {
"id": "med_1ML2wKmVgucuNPBN6xT33",
"uri": "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 attributes:
| Attribute | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled |
| request | object | JSON dictionary containing the request ID and timestamp |
| media | object | JSON dictionary containing the media ID and URI |
| data | object | JSON 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.
Continuous Moderation
The first step to moderate a video stream is to submit the video stream to the API.
Via raw bytes upload
Request arguments
Example request
curl -X POST 'https://api.sightengine.com/1.0/video/check.json' \
-F 'api_user={api_user}' \
-F 'api_secret={api_secret}' \
-F 'models=nudity,wad,faces,face-attributes,celebrities' \
-F 'callback_url=https://yourdomain/yourcallback' \
-F 'media=@/path/to/local/video.mp4'
# this example uses requests
import requests
import json
params = {
# specify the models you want to apply
'models': 'nudity,wad,faces,face-attributes,celebrities',
# specify where you want to receive result callbacks
'callback_url': 'https://yourcallback/path',
'api_user': '{api_user}',
'api_secret': '{api_secret}'
}
files = {'media': open('/path/to/your/video.mp4', 'rb')}
r = requests.post('https://api.sightengine.com/1.0/video/check.json', files=files, data=params)
output = json.loads(r.text)
// this example uses axios and form-data
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
data = new FormData();
data.append('media', fs.createReadStream('/path/to/your/video.mp4'));
// specify the models you want to apply
data.append('models', 'nudity,wad,faces,face-attributes,celebrities');
// specify where you want to receive result callbacks
data.append('callback_url', 'https://yourcallback/path');
data.append('api_user', '{api_user}');
data.append('api_secret', '{api_secret}');
axios({
method: 'post',
url:'https://api.sightengine.com/1.0/video/check.json',
data: data,
headers: data.getHeaders()
})
.then(function (response) {
// on success: handle response
console.log(response.data);
})
.catch(function (error) {
// handle error
if (error.response) console.log(error.response.data);
else console.log(error.message);
});
<?php
$params = array(
'media' => new CurlFile('/path/to/your/video.mp4'),
// specify the models you want to apply
'models' => 'nudity,wad,faces,face-attributes,celebrities',
// specify where you want to receive result callbacks
'callback_url' => 'https://yourcallback/path',
'api_user' => '{api_user}',
'api_secret' => '{api_secret}',
);
// this example uses cURL
$ch = curl_init('https://api.sightengine.com/1.0/video/check.json');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
$response = curl_exec($ch);
curl_close($ch);
$output = json_decode($response, true);
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| models | yes | String list of models (see below for details) |
| media | yes | Video file to be moderated |
| callback_url | no | Callback URL where moderation events will be posted. If you don't specify a callback_url, then your account-level callback-url will be used. |
| max_duration | no | Max video duration in seconds. If the video is longer than this, moderation will stop once the corresponding timestamp is reached. The default value is 900 (15 minutes). |
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.
Via URL upload
GET https://api.sightengine.com/1.0/video/check.json
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=https://yourdomain/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');
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| models | yes | String list of models (see below for details) |
| stream_url | yes | Public URL to the video to be moderated (could be http, https, rtmp, rtsp, rtp...) |
| callback_url | no | Callback URL where moderation events will be posted. If you don't specify a callback_url, then your account-level callback-url will be used. |
| max_duration | no | Max video duration in seconds. If the video is longer than this, moderation will stop once the corresponding timestamp is reached. The default value is 900 (15 minutes). |
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:
nudityfor the nudity detectionwadfor the weapons-alcohol-drugs detectionoffensivefor offensive content detectiongorefor graphic violence or gore detectionpropertiesfor video propertiesfacesfor face detection, face positions and face featuresface-attributesfor face-attributes detectioncelebritiesfor celebrity detectiontypefor type detectiontext-contentfor profanity or PII detection within text in the videotextfor embedded text detection
Head to the Model Page for more details on all the available models.
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"
}
This request will return a JSON response containing the following attributes:
| Parameter | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled |
| request | object | JSON dictionary containing the request ID and timestamp |
| media | object | JSON dictionary containing the media ID and URI |
| callback | string | callback URL where events will be posted |
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:
- the video has been completely read and moderation is done
- an "interesting event" has been detected. One such event would be the presence of nudity. This is defined by setting threshold values on the nudity probabilities.
- an error was encountered after the initial request was closed
Callback content for Continuous Video Moderation
Example response
{
"media": {
"id": "med_1N0OMfhDR6lkfa8uzgLop", "uri": "https://sightengine.com/assets/stream/examples/funfair.mp4"
},
"request": "req_1N0ONgcBn6j5WozgPM0Es",
"data": {
"status": "finished",
"started": 1508832872.0789,
"progress": 1,
"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.
| Attribute | Type | Description |
|---|---|---|
| media | object | a JSON dictionary describing the media (id and uri) |
| request | string | id of the request that generated this event |
| data | object | a JSON dictionary describing the current live moderation results. See below for more details. |
The data object has the following content:
| Attribute | Type | Description |
|---|---|---|
| status | string | ongoing 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 |
| started | float | timestamp 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 |
| progress | float or null | progress of the job. 0 corresponds to the start, 0.5 to 50% progress and 1 to the end. If the duration of the video is not known beforehand, a null value is returned |
| last_update | float | timestamp of the last update to the moderation result |
| frames | array | array 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. |
| operations | int | 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.
Interacting with Continuous Video Moderation
Retrieve a Video Moderation Task and Result
Example request
curl -X GET -G 'https://api.sightengine.com/1.0/video/byid.json' \
-d 'api_user={api_user}' \
-d 'api_secret={api_secret}' \
-d 'id={media_id}'
# this example uses requests
import requests
import json
params = {
# {media_id} is the id of the media that is being moderated
# this id is given to you by the API when you perform a moderation request
'id': '{media_id}',
'api_user': '{api_user}',
'api_secret': '{api_secret}'
}
r = requests.get('https://api.sightengine.com/1.0/video/byid.json', params=params)
output = json.loads(r.text)
<?php
$params = array(
// {media_id} is the id of the media that is being moderated
// this id is given to you by the API when you perform a moderation request
'id' => '{media_id}',
'api_user' => '{api_user}',
'api_secret' => '{api_secret}',
);
// this example uses cURL
$ch = curl_init('https://api.sightengine.com/1.0/video/byid.json?'.http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$output = json_decode($response, true);
// this example uses axios
const axios = require('axios');
axios.get('https://api.sightengine.com/1.0/video/byid.json', {
params: {
'id': '{media_id}',
'api_user': '{api_user}',
'api_secret': '{api_secret}',
}
})
.then(function (response) {
// on success: handle response
console.log(response);
})
.catch(function (error) {
// handle error
if (error.response) console.log(error.response.data);
else console.log(error.message);
});
Retrieve the status of an on-going Moderation Task and the up-to-date moderation results.
This works with currently on-going Video Moderation Tasks as well as recent Video Moderation Tasks.
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| id | yes | Media id |
Example response
{
"status": "success",
"request": {
"id": "rtr_4I2naYrjEUcxwKDifC6nk",
"timestamp": 1550584530.3862,
"operations": 0
},
"output": {
"media": {
"id": "med_4I2nqWOMDsrCs7TNXbKTQ",
"uri": "video.mp4"
},
"request": "req_4I2nM80SPhlVRW1JaxYnw",
"data": {
"status": "ongoing",
"started": 1550584528.3224,
"progress": 0.42,
"last_update": 1550584529.6136,
"operations": 22,
"frames": [
{
"info": {
"id": "med_4I2nqWOMDsrCs7TNXbKTQ_1",
"position": 0
},
"nudity": {
"raw": 0.01,
"safe": 0.98,
"partial": 0.01
},
},
...
]
}
}
}
This request will return a JSON response containing the following attributes:
| Attribute | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled |
| request.id | string | id of the STOP request |
| request.timestamp | float | timestamp at which the STOP request was processed |
| request.operations | int | volume of operations counted towards your monthly usage |
| output | dictionary | a description of the moderation results, the way you would get them from the callback |
The output dictionary contains the following attributes:
| Attribute | Type | Description |
|---|---|---|
| media | dictionary | description of the media id and URI |
| request | string | request id |
| data | dictionary | description of the moderation result |
List on-going Video Moderation Tasks
Example request
curl -X GET -G 'https://api.sightengine.com/1.0/video/ongoing.json' \
-d 'api_user={api_user}' \
-d 'api_secret={api_secret}' \
# this example uses requests
import requests
import json
params = {'api_user': '{api_user}', 'api_secret': '{api_secret}'}
r = requests.get('https://api.sightengine.com/1.0/video/ongoing.json', params=params)
output = json.loads(r.text)
<?php
$params = array(
'api_user' => '{api_user}',
'api_secret' => '{api_secret}',
);
// this example uses cURL
$ch = curl_init('https://api.sightengine.com/1.0/video/ongoing.json?'.http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$output = json_decode($response, true);
// this example uses axios
const axios = require('axios');
axios.get('https://api.sightengine.com/1.0/video/ongoing.json', {
params: {
'api_user': '{api_user}',
'api_secret': '{api_secret}',
}
})
.then(function (response) {
// on success: handle response
console.log(response.data);
})
.catch(function (error) {
// handle error
if (error.response) console.log(error.response.data);
else console.log(error.message);
});
List all on-going continuous video moderation tasks.
This is useful to check how many tasks are on-going and what their ids are.
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
Example response
{
"status": "success",
"request": {
"id": "rtr_4I2hogli0zqFQVoCbAIZO",
"timestamp": 1550584177.5192,
"operations": 0
},
"ongoing": [
{
"requestid": "req_4I2hYjooGs7d4eEIDin4y",
"mediaid": "med_4I2hvcxaNqwjPP0zdT44t",
"type": "video_moderation",
"last_update": "1550584177"
}
]
}
This request will return a JSON response containing the following attributes:
| Attribute | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled |
| request.id | string | id of the STOP request |
| request.timestamp | float | timestamp at which the STOP request was processed |
| request.operations | int | volume of operations counted towards your monthly usage |
| ongoing | array | array of JSON dictionaries. Each dictionary describes a single on-going moderation task. |
For each task, the ongoing array will contain:
- the request id
- the media id
- the timestamp of the last change to the moderation result
Stop an on-going Video Moderation Task
Example request
curl -X DELETE 'https://api.sightengine.com/1.0/video/byid.json' \
-F 'api_user={api_user}' \
-F 'api_secret={api_secret}' \
-F 'id={media_id}'
# this example uses requests
import requests
import json
data = {
# {media_id} is the id of the media that is being moderated
# this id is given to you by the API when you perform a moderation request
'id': '{media_id}',
'api_user': '{api_user}',
'api_secret': '{api_secret}'
}
r = requests.delete('https://api.sightengine.com/1.0/video/byid.json', data=data)
output = json.loads(r.text)
<?php
$params = array(
// {media_id} is the id of the media that is being moderated
// this id is given to you by the API when you perform a moderation request
'id' => '{media_id}',
'api_user' => '{api_user}',
'api_secret' => '{api_secret}',
);
// this example uses cURL
$ch = curl_init('https://api.sightengine.com/1.0/video/byid.json');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
$response = curl_exec($ch);
curl_close($ch);
$output = json_decode($response, true);
// this example uses axios and querystring
const axios = require('axios');
const qs = require('querystring');
data = {
'id': '{media_id}',
'api_user': '{api_user}',
'api_secret': '{api_secret}',
}
axios.delete('https://api.sightengine.com/1.0/video/byid.json', {params: data})
.then(function (response) {
// on success: handle response
console.log(response.data);
})
.catch(function (error) {
// handle error
if (error.response) console.log(error.response.data);
else console.log(error.message);
});
Continuous video moderation tasks will go on until one of the following happens:
- the video stream ends
- the maximum video duration has been reached
- you choose to stop the moderation task
Stopping a given moderation task is simple and straightforward:
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| id | yes | Media id |
Example response
{
"status": `success`,
"request": {
"id": "rtr_4I2da8SXYFsnfVJ8fq03X",
"timestamp": 1550583937.9341,
"operations": 0
}
}
This request will return a JSON response containing the following attributes:
| Attribute | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled |
| request.id | string | id of the STOP request |
| request.timestamp | float | timestamp at which the STOP request was processed |
| request.operations | int | volume of operations counted towards your monthly usage |
Text and Username Moderation
Text Moderation works by submitting Text to the moderation API. Our moderation engine will then analyze the text and return any objectionable content.
Text Moderation detects:
- Profanity (insults, sexual content, discriminatory content ...)
- Personal Details (email addresses, IP addresses, phone numbers, US social security numbers...)
- Links and URLs
In the case of usernames, the API can also help detect misleading usernames that might mislead other users.
Available languages are:
- English (default), iso code
en - Chinese (simplified or traditional), iso code
zh - Dutch, iso code
nl - French, iso code
fr - German, iso code
de - Italian, iso code
it - Portuguese, iso code
pt - Spanish, iso code
es - Swedish, iso code
sv
Available countries (set through the opt_countries parameter) are:
- Brazil, iso code
br - France, iso code
fr - Germany, iso code
de - Italy, iso code
it - Spain, iso code
es - United Kingdom, iso code
gb - United States, iso code
us
Request arguments (POST)
Example request
curl -X POST 'https://api.sightengine.com/1.0/text/check.json' \
-F 'text=Contact rick(at)gmail(dot)com to have s_*_x' \
-F 'lang=en' \
-F 'opt_countries=us,gb,fr' \
-F 'mode=standard' \
-F 'api_user={api_user}' \
-F 'api_secret={api_secret}'
# this example uses requests
import requests
import json
data = {
'text': 'Contact rick(at)gmail(dot)com to have s_*_x',
'mode': 'standard',
'lang': 'en',
'opt_countries': 'us,gb,fr',
'api_user': '{api_user}',
'api_secret': '{api_secret}'
}
r = requests.post('https://api.sightengine.com/1.0/text/check.json', data=data)
output = json.loads(r.text)
<?php
$params = array(
'text' => 'Contact rick(at)gmail(dot)com to have s_*_x',
'lang' => 'en',
'opt_countries' => 'us,gb,fr',
'mode' => 'standard',
'api_user' => '{api_user}',
'api_secret' => '{api_secret}',
);
// this example uses cURL
$ch = curl_init('https://api.sightengine.com/1.0/text/check.json');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
$response = curl_exec($ch);
curl_close($ch);
$output = json_decode($response, true);
// this example uses axios and form-data
const axios = require('axios');
const FormData = require('form-data');
data = new FormData();
data.append('text', 'Contact rick(at)gmail(dot)com to have s_*_x');
data.append('lang', 'en');
data.append('opt_countries', 'us,gb,fr');
data.append('mode', 'standard');
data.append('api_user', '{api_user}');
data.append('api_secret', '{api_secret}');
axios({
url: 'https://api.sightengine.com/1.0/text/check.json',
method:'post',
data: data,
headers: data.getHeaders()
})
.then(function (response) {
// on success: handle response
console.log(response.data);
})
.catch(function (error) {
// handle error
if (error.response) console.log(error.response.data);
else console.log(error.message);
});
To moderate text you should perform a POST request specifying the text, the moderation mode and the target language.
| Parameter | Required | Description |
|---|---|---|
| text | yes | UTF-8 encoded text to be moderated |
| lang | yes | ISO 639-1 code for the target language (en, es, fr, de, zh...) |
| mode | yes | standard for standard text moderation, username for username moderation |
| opt_countries | no | Comma separated list of country codes for phone number detection (ISO 3166-1 alpha-2 code), default is us,gb,fr (United States, United Kingdom, France) |
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
Please note that texts have a size limit:
- standard texts should not be more than 10,000 characters long
- usernames should not be more than 128 characters long
If you submit a longer text, you will get an error and the text will not be moderated.
Response
Example response
{
"status": "success",
"request": {
"id": "req_6cujQglQPgGApjI5odv0P",
"timestamp": 1471947033.92,
"operations": 1
},
"profanity": {
"matches": [
{
"type": "sexual",
"match": "sx",
"start": 38,
"end": 42,
}
]
},
"personal": {
"matches": [
{
"type": "email",
"match": "rick(at)gmail(dot)com",
"start": 8,
"end": 28
}
]
},
"link": {
"matches": []
},
}
This request will return a JSON response containing the following attributes:
| Attribute | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled, failure otherwise |
| request | object | a JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed) |
| profanity | object | a JSON dictionary containing information on any profanity found in the text |
| personal | object | a JSON dictionary containing information on any personal details found in the text |
| link | object | a JSON dictionary containing information on any links or URLs found in the text |
| misleading | object | for usernames only: JSON dictionary telling you if the username is misleading |
The profanity, personal, misleading and link objects each contain a matches array.
The matches array contains details on any objectionable content that was found, its type and position in the provided string. The matches array contains match objects. Each match object has the following attributes:
| Attribute | Type | Description |
|---|---|---|
| type | string | type of profanity or personal detail found. Please see below for the list of types |
| match | string | the word or string that was found to be objectionable |
| start | int | start position of the match in the initial text string. The first character would have position 0. |
| end | int | end position of the match in the initial text string |
The type string can be used to obtain more details on the type of objectionable content found. Possible values depend on the category:
- Profanity:
sexual,insult,discriminatory,inappropriate,other_profanity - Personal Details:
email,ipv4,ipv6,phone_number_us,phone_number_uk,phone_number_fr,ssn - Links/URLS:
url - Misleading:
misleading
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 7 classes:
raw: corresponding to raw nuditysafe: corresponding to no nuditybikini: corresponding to an image containing a bikinichestcleavagelingerieminiskirt
The wad model has 6 classes:
no-weaponsweaponsno-alcoholalcoholno-drugsdrugs
The text model has 3 classes:
no-texttext-artificialtext-natural
The offensive model has 2 classes:
not-offensiveoffensive
The scam model has 2 classes:
not-scamscam
The gender model has 2 classes:
malefemale
The minor model has 2 classes:
no-minorminor
The celebrities model has 2 classes:
no-celebritycelebrity
The face model has 3 classes:
nonesinglemultiple
The type model has 2 classes:
photoillustration
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");
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| url | yes | Public URL to the image to be moderated |
| model | yes | Model for which you want to perform a correction. Could be nudity, face, type, wad, celebrities |
| class | yes | 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");
| Parameter | Required | Description |
|---|---|---|
| api_user | yes | Your API user |
| api_secret | yes | Your API secret |
| media | yes | The image (local file) to be moderated |
| model | yes | Model for which you want to perform a correction. Could be nudity, face, type |
| class | yes | 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 attributes:
| Attribute | Type | Description |
|---|---|---|
| status | string | success if the request was successfully handled, failure otherwise |
| request | object | a JSON dictionary containing meta data on the request (identifying id, timestamp and number of operations performed) |
| media | object | a 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:
- The HTTP status code returned is
4xxor5xx(except for JSONP requests that always return a200code) - The
statusfield is set tofailure
More information on the nature of the error can be found through the error object. This object contains the following Attributes:
| Attribute | Type | Description |
|---|---|---|
| type | string | Type of the error. Common types are credentials_error, media_error, usage_limit, plan_error, argument_error |
| code | int | Sightengine-specific code describing the error. Useful if you need to communicate with support. |
| message | string | Human-readable description of the error. |