On this page

Docs / People & Identity / People Counting API

People Counting API

BETA people_counting

Automatically detect and analyze the presence of people in images and videos. Sightengine APIs analyzes each frame and returns the number of visible people.

Overview

The People Counting model determines the number of different people visible within a given image or video frame.

The model does not rely on face detection. Individuals will be counted by the model regardless of face visibility, ensuring accurate detection even when only partial body parts are shown.

If a person appears multiple times in the frame, such as reflections in mirrors or image collages, the model will correctly count them only once.

The model has been trained to distinguish real people from non-human representations, explicitly excluding mannequins, dolls, statues and illustrated figures like cartoons or drawings.

The response is structured into 6 distinct classes, based on the number of unique people visible:

Class nameDescription
0No people visible in the frame
1One person in the frame
2Two people in the frame
3Three people in the frame
4Four people in the frame
5+Five or more people in the frame

For video inputs, the model will analyze each frame individually and return the number of people visible within each frame.

Use the model (images)

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

People counting

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

You can either share a URL to the image, or upload the image file.

Option 1: Send image URL

Here's how to proceed if you choose to share the image URL:


curl -X GET -G 'https://api.sightengine.com/1.0/check.json' \
    -d 'models=people-counting' \
    -d 'api_user={api_user}&api_secret={api_secret}' \
    --data-urlencode 'url=https://sightengine.com/assets/img/examples/example7.jpg'



# this example uses requests
import requests
import json

params = {
  'url': 'https://sightengine.com/assets/img/examples/example7.jpg',
  'models': 'people-counting',
  'api_user': '{api_user}',
  'api_secret': '{api_secret}'
}
r = requests.get('https://api.sightengine.com/1.0/check.json', params=params)

output = json.loads(r.text)



$params = array(
  'url' =>  'https://sightengine.com/assets/img/examples/example7.jpg',
  'models' => 'people-counting',
  'api_user' => '{api_user}',
  'api_secret' => '{api_secret}',
);

// this example uses cURL
$ch = curl_init('https://api.sightengine.com/1.0/check.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/check.json', {
  params: {
    'url': 'https://sightengine.com/assets/img/examples/example7.jpg',
    'models': 'people-counting',
    '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);
});

See request parameter description

ParameterTypeDescription
urlstringURL of the image to analyze
modelsstringcomma-separated list of models to apply
api_userstringyour API user id
api_secretstringyour API secret

Option 2: Send image file

Here's how to proceed if you choose to upload the image file:


curl -X POST 'https://api.sightengine.com/1.0/check.json' \
    -F 'media=@/path/to/image.jpg' \
    -F 'models=people-counting' \
    -F 'api_user={api_user}' \
    -F 'api_secret={api_secret}'



# this example uses requests
import requests
import json

params = {
  'models': 'people-counting',
  'api_user': '{api_user}',
  'api_secret': '{api_secret}'
}
files = {'media': open('/path/to/image.jpg', 'rb')}
r = requests.post('https://api.sightengine.com/1.0/check.json', files=files, data=params)

output = json.loads(r.text)



$params = array(
  'media' => new CurlFile('/path/to/image.jpg'),
  'models' => 'people-counting',
  'api_user' => '{api_user}',
  'api_secret' => '{api_secret}',
);

// this example uses cURL
$ch = curl_init('https://api.sightengine.com/1.0/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');
const fs = require('fs');

data = new FormData();
data.append('media', fs.createReadStream('/path/to/image.jpg'));
data.append('models', 'people-counting');
data.append('api_user', '{api_user}');
data.append('api_secret', '{api_secret}');

axios({
  method: 'post',
  url:'https://api.sightengine.com/1.0/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);
});

See request parameter description

ParameterTypeDescription
mediafileimage to analyze
modelsstringcomma-separated list of models to apply
api_userstringyour API user id
api_secretstringyour API secret

API response

The API will then return a JSON response with the following structure:

                  
                  
{
    "status": "success",
    "request": {
        "id": "req_gcTp4s63IAAni0lFOT7KK",
        "timestamp": 1714997478.552115,
        "operations": 1
    },
    "people_count": {
        "0": 0.0,
        "1": 0.99,
        "2": 0.0,
        "3": 0.0,
        "4": 0.0,
        "5+": 0.0
    },
    "media": {
        "id": "med_gcTpqyOZ18IMsiMe4Ar28",
        "uri": "https://sightengine.com/assets/img/examples/example7.jpg"
    }
}

See response description

Successful Response
Status code: 200, Content-Type: application/json
FieldTypeDescription
statusstringstatus of the request, either "success" or "failure"
requestobjectinformation about the processed request
request.idstringunique identifier of the request
request.timestampfloattimestamp of the request in Unix time
request.operationsintegernumber of operations consumed by the request
people_countobjectresults for the model
mediaobjectinformation about the media analyzed
media.idstringunique identifier of the media
media.uristringURI of the media analyzed: either the URL or the filename
Error
Status codes: 4xx and 5xx. See how error responses are structured.

Use the model (videos)

People counting

This model is currently gated. Please get in touch for access and implementation details.