Models / Image Quality Detection

Image Quality Detection


The image properties model can help you determine the perceived quality of an Image through the sharpness, contrast and brightness properties returned by the API.

Use cases

  • Surface high-quality images to users
  • Filter out excessively blurry, dark or otherwise unpleasant photos
  • Encourage users to upload higher quality images
  • Group or classify images by quality level

Sharpness / Bluriness Detection

The Image Properties API can help you determine the perceived sharpness or bluriness of an Image through the "sharpness" property.

The returned value is between 0 and 1. Images with a sharpness value closer to 1 will be sharper while images with a sharpness value closer to 0 will be perceived as blurrier.

Illustration of different sharpness values

sharp image
sharpness = 0.94
moderately sharp image
sharpness = 0.72
blurry image
sharpness = 0.46

Images usually tend to have different levels of sharpness or bluriness due to parts of the image being either in-focus or out-of-focus.

The sharpness value you will get is an estimate of the overall perceived sharpness of the image, meaning that even if most of the image is out-of-focus, the image will still be perceveid as sharp if a substantial portion is in-focus.

sharp image with out-of-focus part
Illustration: This image has a large out-of-focus part but is still perceived as sharp due to the pine cones being in-focus (sharpness: 0.996)

Recommended thresholds

  • Below 0.4: Very blurry
  • Between 0.4 and 0.6: Blurry
  • Between 0.6 and 0.8: Slightly blurry
  • Between 0.8 and 0.9: Sharp
  • Between 0.9 and 1: Very sharp

Brightness Detection

The brightness of the image is returned as a between 0 and 1. Images with a value closer to 1 will be brighter while images with a value closer to 0 will be darker.

bright image
The image is bright: (brightness value 0.915)
dark image
The image is dark: (brightness value 0.192)

Recommended thresholds

  • Equal or inferior to 0.2: Very dark
  • Between 0.2 and 0.4: Dark
  • Between 0.4 and 0.6: Low brightness
  • Between 0.6 and 0.8: Bright
  • Between 0.8 and 1: Very bright

Contrast Detection

The returned value is between 0 and 1.

Image with a low contrast: (contrast value 0.296)
Image with a hight contrast: (contrast value 0.89)

Recommended thresholds

  • Equal or inferior to 0.3: Low contrast
  • Between 0.3 and 0.7: Average contrast
  • Between 0.7 and 1: High contrast

Use the model

If you haven't already, create an account to get your own API keys.

Detect the properties of an image

Let's say you want to moderate the following image:

You can either upload a public URL to the image, or upload the raw binary image. Here's how to proceed if you choose to share the image's public URL:

curl -X GET -G '' \
    -d 'models=properties' \
    -d 'api_user={api_user}&api_secret={api_secret}' \
    --data-urlencode 'url='

# this example uses requests
import requests
import json

params = {
  'url': '',
  'models': 'properties',
  'api_user': '{api_user}',
  'api_secret': '{api_secret}'
r = requests.get('', params=params)

output = json.loads(r.text)

$params = array(
  'url' =>  '',
  'models' => 'properties',
  'api_user' => '{api_user}',
  'api_secret' => '{api_secret}',

// this example uses cURL
$ch = curl_init(''.http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

$output = json_decode($response, true);

// this example uses axios
const axios = require('axios');

axios.get('', {
  params: {
    'url': '',
    'models': 'properties',
    'api_user': '{api_user}',
    'api_secret': '{api_secret}',
.then(function (response) {
  // on success: handle response
.catch(function (error) {
  // handle error
  if (error.response) console.log(;
  else console.log(error.message);

The API will then return a JSON 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": ""

Any other needs?

See our full list of models for details on other filters and checks you can run on your images and videos.

Did you find this page helpful?

We're always looking for advice to help improve our documentation!

Let us know what you think

Cookies help us deliver our services. By using our services, you agree to our use of cookies. Learn more