Face Identification

Searches for the most similar face template in your database using the submitted photo. This is a 1:N search, returning the best match (if any) from all stored templates.

You may optionally enable liveness and deepfake detection via query parameters.

Endpoint

POST https://cloud.ooto-ai.com/api/v1.0/identify

Request Format

• Method: POST

• Content-Type: multipart/form-data

• Query Parameters: check_liveness, check_deepfake

Query Parameters

Name	Type	Required	Description
check_liveness	Boolean	No	Enable liveness detection
check_deepfake	Boolean	No	Enable deepfake detection

Form Data

Field	Type	Required	Description
photo	File	Yes	JPEG or PNG image with one clear face

Authentication Headers

To access the API, you need to include the following headers in your request:

• APP-ID: Your application's unique identifier.

• APP-KEY: Your application's authentication key.

Example Request (cURL)

curl -X POST --location 'https://cloud.ooto-ai.com/api/v1.0/identify?check_liveness=true&check_deepfake=true' \
--header 'APP-ID: <put_app_id_here>' \
--header 'APP-KEY: <put_app_key_here>' \
--form 'photo=@"/path/to/photo"'

Replace «put_app_id_here», «put_app_key_here» with your actual credentials and the path to your selfie image.

Successful Response (HTTP 200)

{
    "transactionId": "ce394cea-a3cf-4044-8ce8-54e398dda667",
    "result": {
        "templateId": "e85098dd-4667-4a91-a0a0-adf5b8e9336d",
        "similarity": 1,
        "face": {
            "box": {
                "x": 25,
                "y": 275,
                "w": 606,
                "h": 761
            },
            "landmarks": [
                [
                    230,
                    574
                ],
                [
                    457,
                    567
                ],
                [
                    369,
                    740
                ],
                [
                    248,
                    802
                ],
                [
                    444,
                    796
                ]
            ],
            "liveness": {
                "score": 0.8860905766487122,
                "fine": true
            },
            "deepfake": {
                "score": 0.9506649971008301,
                "fine": true
            },
            "quality": {
                "uniformity": {
                    "value": 0.7044515103338633,
                    "fine": true
                },
                "exposure": {
                    "value": 0.5734725113730128,
                    "fine": true
                },
                "contrast": {
                    "value": 0.5869247898479624,
                    "fine": true
                },
                "flare": {
                    "score": 0.997887909412384,
                    "fine": false
                },
                "blur": {
                    "score": 0.0012071678647771478,
                    "fine": true
                },
                "occlusion": {
                    "score": 0.8302246928215027,
                    "fine": false
                },
                "macroblocks": {
                    "score": 0.0000013804340142087312,
                    "fine": true
                },
                "emotion": {
                    "score": 0.0040520974434912205,
                    "fine": true
                },
                "right_eye_closed": {
                    "score": 0.9050158113241196,
                    "fine": false
                },
                "left_eye_closed": {
                    "score": 0.0009260773658752441,
                    "fine": true
                },
                "crfiqa": {
                    "score": 0.5428674221038818,
                    "fine": false
                },
                "distortion": {
                    "score": 0.3051091432571411,
                    "fine": true
                },
                "gender": "male",
                "age": 62,
                "race": "white",
                "pitch": 17.443319857120514,
                "yaw": 10.05310446023941,
                "roll": 1.412617564201355
            }
        }
    }
}

Field Explanation

Field	Description
templateId	ID of the most similar template found in the database
similarity	Cosine similarity between input and matched template
liveness	Returned if check_liveness=true
deepfake	Returned if check_deepfake=true
face	Face detection details from input photo

Error Response (HTTP 400)

{
    "transactionId": "9191079a-4f80-4c8a-9a4b-528af2cfd3c4",
    "result": {
        "status": "error",
        "code": 1,
        "info": "photo should not be empty"
    }
}

Engine Errors

Code	Info
1	photo should not be empty
2	wrong mime-type in input data
3	photo size is 0 bytes
4	can not decode image, check it is valid jpeg or png file
5	can not detect face
6	more than one face detected on photo
9	can not extract features from sample, probably it is too small

Best Practices

• Use high-quality, well-lit, frontal photos

• Make sure there’s only one visible face

• Use check_liveness in environments with higher spoofing risk

• Typical similarity threshold for a valid match: ≥ 0.75