# Face Identification

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

#### Endpoint

```bash
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

<table data-header-hidden><thead><tr><th width="187"></th><th></th><th></th><th></th></tr></thead><tbody><tr><td>Name</td><td>Type</td><td>Required</td><td>Description</td></tr><tr><td>check_liveness</td><td>Boolean</td><td>No</td><td>Enable liveness detection</td></tr><tr><td>check_deepfake</td><td>Boolean</td><td>No</td><td>Enable deepfake detection</td></tr></tbody></table>

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

```bash
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)

{% code fullWidth="false" %}

```json
{
  "transactionId": "e911ef43-3102-40bb-80f3-037b91a4bbfd",
  "result": {
    "search": {
      "templateId": "16de28ea-dd15-4005-9a42-539e911db2d3",
      "similarity": 0.7977402806282043
    },
    "box": {
      "x": 70,
      "y": 308,
      "w": 560,
      "h": 700
    },
    "landmarks": [
      [
        231,
        574
      ],
      [
        460,
        567
      ],
      [
        379,
        736
      ],
      [
        253,
        808
      ],
      [
        452,
        800
      ]
    ],
    "liveness": {
      "score": 0.8332664312042404,
      "fine": false
    },
    "deepfake": {
      "score": 0.9484865963459015,
      "fine": true
    },
    "quality": {
      "uniformity": {
        "value": 0.7094009533638017,
        "fine": true
      },
      "exposure": {
        "value": 0.56348490191915,
        "fine": true
      },
      "contrast": {
        "value": 0.5916379668502664,
        "fine": true
      },
      "flare": {
        "score": 0.9966791272163391,
        "fine": false
      },
      "blur": {
        "score": 0.00035461210063658655,
        "fine": true
      },
      "occlusion": {
        "score": 0.6792494058609009,
        "fine": false
      },
      "macroblocks": {
        "score": 5.95949359194492e-7,
        "fine": true
      },
      "emotion": {
        "score": 0.018047181889414787,
        "fine": true
      },
      "leftEyeClosed": {
        "score": 0.0006224513053894043,
        "fine": true
      },
      "rightEyeClosed": {
        "score": 0.991077727638185,
        "fine": false
      },
      "crfiqa": {
        "score": 0.5303798913955688,
        "fine": false
      },
      "distortion": {
        "score": 0.2309398055076599,
        "fine": true
      },
      "gender": "male",
      "age": 59,
      "race": "middle eastern",
      "pitch": 16.22133895754814,
      "yaw": 12.984667718410492,
      "roll": 1.9543040916323662
    },
    "demography": {
      "gender": "male",
      "age": 59,
      "race": "middle eastern"
    }
  }
}
```

{% endcode %}

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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ooto-ai.com/face-api-1-n/face-identification.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.