Detect objects in a photo

To detect objects in a photo, use this method:

POST /detect

The REQUEST BODY is required and contains multipart/form-data with the following parameters.

Name	Type	Description
`photo`	binary	Source image file.
`attributes`	object	Contains attributes that can be detected for the following object types: face, vehicle, and body.

The attributes field may be empty or include the face, car, and body objects, each with the following set of parameters:

Name		Type	Description
`face`		object	Contains face attributes.
	`age`	boolean	If `true`, the estimated age is included in the response.
	`beard`	boolean	If `true`, the presence of a beard is detected.
	`emotions`	boolean	If `true`, the facial expression is detected (surprise, sadness, happiness, neutral expression, fear, disgust, anger).
	`glasses`	boolean	If `true`, the presence and type of glasses is detected.
	`gender`	boolean	If `true`, the gender is determined.
	`medmask`	boolean	If `true`, the presence of a medical mask and its improper positioning on the face is detected.
	`headpose`	boolean	If `true`, the head turn and head tilt angles are estimated.
	`eyes_attrs`	boolean	If `true`, the eye state is determined (eyes opened, eyes closed, eyes occluded).
`car`		object	Contains vehicle attributes.
	`description`	boolean	If `true`, the response will include details about the vehicle, such as its body type, make, model, and body color.
	`license_plate`	boolean	If `true`, the response will include information about the vehicle’s license plate, such as its number, country, region, and number color.
	`special_vehicle_type`	boolean	If `true`, the response will indicate whether the vehicle belongs to a special category (e.g., `taxi`, `route_transport`).
	`category`	boolean	If `true`, the response will include the vehicle’s category (e.g., `B`, `C`).
	`weight_type`	boolean	If `true`, the response will include the vehicle’s weight classification (e.g., `B_heavy`, `D_light`).
	`orientation`	boolean	If `true`, the response will include the vehicle’s angle in the photo (e.g., `front`, `side`, `back`).
`body`		object	Contains body attributes.
	`color`	boolean	If `true`, the colors of the upper and lower clothing are detected.
	`clothes`	boolean	If `true`, the response will include details about clothing, such as the type of upper-body clothing, the presence and length of its sleeves, lower-body clothing, and headwear.
	`bags`	boolean	If `true`, the response will indicate whether a bag is present in the hand or on the back.
	`protective_equipment`	boolean	If `true`, the presence and color of a vest and helmet is detected.
	`age_gender`	boolean	If `true`, the age group and gender is determined.
	`fall`	boolean	If `true`, the response will indicate whether the person has fallen.
	`handface`	boolean	If `true`, the following actions are detected: smoking, using a phone, and making a phone call.
	`phoneuse`	boolean	If `true`, the action of taking pictures with a phone is detected.

Attach a source image file and send the POST request.

CURL example

curl -X POST "http://<findface-ip:port>/detect" \
-H "Authorization: Token <token>" \
-H "Content-Type: multipart/form-data" \
-F "photo=@sample_face.jpg" \
-F 'attributes={
 "face": {
   "age": true,
   "beard": true,
   "emotions": true,
   "glasses": true,
   "gender": true,
   "medmask": true,
   "headpose": true,
   "eyes_attrs": true
 },
 "car": {
   "description": false,
   "license_plate": false,
   "special_vehicle_type": false,
   "category": false,
   "weight_type": false,
   "orientation": false
 },
 "body": {
   "color": false,
   "clothes": false,
   "bags": false,
   "protective_equipment": false,
   "age_gender": false,
   "fall": false,
   "handface": false,
   "phoneuse": false
 }
}'

Tip

Replace sample_face.jpg with the full path if the file is not in your current working directory. Example: "photo=@/home/ubuntu/sample_face.jpg"

If the response is successful (OK: 200), it returns a JSON object that contains the following parameters. Example.

Name	Type	Description
`orientation*`	integer	EXIF orientation of the photo.
`objects`	object	Contains arrays of data. Each array includes information about detected objects of a specific type (face, body, or vehicle), along with their attributes specified in the request.

Response example

{
 "orientation": 1,
 "objects": {
   "face": [
     {
       "id": "d1uvcdskd5qs72mq52h0",
       "bbox": {
         "left": 722,
         "top": 31,
         "right": 801,
         "bottom": 132
       },
       "detection_score": 0.5006658,
       "low_quality": false,
       "features": {
         "age": 25,
         "beard": {
           "name": "none",
           "confidence": 0.052511778
         },
         "emotions": {
           "name": "neutral",
           "confidence": 0.9908866
         },
         "glasses": {
           "confidence": 0.89929795,
           "name": "none"
         },
         "gender": {
           "confidence": 0.99800926,
           "name": "female"
         },
         "medmask": {
           "confidence": 0.9999994,
           "name": "none"
         },
         "headpose_pitch": {
           "name": 6.227072,
           "confidence": 1
         },
         "headpose_yaw": {
           "name": 20.798172,
           "confidence": 1
         },
         "eyes_attrs": {
           "confidence": 0.8949018,
           "name": "opened"
         }
       }
     }
   ],
   "body": [
     {
       "id": "d1uvceskd5qs72mq52hg",
       "bbox": {
         "left": 522,
         "top": 5,
         "right": 933,
         "bottom": 792
       },
       "detection_score": 0.82396024,
       "low_quality": false,
       "features": {}
     }
   ]
 }
}

In the response, you will receive the id and bounding box (bbox) coordinates of the object (face, car, body). Copy the id of the required object to add the object to a record or to search for the object.