API documentation

The Everypixel API offers image recognition as a service.
The API is built around a simple idea. You send inputs (an image)
to the service and it returns predictions.
Get your free API key →

Authentication

After being signed up you will get credentials for API access. You must keep them safe. These credentials should be used for OAuth 2.0 authentication protocol. At the first step you should get the access token:

curl "https://api.everypixel.com/oauth/token?client_id=<your-client-id>&client_secret=<your-client-secret>&grant_type=client_credentials"
from requests_oauthlib import OAuth2Session
from oauthlib.oauth2 import BackendApplicationClient

client_id = '<your-client-id>'
client_secret = '<your-client-secret>'

oauth = OAuth2Session(client=BackendApplicationClient(client_id))
token = oauth.fetch_token(token_url='https://api.everypixel.com/oauth/token', auth=(client_id, client_secret))
$client_id = "<your-client-id>";
$secret = "<your-client-secret>";
$url = "https://api.everypixel.com/oauth/token?client_id=$client_id&client_secret=$secret&grant_type=client_credentials";

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$data = curl_exec($curl);
curl_close($curl);

$json = json_decode($data);

You will get the json document containing access token with 1 hour lifetime. You can use only one access token at once.

{"access_token": "Aa4k7ink5cUXsG3V0OLDqNA3VF0BPg", "token_type": "Bearer", "scope": "keywording"}

Versioning

The versioning of API is a part of URI. To use v1 of the API the request URI should begin with /v1 followed by API method.

https://api.everypixel.com/v1

API methods

/keywords

By sending an image to this method you can get a list of suggested keywords. You may specify a number of returned words or a threshold of its minimum score. Just provide num_keywords or threshold parameter to this method.

Image should be specified by its url or uploaded with multipart form by parameter 'data'. You should use, respectively, GET and POST methods.

curl -H "Authorization: Bearer <access-token>" "https://api.everypixel.com/v1/keywords?url=http://image.everypixel.com/2014.12/67439828186edc79b9be81a4dedea8b03c09a12825b_b.jpg&num_keywords=10"
api = OAuth2Session(client_id, token=token)
params = {'url': 'http://image.everypixel.com/2014.12/67439828186edc79b9be81a4dedea8b03c09a12825b_b.jpg', 'num_keywords': 10}
keywords = api.get('https://api.everypixel.com/v1/keywords', params=params).json()

with open('image.jpg','rb') as image:
    data = {'data': image}
    keywords = api.post('https://api.everypixel.com/v1/keywords', files=data).json()
$authorization = "Authorization: Bearer <access-token>";
$url = "https://api.everypixel.com/v1/keywords?url=http://image.everypixel.com/2014.12/67439828186edc79b9be81a4dedea8b03c09a12825b_b.jpg&num_keywords=10";

$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPHEADER, array($authorization));
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$data = curl_exec($curl);
curl_close($curl);

$json = json_decode($data);
And the answer would be:
{
  "keywords": [
    {"keyword": "Domestic Cat", "score": 0.98873621225357056},
    {"keyword": "Pets", "score": 0.97396981716156006},
    {"keyword": "Animal", "score": 0.94135761260986328},
    {"keyword": "Cute", "score": 0.86750519275665283},
    {"keyword": "Kitten", "score": 0.83549922704696655},
    {"keyword": "Feline", "score": 0.74918556213378906},
    {"keyword": "Domestic Animals", "score": 0.71088212728500366},
    {"keyword": "Young Animal", "score": 0.703544020652771},
    {"keyword": "Mammal", "score": 0.67086690664291382},
    {"keyword": "Fur", "score": 0.61061191558837891}
  ],
  "status": "ok"
}

/quality

This method allows you to get the quality score for your photo. This service doesn't measure how cool or beautiful a person or an object on a photo may look. It cares only about technical parts like brightness, contrast, noise and so on. The service is not dedicated for scoring historical photos, illustrations or 3D visualizations.

Image should be specified by its url or uploaded with multipart form by parameter 'data'. You should use, respectively, GET and POST methods.

curl -H "Authorization: Bearer <access-token>" "https://api.everypixel.com/v1/quality?url=http://image.everypixel.com/2014.12/67439828186edc79b9be81a4dedea8b03c09a12825b_b.jpg"
api = OAuth2Session(client_id, token=token)
params = {'url': 'http://image.everypixel.com/2014.12/67439828186edc79b9be81a4dedea8b03c09a12825b_b.jpg'}
quality = api.get('https://api.everypixel.com/v1/quality', params=params).json()

with open('image.jpg','rb') as image:
    data = {'data': image}
    quality = api.post('https://api.everypixel.com/v1/quality', files=data).json()
$authorization = "Authorization: Bearer <access-token>";
$url = "https://api.everypixel.com/v1/quality?url=http://image.everypixel.com/2014.12/67439828186edc79b9be81a4dedea8b03c09a12825b_b.jpg";

$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPHEADER, array($authorization));
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$data = curl_exec($curl);
curl_close($curl);

$json = json_decode($data);
And the answer would be:
{
  "quality": {
    "score": 0.9729430521699124
  },
  "status": "ok"
}

/quality_ugc

The main difference between Stock photo scoring and this model is in the training dataset. User-Generated Photo Scoring is a model trained on a 1,000,000 of user photos from Instagram. Estimation parameters for this model were prepared by a group of 10 professional photographers. Scoring methods are based on five classes: very bad (0-20), bad (20-40), normal (40-60), good (60-80) and excellent (80-100).

This model is designed to evaluate user photos taken both by a professional camera and by a camera of a smartphone. It doesn't estimate the plot and do not measure how cool or beautiful a person or an object on a photo may look. It cares only about technical parts like brightness, contrast, noise and so on. The service is not dedicated for scoring historical photos, illustrations or 3D visualizations.

Image should be specified by its url or uploaded with multipart form by parameter 'data'. You should use, respectively, GET and POST methods.

curl -H "Authorization: Bearer <access-token>" "https://api.everypixel.com/v1/quality_ugc?url=http://image.everypixel.com/2014.12/67439828186edc79b9be81a4dedea8b03c09a12825b_b.jpg"
api = OAuth2Session(client_id, token=token)
params = {'url': 'http://image.everypixel.com/2014.12/67439828186edc79b9be81a4dedea8b03c09a12825b_b.jpg'}
quality = api.get('https://api.everypixel.com/v1/quality_ugc', params=params).json()

with open('image.jpg','rb') as image:
    data = {'data': image}
    quality = api.post('https://api.everypixel.com/v1/quality_ugc', files=data).json()
$authorization = "Authorization: Bearer <access-token>";
$url = "https://api.everypixel.com/v1/quality_ugc?url=http://image.everypixel.com/2014.12/67439828186edc79b9be81a4dedea8b03c09a12825b_b.jpg";

$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPHEADER, array($authorization));
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$data = curl_exec($curl);
curl_close($curl);

$json = json_decode($data);
And the answer would be:
{
  "quality": {
    "score": 0.5947988033294678,
    "class": 3
  },
  "status": "ok"
}

Errors

Most of the errors returned by the API have json formatted text.

{
  "status": "error",
  "message": "Threshold must be float."
}

Also, you can receive non-successful HTTP status codes:
401 - you have no access to a specified endpoint. It might happen if your access token has been expired.
429 - you have exceeded available requests from your plan.