Rest API description

Postman REST API documentation
Face Recognition Service
Face Detection Service
Face Verification Service
Base64 Support
Recognition and verification using embedding

To know more about face services and face plugins visit this page.

Postman documentation

There is a Postman REST API documentation that covers the same REST endpoint. Postman documentation supports snippets on the most popular programming languages.

Face Recognition Service

Managing Subjects

These endpoints allow you to work with subjects.

The most popular case of subject usage is to assign a subject to one person. So, to upload several images of one person, you need to upload them to one subject. As a result, when you perform face recognition, you find a person who is on the image.

Another case of subject usage is assigning a photo of several people as a subject. In this case, you need to detect all faces on the image and then save them to one subject. As a result, when you perform face recognition, you find all photos on which there is the person who is on the image. You don’t need to work with subjects explicitly. You can just upload a new example of the subject and the subject will be created automatically. Or if you delete all the examples of the subject, it will be deleted automatically.

Add a Subject

since 0.6 version

Create a new subject in Face Collection. Creating a subject is an optional step, you can upload an example without an existing subject, and a subject will be created automatically.

shell

curl -X POST "http://localhost:8000/api/v1/recognition/subjects" \
-H "Content-Type: application/json" \
-H "x-api-key: <service_api_key>" \
-d '{"subject": "<subject_name>"}'

Element	Description	Type	Required	Notes
Content-Type	header	string	required	application/json
x-api-key	header	string	required	api key of the Face recognition service, created by the user
subject	body param	string	required	is the name of the subject. It can be a person name, but it can be any string

Response body on success:

json

{
  "subject": "<subject_name>"
}

Element	Type	Description
subject	string	is the name of the subject

Rename a Subject

since 0.6 version

Rename existing subject. If a new subject name already exists, subjects are merged - all faces from the old subject name are reassigned to the subject with the new name, old subject removed.

shell

curl -X PUT "http://localhost:8000/api/v1/recognition/subjects/<subject>" \
-H "Content-Type: application/json" \
-H "x-api-key: <service_api_key>" \
-d '{"subject: <subject_name>"}'

Element	Description	Type	Required	Notes
Content-Type	header	string	required	application/json
x-api-key	header	string	required	api key of the Face recognition service, created by the user
subject	body param	string	required	is the name of the subject. It can be a person name, but it can be any string

Response body on success:

json

{
  "updated": "true|false"
}

Element	Type	Description
updated	boolean	failed or success

Delete a Subject

since 0.6 version

Delete existing subject and all saved faces.

shell

curl -X DELETE "http://localhost:8000/api/v1/recognition/subjects/<subject>" \
-H "Content-Type: application/json" \
-H "x-api-key: <service_api_key>"

Element	Description	Type	Required	Notes
Content-Type	header	string	required	application/json
x-api-key	header	string	required	api key of the Face recognition service, created by the user
subject	body param	string	required	is the name of the subject. It can be a person name, but it can be any string

Response body on success:

json

{
  "subject": "<subject_name>"
}

Element	Type	Description
subject	string	is the name of the subject

Delete All Subjects

since 0.6 version

Delete all existing subjects and all saved faces.

shell

curl -X DELETE "http://localhost:8000/api/v1/recognition/subjects" \
-H "Content-Type: application/json" \
-H "x-api-key: <service_api_key>"

Element	Description	Type	Required	Notes
Content-Type	header	string	required	application/json
x-api-key	header	string	required	api key of the Face recognition service, created by the user

Response body on success:

json

{
  "deleted": "<count>"
}

Element	Type	Description
deleted	integer	number of deleted subjects

List Subjects

since 0.6 version

This returns all subject related to Face Collection.

shell

curl -X GET "http://localhost:8000/api/v1/recognition/subjects/" \
-H "Content-Type: application/json" \
-H "x-api-key: <service_api_key>"

Element	Description	Type	Required	Notes
Content-Type	header	string	required	application/json
x-api-key	header	string	required	api key of the Face recognition service, created by the user

Response body on success:

json

{
  "subjects": [
    "<subject_name1>",
    "<subject_name2>"
    ]
}

Element	Type	Description
subjects	array	the list of subjects in Face Collection

Managing Subject Examples

The subject example is basically an image of a known face that you want to save to face collection.

When you save a subject example, CompreFace calculates the embedding of the face (faceprint) and saves it into the database. By default, the image itself is also saved, it is needed for managing images, e.g. download of the image. You can change it using save_images_to_db parameter in configuration.

One subject example is enough for face recognition, the accuracy will be high enough. But if you add more examples, the accuracy may be even better.

Add an Example of a Subject

This creates an example of the subject by saving images. You can add as many images as you want to train the system. Image should contain only one face.

shell

curl -X POST "http://localhost:8000/api/v1/recognition/faces?subject=<subject>&det_prob_threshold=<det_prob_threshold>" \
-H "Content-Type: multipart/form-data" \
-H "x-api-key: <service_api_key>" \
-F file=@<local_file>

Element	Description	Type	Required	Notes
Content-Type	header	string	required	multipart/form-data
x-api-key	header	string	required	api key of the Face recognition service, created by the user
subject	param	string	required	is the name you assign to the image you save
det_prob_threshold	param	string	optional	minimum required confidence that a recognized face is actually a face. Value is between 0.0 and 1.0.
file	body	image	required	allowed image formats: jpeg, jpg, ico, png, bmp, gif, tif, tiff, webp. Max size is 5Mb

Response body on success:

json

{
  "image_id": "6b135f5b-a365-4522-b1f1-4c9ac2dd0728",
  "subject": "subject1"
}

Element	Type	Description
image_id	UUID	UUID of uploaded image
subject	string	Subject of the saved image

List of All Saved Examples of the Subject

To retrieve a list of subjects saved in a Face Collection:

shell

curl -X GET "http://localhost:8000/api/v1/recognition/faces?page=<page>&size=<size>&subject=<subject>" \
-H "x-api-key: <service_api_key>" \

Element	Description	Type	Required	Notes
x-api-key	header	string	required	api key of the Face recognition service, created by the user
page	param	integer	optional	page number of examples to return. Can be used for pagination. Default value is 0. Since 0.6 version
size	param	integer	optional	faces on page (page size). Can be used for pagination. Default value is 20. Since 0.6 version
subject	param	string	optional	what subject examples endpoint should return. If empty, return examples for all subjects. Since 1.0 version

Response body on success:

{
  "faces": [
    {
      "image_id": <image_id>,
      "subject": <subject>
    },
    ...
  ],
  "page_number": 0,
  "page_size": 10,
  "total_pages": 2,
  "total_elements": 12
}

Element	Type	Description
face.image_id	UUID	UUID of the face
faсe.subject	string	<subject> of the person, whose picture was saved for this api key
page_number	integer	page number
page_size	integer	requested page size
total_pages	integer	total pages
total_elements	integer	total faces

Delete All Examples of the Subject by Name

To delete all image examples of the <subject>:

shell

curl -X DELETE "http://localhost:8000/api/v1/recognition/faces?subject=<subject>" \
-H "x-api-key: <service_api_key>"

Element	Description	Type	Required	Notes
x-api-key	header	string	required	api key of the Face recognition service, created by the user
subject	param	string	optional	is the name subject. If this parameter is absent, all faces in Face Collection will be removed

Response body on success:

{
    "deleted": <count>
}

Element	Type	Description
deleted	integer	Number of deleted faces

Delete an Example of the Subject by ID

Endpoint to delete an image by ID. If no image found by id - 404.

shell

curl -X DELETE "http://localhost:8000/api/v1/recognition/faces/<image_id>" \
-H "x-api-key: <service_api_key>"

Element	Description	Type	Required	Notes
x-api-key	header	string	required	api key of the Face recognition service, created by the user
image_id	variable	UUID	required	UUID of the removing face

Response body on success:

{
  "image_id": <image_id>,
  "subject": <subject>
}

Element	Type	Description
image_id	UUID	UUID of the removed face
subject	string	<subject> of the person, whose picture was saved for this api key

Delete Multiple Examples

since 1.0 version

To delete several subject examples:

shell

curl -X POST "http://localhost:8000/api/v1/recognition/faces/delete" \
-H "Content-Type: application/json" \
-H "x-api-key: <service_api_key>" \
-d '["<image_id1>","<image_id2>", ..., "<image_idN>"]'

Element	Description	Type	Required	Notes
service_api_key	header	string	required	api key of the Face recognition service, created by the user
image_id	variable	UUID	required	UUID of the removing face

Response body on success:

{
  "image_id": <image_id>,
  "subject": <subject>
}

Element	Description	Type
image_id	UUID of the removed face	UUID
subject	of the person, whose picture was saved for this api key	string

If some image ids are not exists, they will be ignored

Direct Download an Image example of the Subject by ID

since 0.6 version

You can paste this URL into the html tag to show the image.

shell

curl -X GET "http://localhost:8000/api/v1/static/<service_api_key>/images/<image_id>"

Element	Description	Type	Required	Notes
service_api_key	variable	string	required	api key of the Face recognition service, created by the user
image_id	variable	UUID	required	UUID of the image to download

Response body is binary image. Empty bytes if image not found.

Download an Image example of the Subject by ID

since 0.6 version

To download an image example of the Subject by ID:

shell

curl -X GET "http://localhost:8000/api/v1/recognition/faces/<image_id>/img"
-H "x-api-key: <service_api_key>"

Element	Description	Type	Required	Notes
x-api-key	header	string	required	api key of the Face recognition service, created by the user
image_id	variable	UUID	required	UUID of the image to download

Response body is binary image. Empty bytes if image not found.

Recognize Faces from a Given Image

To recognize faces from the uploaded image:

shell

curl  -X POST "http://localhost:8000/api/v1/recognition/recognize?limit=<limit>&prediction_count=<prediction_count>&det_prob_threshold=<det_prob_threshold>&face_plugins=<face_plugins>&status=<status>&detect_faces=<detect_faces>" \
-H "Content-Type: multipart/form-data" \
-H "x-api-key: <service_api_key>" \
-F file=<local_file>

Element	Description	Type	Required	Notes
Content-Type	header	string	required	multipart/form-data
x-api-key	header	string	required	api key of the Face recognition service, created by the user
file	body	image	required	allowed image formats: jpeg, jpg, ico, png, bmp, gif, tif, tiff, webp. Max size is 5Mb
limit	param	integer	optional	maximum number of faces on the image to be recognized. It recognizes the biggest faces first. Value of 0 represents no limit. Default value: 0
det_prob_threshold	param	string	optional	minimum required confidence that a recognized face is actually a face. Value is between 0.0 and 1.0.
prediction_count	param	integer	optional	maximum number of subject predictions per face. It returns the most similar subjects. Default value: 1
face_plugins	param	string	optional	comma-separated slugs of face plugins. If empty, no additional information is returned. Learn more
status	param	boolean	optional	if true includes system information like execution_time and plugin_version fields. Default value is false
detect_faces	param	boolean	optional	if false, CompreFace won't run a face detector. Instead, it will treat the image as a cropped face. Default value is true. Since 1.2 version

Response body on success:

json

{
  "result" : [ {
    "age" : {
      "probability": 0.9308982491493225,
      "high": 32,
      "low": 25
    },
    "gender" : {
      "probability": 0.9898611307144165,
      "value": "female"
    },
    "mask" : {
      "probability": 0.9999470710754395,
      "value": "without_mask"
    },
    "embedding" : [ 9.424854069948196E-4, "...", -0.011415496468544006 ],
    "box" : {
      "probability" : 1.0,
      "x_max" : 1420,
      "y_max" : 1368,
      "x_min" : 548,
      "y_min" : 295
    },
    "landmarks" : [ [ 814, 713 ], [ 1104, 829 ], [ 832, 937 ], [ 704, 1030 ], [ 1017, 1133 ] ],
    "subjects" : [ {
      "similarity" : 0.97858,
      "subject" : "subject1"
    } ],
    "execution_time" : {
      "age" : 28.0,
      "gender" : 26.0,
      "detector" : 117.0,
      "calculator" : 45.0,
      "mask": 36.0
    }
  } ],
  "plugins_versions" : {
    "age" : "agegender.AgeDetector",
    "gender" : "agegender.GenderDetector",
    "detector" : "facenet.FaceDetector",
    "calculator" : "facenet.Calculator",
    "mask": "facemask.MaskDetector"
  }
}

Element	Type	Description
age	object	detected age range. Return only if age plugin is enabled
gender	object	detected gender. Return only if gender plugin is enabled
pose	object	detected head pose. Return only if pose plugin is enabled
mask	object	detected mask. Return only if face mask plugin is enabled.
embedding	array	face embeddings. Return only if calculator plugin is enabled
box	object	list of parameters of the bounding box for this face
probability	float	probability that a found face is actually a face
x_max, y_max, x_min, y_min	integer	coordinates of the frame containing the face
landmarks	array	list of the coordinates of the frame containing the face-landmarks. Return only if landmarks plugin is enabled
subjects	list	list of similar subjects with size of <prediction_count> order by similarity
similarity	float	similarity that on that image predicted person
subject	string	name of the subject in Face Collection
execution_time	object	execution time of all plugins
plugins_versions	object	contains information about plugin versions

Verify Faces from a Given Image

To compare faces from the uploaded images with the face in saved image ID:

shell

curl -X POST "http://localhost:8000/api/v1/recognition/faces/<image_id>/verify?limit=<limit>&det_prob_threshold=<det_prob_threshold>&face_plugins=<face_plugins>&status=<status>" \
-H "Content-Type: multipart/form-data" \
-H "x-api-key: <service_api_key>" \
-F file=<local_file>

Element	Description	Type	Required	Notes
Content-Type	header	string	required	multipart/form-data
x-api-key	header	string	required	api key of the Face recognition service, created by the user
image_id	variable	UUID	required	UUID of the verifying face
file	body	image	required	allowed image formats: jpeg, jpg, ico, png, bmp, gif, tif, tiff, webp. Max size is 5Mb
limit	param	integer	optional	maximum number of faces on the target image to be recognized. It recognizes the biggest faces first. Value of 0 represents no limit. Default value: 0
det_prob_threshold	param	string	optional	minimum required confidence that a recognized face is actually a face. Value is between 0.0 and 1.0.
face_plugins	param	string	optional	comma-separated slugs of face plugins. If empty, no additional information is returned. Learn more
status	param	boolean	optional	if true includes system information like execution_time and plugin_version fields. Default value is false

Response body on success:

json

{
  "result": [
    {
      "age" : {
        "probability": 0.9308982491493225,
        "high": 32,
        "low": 25
      },
      "gender" : {
        "probability": 0.9898611307144165,
        "value": "female"
      },
      "mask" : {
        "probability": 0.9999470710754395,
        "value": "without_mask"
      },
      "embedding" : [ -0.049007344990968704, "...", -0.01753818802535534 ],
      "box" : {
        "probability" : 0.9997453093528748,
        "x_max" : 205,
        "y_max" : 167,
        "x_min" : 48,
        "y_min" : 0
      },
      "landmarks" : [ [ 260, 129 ], [ 273, 127 ], [ 258, 136 ], [ 257, 150 ], [ 269, 148 ] ],
      "similarity" : 0.97858,
      "execution_time" : {
        "age" : 59.0,
        "gender" : 30.0,
        "detector" : 177.0,
        "calculator" : 70.0,
        "mask": 36.0
      }
    }
  ],
  "plugins_versions" : {
    "age" : "agegender.AgeDetector",
    "gender" : "agegender.GenderDetector",
    "detector" : "facenet.FaceDetector",
    "calculator" : "facenet.Calculator",
    "mask": "facemask.MaskDetector"
  }
}

Element	Type	Description
age	object	detected age range. Return only if age plugin is enabled
gender	object	detected gender. Return only if gender plugin is enabled
pose	object	detected head pose. Return only if pose plugin is enabled
mask	object	detected mask. Return only if face mask plugin is enabled
embedding	array	face embeddings. Return only if calculator plugin is enabled
box	object	list of parameters of the bounding box for this face
probability	float	probability that a found face is actually a face
x_max, y_max, x_min, y_min	integer	coordinates of the frame containing the face
landmarks	array	list of the coordinates of the frame containing the face-landmarks. Return only if landmarks plugin is enabled
similarity	float	similarity that on that image predicted person
execution_time	object	execution time of all plugins
plugins_versions	object	contains information about plugin versions

Face Detection Service

To detect faces from the uploaded image:

shell

curl  -X POST "http://localhost:8000/api/v1/detection/detect?limit=<limit>&det_prob_threshold=<det_prob_threshold>&face_plugins=<face_plugins>&status=<status>" \
-H "Content-Type: multipart/form-data" \
-H "x-api-key: <service_api_key>" \
-F file=<local_file>

Element	Description	Type	Required	Notes
Content-Type	header	string	required	multipart/form-data
x-api-key	header	string	required	api key of the Face Detection service, created by the user
file	body	image	required	image where to detect faces. Allowed image formats: jpeg, jpg, ico, png, bmp, gif, tif, tiff, webp. Max size is 5Mb
limit	param	integer	optional	maximum number of faces on the image to be recognized. It recognizes the biggest faces first. Value of 0 represents no limit. Default value: 0
det_prob_threshold	param	string	optional	minimum required confidence that a recognized face is actually a face. Value is between 0.0 and 1.0
face_plugins	param	string	optional	comma-separated slugs of face plugins. If empty, no additional information is returned. Learn more
status	param	boolean	optional	if true includes system information like execution_time and plugin_version fields. Default value is false

Response body on success:

json

{
  "result" : [ {
    "age" : {
      "probability": 0.9308982491493225,
      "high": 32,
      "low": 25
    },
    "gender" : {
      "probability": 0.9898611307144165,
      "value": "female"
    },
    "mask" : {
      "probability": 0.9999470710754395,
      "value": "without_mask"
    },
    "embedding" : [ -0.03027934394776821, "...", -0.05117142200469971 ],
    "box" : {
      "probability" : 0.9987509250640869,
      "x_max" : 376,
      "y_max" : 479,
      "x_min" : 68,
      "y_min" : 77
    },
    "landmarks" : [ [ 156, 245 ], [ 277, 253 ], [ 202, 311 ], [ 148, 358 ], [ 274, 365 ] ],
    "execution_time" : {
      "age" : 30.0,
      "gender" : 26.0,
      "detector" : 130.0,
      "calculator" : 49.0,
      "mask": 36.0
    }
  } ],
  "plugins_versions" : {
    "age" : "agegender.AgeDetector",
    "gender" : "agegender.GenderDetector",
    "detector" : "facenet.FaceDetector",
    "calculator" : "facenet.Calculator",
    "mask": "facemask.MaskDetector"
  }
}

Element	Type	Description
age	object	detected age range. Return only if age plugin is enabled
gender	object	detected gender. Return only if gender plugin is enabled
pose	object	detected head pose. Return only if pose plugin is enabled
mask	object	detected mask. Return only if face mask plugin is enabled
embedding	array	face embeddings. Return only if calculator plugin is enabled
box	object	list of parameters of the bounding box for this face (on processedImage)
probability	float	probability that a found face is actually a face (on processedImage)
x_max, y_max, x_min, y_min	integer	coordinates of the frame containing the face (on processedImage)
landmarks	array	list of the coordinates of the frame containing the face-landmarks. Return only if landmarks plugin is enabled
execution_time	object	execution time of all plugins
plugins_versions	object	contains information about plugin versions

Face Verification Service

To compare faces from given two images:

shell

curl  -X POST "http://localhost:8000/api/v1/verification/verify?limit=<limit>&prediction_count=<prediction_count>&det_prob_threshold=<det_prob_threshold>&face_plugins=<face_plugins>&status=<status>" \
-H "Content-Type: multipart/form-data" \
-H "x-api-key: <service_api_key>" \
-F source_image=<local_check_file>
-F target_image=<local_process_file>

Element	Description	Type	Required	Notes
Content-Type	header	string	required	multipart/form-data
x-api-key	header	string	required	api key of the Face verification service, created by the user
source_image	body	image	required	file to be verified. Allowed image formats: jpeg, jpg, ico, png, bmp, gif, tif, tiff, webp. Max size is 5Mb
target_image	body	image	required	reference file to check the source file. Allowed image formats: jpeg, jpg, ico, png, bmp, gif, tif, tiff, webp. Max size is 5Mb
limit	param	integer	optional	maximum number of faces on the target image to be recognized. It recognizes the biggest faces first. Value of 0 represents no limit. Default value: 0
det_prob_threshold	param	string	optional	minimum required confidence that a recognized face is actually a face. Value is between 0.0 and 1.0.
face_plugins	param	string	optional	comma-separated slugs of face plugins. If empty, no additional information is returned. Learn more
status	param	boolean	optional	if true includes system information like execution_time and plugin_version fields. Default value is false

Response body on success:

json

{
  "result" : [{
    "source_image_face" : {
      "age" : {
        "probability": 0.9308982491493225,
        "high": 32,
        "low": 25
      },
      "gender" : {
        "probability": 0.9898611307144165,
        "value": "female"
      },
      "mask" : {
        "probability": 0.9999470710754395,
        "value": "without_mask"
      },
      "embedding" : [ -0.0010271212086081505, "...", -0.008746841922402382 ],
      "box" : {
        "probability" : 0.9997453093528748,
        "x_max" : 205,
        "y_max" : 167,
        "x_min" : 48,
        "y_min" : 0
      },
      "landmarks" : [ [ 92, 44 ], [ 130, 68 ], [ 71, 76 ], [ 60, 104 ], [ 95, 125 ] ],
      "execution_time" : {
        "age" : 85.0,
        "gender" : 51.0,
        "detector" : 67.0,
        "calculator" : 116.0,
        "mask": 36.0
      }
    },
    "face_matches": [
      {
        "age" : {
          "probability": 0.9308982491493225,
          "high": 32,
          "low": 25
        },
        "gender" : {
          "probability": 0.9898611307144165,
          "value": "female"
        },
        "mask" : {
          "probability": 0.9999470710754395,
          "value": "without_mask"
        },
        "embedding" : [ -0.049007344990968704, "...", -0.01753818802535534 ],
        "box" : {
          "probability" : 0.99975,
          "x_max" : 308,
          "y_max" : 180,
          "x_min" : 235,
          "y_min" : 98
        },
        "landmarks" : [ [ 260, 129 ], [ 273, 127 ], [ 258, 136 ], [ 257, 150 ], [ 269, 148 ] ],
        "similarity" : 0.97858,
        "execution_time" : {
          "age" : 59.0,
          "gender" : 30.0,
          "detector" : 177.0,
          "calculator" : 70.0,
          "mask": 36.0
        }
      }],
    "plugins_versions" : {
      "age" : "agegender.AgeDetector",
      "gender" : "agegender.GenderDetector",
      "detector" : "facenet.FaceDetector",
      "calculator" : "facenet.Calculator",
      "mask": "facemask.MaskDetector"
    }
  }]
}

Element	Type	Description
source_image_face	object	additional info about source image face
face_matches	array	result of face verification
age	object	detected age range. Return only if age plugin is enabled
gender	object	detected gender. Return only if gender plugin is enabled
pose	object	detected head pose. Return only if pose plugin is enabled
mask	object	detected mask. Return only if face mask plugin is enabled
embedding	array	face embeddings. Return only if calculator plugin is enabled
box	object	list of parameters of the bounding box for this face
probability	float	probability that a found face is actually a face
x_max, y_max, x_min, y_min	integer	coordinates of the frame containing the face
landmarks	array	list of the coordinates of the frame containing the face-landmarks. Return only if landmarks plugin is enabled
similarity	float	similarity between this face and the face on the source image
execution_time	object	execution time of all plugins
plugins_versions	object	contains information about plugin versions

Base64 Support

since 0.5.1 version

Except multipart/form-data, all CompreFace endpoints, that require images as input, accept images in Base64 format. The base rule is to use Content-Type: application/json header and send JSON in the body. The name of the JSON parameter coincides with the name of the multipart/form-data parameter.

Add an Example of a Subject, Base64

Full description here.

shell

curl -X POST "http://localhost:8000/api/v1/recognition/faces?subject=<subject>&det_prob_threshold=<det_prob_threshold>" \
-H "Content-Type: application/json" \
-H "x-api-key: <service_api_key>" \
-d {"file": "<base64_value>"}

Recognize Faces from a Given Image, Base64

Full description here.

shell

curl  -X POST "http://localhost:8000/api/v1/recognition/recognize?limit=<limit>&prediction_count=<prediction_count>&det_prob_threshold=<det_prob_threshold>&face_plugins=<face_plugins>&status=<status>" \
-H "Content-Type: application/json" \
-H "x-api-key: <service_api_key>" \
-d {"file": "<base64_value>"}

Verify Faces from a Given Image, Base64

Full description here.

shell

curl -X POST "http://localhost:8000/api/v1/recognition/faces/<image_id>/verify?
limit=<limit>&det_prob_threshold=<det_prob_threshold>&face_plugins=<face_plugins>&status=<status>" \
-H "Content-Type: application/json" \
-H "x-api-key: <service_api_key>" \
-d {"file": "<base64_value>"}

Face Detection Service, Base64

Full description here.

shell

curl  -X POST "http://localhost:8000/api/v1/detection/detect?limit=<limit>&det_prob_threshold=<det_prob_threshold>&face_plugins=<face_plugins>&status=<status>" \
-H "Content-Type: application/json" \
-H "x-api-key: <service_api_key>" \
-d {"file": "<base64_value>"}

Face Verification Service, Base64

Full description here.

shell

curl -X POST "http://localhost:8000/api/v1/verification/verify?limit=<limit>&prediction_count=<prediction_count>&det_prob_threshold=<det_prob_threshold>&face_plugins=<face_plugins>&status=<status>" \
-H "Content-Type: application/json" \
-H "x-api-key: <service_api_key>" \
-d {"source_image": "<source_image_base64_value>", "target_image": "<target_image_base64_value>"}

Recognition and verification using embedding

since 1.2.0 version

You can use computed embedding to perform recognition and verification. To obtain embedding, you can use calculator plugin in each Face service. The base rule is to use Content-Type: application/json header and send JSON in the body.

Recognize Faces from a Given Image, Embedding

The service is used to determine similarities between input embeddings and embeddings within the Face Collection. An example:

shell

curl -X POST "http://localhost:8000/api/v1/recognition/embeddings/recognize?prediction_count=<prediction_count>" \
-H "Content-Type: application/json" \
-H "x-api-key: <service_api_key>" \
-d {"embeddings": [[<array_of_embedding>], ...]}

Element	Description	Type	Required	Notes
Content-Type	header	string	required	application/json
x-api-key	header	string	required	an api key of the Face recognition service, created by the user
embeddings	body	array	required	an input embeddings. The length depends on the model (e.g. 512 or 128)
prediction_count	param	integer	optional	the maximum number of subject predictions per embedding. It returns the most similar subjects. Default value: 1

Response body on success:

json

{
  "result": [
    {
      "embedding": [0.0627421774604647, "...", -0.0236684433507126],
      "similarities": [
        {
          "subject": "John",
          "similarity": 0.55988
        },
        "..."
      ]
    },
    "..."
  ]
}

Element	Type	Description
result	array	an array that contains all the results
embedding	array	an input embedding
similarities	array	an array that contains results of similarity between the embedding and the input embedding
subject	string	a subject in which the similar embedding was found
similarity	float	a similarity between the embedding and the input embedding

Verify Faces from a Given Image, Embedding

The endpoint is used to compare input embeddings to the embedding stored in Face Collection. An example:

shell

curl -X POST "http://localhost:8000/api/v1/recognition/embeddings/faces/{image_id}/verify" \
-H "Content-Type: application/json" \
-H "x-api-key: <service_api_key>" \
-d {"embeddings": [[<array_of_embeddings>], ...]}

Element	Description	Type	Required	Notes
Content-Type	header	string	required	application/json
x-api-key	header	string	required	api key of the Face recognition service, created by the user
embeddings	body	array	required	an input embeddings. The length depends on the model (e.g. 512 or 128)
image_id	variable	UUID	required	an id of the source embedding within the Face Collection

Response body on success:

json

{
  "result": [
    {
      "embedding": [0.0627421774604647, "...", -0.0236684433507126],
      "similarity": 0.55988
    },
    "..."
  ]
}

Element	Type	Description
result	array	an array that contains all the results
embedding	array	a source embedding which we are comparing to embedding from Face Collection
similarity	float	a similarity between the source embedding and embedding from Face Collection

Face Verification Service, Embedding

The service is used to determine similarities between an input source embedding and input target embeddings. An example:

shell

curl -X POST "http://localhost:8000/api/v1/verification/embeddings/verify" \
-H "Content-Type: application/json" \
-H "x-api-key: <service_api_key>" \
-d {"source": [<source_embedding>], "targets": [[<target_embedding>], ...]}

Element	Description	Type	Required	Notes
Content-Type	header	string	required	application/json
x-api-key	header	string	required	api key of the Face verification service, created by the user
source	body	array	required	an input embeddings. The length depends on the model (e.g. 512 or 128)
targets	body	array	required	an array of the target embeddings. The length depends on the model (e.g. 512 or 128)

Response body on success:

json

{
  "result": [
    {
      "embedding": [0.0627421774604647, "...", -0.0236684433507126],
      "similarity": 0.55988
    },
    "..."
  ]
}

Element	Type	Description
result	array	an array that contains all the results
embedding	array	a target embedding which we are comparing to source embedding
similarity	float	a similarity between the source embedding and the target embedding

Rest API description

Rest API description

Table Of Contents

Postman documentation

Face Recognition Service

Managing Subjects

Add a Subject

Rename a Subject

Delete a Subject

Delete All Subjects

List Subjects

Managing Subject Examples

Add an Example of a Subject

List of All Saved Examples of the Subject

Delete All Examples of the Subject by Name

Delete an Example of the Subject by ID

Delete Multiple Examples

Direct Download an Image example of the Subject by ID

Download an Image example of the Subject by ID

Recognize Faces from a Given Image

Verify Faces from a Given Image

Face Detection Service

Face Verification Service

Base64 Support

Add an Example of a Subject, Base64

Recognize Faces from a Given Image, Base64

Verify Faces from a Given Image, Base64

Face Detection Service, Base64

Face Verification Service, Base64

Recognition and verification using embedding

Recognize Faces from a Given Image, Embedding

Verify Faces from a Given Image, Embedding

Face Verification Service, Embedding