- 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.
There is a Postman REST API documentation that covers the same REST endpoint. Postman documentation supports snippets on the most popular programming languages.
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.
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.
curl -X POST "https://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:
{
"subject": "<subject_name>"
}
Element | Type | Description |
---|---|---|
subject | string | is the name of the 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.
curl -X PUT "https://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:
{
"updated": "true|false"
}
Element | Type | Description |
---|---|---|
updated | boolean | failed or success |
since 0.6 version
Delete existing subject and all saved faces.
curl -X DELETE "https://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:
{
"subject": "<subject_name>"
}
Element | Type | Description |
---|---|---|
subject | string | is the name of the subject |
since 0.6 version
Delete all existing subjects and all saved faces.
curl -X DELETE "https://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:
{
"deleted": "<count>"
}
Element | Type | Description |
---|---|---|
deleted | integer | number of deleted subjects |
since 0.6 version
This returns all subject related to Face Collection.
curl -X GET "https://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:
{
"subjects": [
"<subject_name1>",
"<subject_name2>"
]
}
Element | Type | Description |
---|---|---|
subjects | array | the list of subjects in Face Collection |
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.
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.
curl -X POST "https://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:
{
"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 |
To retrieve a list of subjects saved in a Face Collection:
curl -X GET "https://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 | 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 |
To delete all image examples of the :
curl -X DELETE "https://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 |
Endpoint to delete an image by ID. If no image found by id - 404.
curl -X DELETE "https://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 | of the person, whose picture was saved for this api key |
since 1.0 version
To delete several subject examples:
curl -X POST "https://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
since 0.6 version
You can paste this URL into the html tag to show the image.
curl -X GET "https://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.
since 0.6 version
To download an image example of the Subject by ID:
curl -X GET "https://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.
To recognize faces from the uploaded image:
curl -X POST "https://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:
{
"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 |
To compare faces from the uploaded images with the face in saved image ID:
curl -X POST "https://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:
{
"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 |
To detect faces from the uploaded image:
curl -X POST "https://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:
{
"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 |
To compare faces from given two images:
curl -X POST "https://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:
{
"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 |
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.
Full description here.
curl -X POST "https://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>"}
Full description here.
curl -X POST "https://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>"}
Full description here.
curl -X POST "https://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>"}
Full description here.
curl -X POST "https://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>"}
Full description here.
curl -X POST "https://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>"}
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.
The service is used to determine similarities between input embeddings and embeddings within the Face Collection. An example:
curl -X POST "https://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:
{
"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 |
The endpoint is used to compare input embeddings to the embedding stored in Face Collection. An example:
curl -X POST "https://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:
{
"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 |
The service is used to determine similarities between an input source embedding and input target embeddings. An example:
curl -X POST "https://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:
{
"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 |