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. |
| face_detection_scale | number | 600 | Increase the value in order to allow to detect smaller faces (range from 100 to 2000). |
| 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"
},
...
]
}