Face Recognition
Module Description

Face Recognition detects and identifies the faces of public figures in a variety of categories such as politics, sports, business and entertainment. This module covers more than 20.000 personalities, including the world's most famous people and a vast majority of German politicians and athletes.
Module ID: face_recognition
Module Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| model | string | celebrities | The name or the ID of the model to use (See Model Resource). |
| models | list | null | Optional list of names or IDs for multiple models (list of strings). E.g. custom models can be combined with the pre-trained celebrity model. |
| max_distance | number | 1.0 | Thresholding the distance, how similar (in terms of euclidean distance) the recognized identity is to the closest sample in the training data (range from 0.0 to 2.0). |
| cluster_unknowns | boolean | false | Whether to give individual results for unknown identities or not (Unknown #1, Unknown #2, ..). |
| index_unknowns | boolean | false | Whether to index unknown identities with a unique ID or not (The index is accessible on the left menu bar). This parameter overrides cluster_unknowns since clustering of unknown identities is required for indexing. |
| index_collection_name | string | face_test_env | Name of the index collection in which unknown identities are indexed if index_unknowns is enabled. Only letters, digits and underscores (_) are allowed. |
| face_detection_scale | number | 600 | Increase the value in order to allow to detect smaller faces (range from 100 to 2000). |
| face_sharpness | integer | 40 | Minimum sharpness score a detected face must have to be used for recognition (range from 0 to 100). Higher values require faces to be more in focus and reject more blurry faces; lower values also accept blurrier faces, at the cost of potentially less accurate recognition. 0 disables the sharpness filter. Typical values range from 20 (permissive) to 40 (strict). |
| enable_top_k | boolean | false | Enable the top-k prediction which returns the top k most similar identities. Example response can be found here. |
| top_k | integer | 3 | The number of top-k predictions to return (range from 1 to 10). |
Pre-trained models
| Name | Description |
|---|---|
| celebrities | 20.000 personalities, including the world's most famous people and a vast majority of German politicians and athletes |
Example
Send the following JSON as request body via POST to the /jobs/ endpoint:
{
"sources": [
"{url-to-your-image}"
],
"modules": {
"face_recognition": {
"model": "celebrities"
}
}
}
When requesting the job via GET on the /jobs/{JOB_ID}/ endpoint, the response looks like this:
{
"id": "ae246648-50d7-4058-b0b0-e7f6a4ac650e",
"tag": "",
"state": "completed",
"errors": [],
"progress": 1,
"duration": 104.936,
"time_created": "2021-05-20 09:34:37.135000",
"time_started": "2021-05-20 09:34:37.267000",
"time_completed": "2021-05-20 09:36:22.203000",
"sources": [
"storage://WQM2S9L9O0tDYacfNQN7"
],
"modules": {
"face_recognition": {
"model": "celebrities",
"state": "completed",
"progress": 1
}
},
"media_type": "video",
"result": {
"detailed_link": "http://api.deepva.com/api/v1/jobs/ae246648-50d7-4058-b0b0-e7f6a4ac650e/detailed-results",
"summary": [
{
"source": "storage://WQM2S9L9O0tDYacfNQN7",
"media_type": "video",
"info": {
"fps": 25.0,
"resolution": [
960,
540
],
"total_frames": 3636,
"duration": 145.44
},
"items": [
{
"type": "face",
"label": "John Doe",
"module": "face_recognition"
},
{
"type": "face",
"label": "Jane Doe",
"module": "face_recognition"
}
]
}
]
}
}
To get detailed information about the predicted person (for example the time code) you can request the /jobs/{JOB_ID}/detailed-results/ endpoint, the response looks like this:
{
"total": 28,
"offset": 0,
"limit": 10,
"next": "https://api.deepva.com/api/v1/jobs/ae246648-50d7-4058-b0b0-e7f6a4ac650e/detailed-results/?limit=10&offset=10",
"prev": "https://api.deepva.com/api/v1/jobs/ae246648-50d7-4058-b0b0-e7f6a4ac650e/detailed-results/?limit=10&offset=0",
"data": [
{
"id": "d2fd5425-4d2f-4cd9-8eb7-39cd632a740d",
"media_type": "video",
"frame_start": 12,
"frame_end": 56,
"source": "storage://WQM2S9L9O0tDYacfNQN7",
"module": "face_recognition",
"meta": {
"person": "John Doe",
"class_id": null,
"closest_person": null,
"mean_distance": 0.93,
"mean_similarity": 0.57,
"indexed_identity": null
},
"thumbnail": {
"image": "<base64 encoded image>",
"meta": {}
},
"detections": [
{
"frame_index": 12,
"type": "face_bbox",
"data": {
"x": 0.637,
"y": 0.167,
"w": 0.088,
"h": 0.222
}
},
{
"frame_index": 24,
"type": "face_bbox",
"data": {
"x": 0.633,
"y": 0.17,
"w": 0.086,
"h": 0.22
}
},
{
"frame_index": 36,
"type": "face_bbox",
"data": {
"x": 0.634,
"y": 0.159,
"w": 0.09,
"h": 0.231
}
},
{
"frame_index": 48,
"type": "face_bbox",
"data": {
"x": 0.639,
"y": 0.161,
"w": 0.089,
"h": 0.231
}
}
],
"time_start": 0.48,
"time_end": 2.24,
"tc_start": "00:00:00:12",
"tc_end": "00:00:02:06"
},
{
"id": "038bea16-b727-41a5-af66-e3cb80fe1025",
"media_type": "video",
"frame_start": 12,
"frame_end": 56,
"source": "storage://WQM2S9L9O0tDYacfNQN7",
"module": "face_recognition",
"meta": {
"person": "Jane Doe",
"class_id": null,
"closest_person": null,
"mean_distance": 0.89,
"mean_similarity": 0.6,
"indexed_identity": null
},
"thumbnail": {
"image": "<base64 encoded image>",
"meta": {}
},
"detections": [
{
"frame_index": 12,
"type": "face_bbox",
"data": {
"x": 0.83,
"y": 0.146,
"w": 0.096,
"h": 0.222
}
},
{
"frame_index": 24,
"type": "face_bbox",
"data": {
"x": 0.82,
"y": 0.139,
"w": 0.095,
"h": 0.215
}
},
{
"frame_index": 36,
"type": "face_bbox",
"data": {
"x": 0.824,
"y": 0.135,
"w": 0.094,
"h": 0.211
}
},
{
"frame_index": 48,
"type": "face_bbox",
"data": {
"x": 0.826,
"y": 0.131,
"w": 0.097,
"h": 0.211
}
}
],
"time_start": 0.48,
"time_end": 2.24,
"tc_start": "00:00:00:12",
"tc_end": "00:00:02:06"
}
]
}
Example for a detailed-results response with top-k enabled:
If enable_top_k is set to true the closest_k_persons field in the detailed results object's meta field contains a list of alternative predictions (most similar).
Each person's name is given via the person field. The similarity is returned as well to indicate how close the person is to the person in the model.
{
"total":16,
"offset":0,
"limit":10,
"next":"https://api.deepva.com/api/v2/jobs/0523c505-a939-4b9a-be41-f89d24c51810/detailed-results/?limit=100&offset=100",
"prev":"https://api.deepva.com/api/v2/jobs/0523c505-a939-4b9a-be41-f89d24c51810/detailed-results/?limit=100&offset=0",
"data":[
{
"id":"e51c1e49-bbac-4dbf-b31a-7e8217abf865",
"media_type":"video",
"frame_start":1036,
"frame_end":1218,
"source":"storage://jRsMJzpOkC3Yk59hKEIA",
"module":"face_recognition",
"meta":{
"person":"Olaf Scholz",
"class_id":null,
"knowledge_graph_node_id":2017205,
"image_ids":[
],
"closest_person":null,
"closest_k_persons":[
{
"person":"Olaf Scholz",
"similarity":0.6
},
{
"person":"Tim Johnson",
"similarity":0.3
},
{
"person":"Jean Marais",
"similarity":0.3
}
],
"mean_distance":0.865,
"mean_similarity":0.625,
"indexed_identity":null
},
"thumbnail":{
"image":"<BASE_64_STRING>",
"meta":{}
},
"detections":[],
"time_start":20.72,
"time_end":24.36,
"tc_start":"00:00:20:35",
"tc_end":"00:00:24:17"
},
...
]
}