Skip to content

Latest commit

 

History

History
960 lines (810 loc) · 53 KB

Rest-API-description.md

File metadata and controls

960 lines (810 loc) · 53 KB
Raw

Rest API description

Table Of Contents

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.

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:

{
  "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.

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:

{
  "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.

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:

{
  "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.

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:

{
  "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.

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:

{
  "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.

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:

{
  "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:

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 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 :

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.

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 of the person, whose picture was saved for this api key

Delete Multiple Examples

since 1.0 version

To delete several subject examples:

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.

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:

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:

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:

{
  "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:

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:

{
  "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:

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:

{
  "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:

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:

{
  "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.

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.

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.

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.

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.

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:

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:

{
  "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:

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:

{
  "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:

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:

{
  "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