Skip to content

Face Recognition

Module Description

Face Recognition

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).
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).

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"
        }
    ]
}