# Face Comparison

### Headers

| Header          | Value                                                                |
| --------------- | -------------------------------------------------------------------- |
| `Content-Type`  | `application/json`                                                   |
| `Authorization` | `Bearer` [`YOUR_API_KEY`](https://docs.kredibel.io/authentication-1) |

### **Model**

Kredibel provide two different option of model for face recognition. Every model has its own advantages and disadvantages. We recommend you to try both of the model before deciding which model is the best fit for your case.

| Version | Description                                                                                                               | Threshold                                  |
| ------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| **1**   | Model version 1 is the default model used for face recognition task. The model extract 512 facial features (landmarks).   | <p>< 0.80: not match<br>>= 0.80: match</p> |
| 2       | Model version 2 is the another model option for face recognition task. The model extract 128 facial features (landmarks). | <p>< 0.80: not match<br>>= 0.80: match</p> |

## **Non-Handheld**

### Endpoint

| Method | URL                                  |
| ------ | ------------------------------------ |
| POST   | `$vision`**`/v1/face/verification`** |

### **Request**

{% tabs %}
{% tab title="Description" %}

| Field                  | Type             | Description                                                                                                                                          |
| ---------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| image1                 | `<base64:image>` | <p>Image binary encoded in base64 without \<data:image/png;>.<br>- <strong>Supports:</strong> JPG, JPEG, PNG<br>- <strong>Max Size:</strong> 2MB</p> |
| image2                 | `<base64:image>` | <p>Image binary encoded in base64 without \<data:image/png;>.<br>- <strong>Supports:</strong> JPG, JPEG, PNG<br>- <strong>Max Size:</strong> 2MB</p> |
| [modelVersion](#model) | `Integer`        | Model version used to recognize the faces. Default version is 1.                                                                                     |
| threshold              | `Float (0-1)`    | Threshold of the matched faces.                                                                                                                      |
| {% endtab %}           |                  |                                                                                                                                                      |

{% tab title="Example" %}

```
{
    "image1": "<base64:image>",
    "image2": "<base64:image>"
}
```

{% endtab %}
{% endtabs %}

### **Response**

{% tabs %}
{% tab title="Description" %}

| Field        | Type          | Description                             |
| ------------ | ------------- | --------------------------------------- |
| similarity   | `Float (0-1)` | Similarity value between the two images |
| matched      | `Boolean`     | Matched                                 |
| {% endtab %} |               |                                         |

{% tab title="Example" %}

```
{
    "message": "face verification succeded",
    "data": {
        "id": "8f9efedc-d5bf-11eb-9953-5517feb46cc4",
        "similarity": 0.7396538793680758,
        "matched": true
    }
}
```

{% endtab %}
{% endtabs %}

## Handheld

### Endpoint

|        |                                               |
| ------ | --------------------------------------------- |
| Method | URL                                           |
| POST   | `$vision`**`/v1/face/verification/handheld`** |

### **Request**

{% tabs %}
{% tab title="Description" %}

| Field                  | Type             | Description                                                                                                                                          |
| ---------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| image                  | `<base64:image>` | <p>Image binary encoded in base64 without \<data:image/png;>.<br>- <strong>Supports:</strong> JPG, JPEG, PNG<br>- <strong>Max Size:</strong> 2MB</p> |
| [modelVersion](#model) | `Integer`        | Model version used to recognize the faces. Default version is 1.                                                                                     |
| threshold              | `Float (0-1)`    | Threshold of the matched faces.                                                                                                                      |
| {% endtab %}           |                  |                                                                                                                                                      |

{% tab title="Example" %}

```
{
    "image": "<base64:image>"
}
```

{% endtab %}
{% endtabs %}

### **Response**

{% tabs %}
{% tab title="Description" %}

| Field        | Type          | Description                             |
| ------------ | ------------- | --------------------------------------- |
| similarity   | `Float (0-1)` | Similarity value between the two images |
| matched      | `Boolean`     | Matched                                 |
| {% endtab %} |               |                                         |

{% tab title="Example" %}

```
{
    "message": "face verification succeded",
    "data": {
        "id": "8f9efedc-d5bf-11eb-9953-5517feb46cc4",
        "similarity": 0.7396538793680758,
        "matched": true
    }
}
```

{% endtab %}
{% endtabs %}

### **Errors**

{% hint style="info" %}
Please read this [page \<Responses & Errors>](https://docs.kredibel.io/responses-and-errors) to know more about response.
{% endhint %}

**Error 4XX**

{% tabs %}
{% tab title="Error Type" %}

<table><thead><tr><th width="266">Error Type</th><th width="352.3333333333333">Description</th><th>Is charged?</th></tr></thead><tbody><tr><td>invalid_base64_encoding</td><td>Invalid base64 encoding.</td><td><strong>false</strong></td></tr><tr><td>no_face_detected</td><td>No face was detected from one of the images or both images.</td><td><strong>true</strong></td></tr></tbody></table>
{% endtab %}

{% tab title="Structure" %}

```
{
   "errors":{
      "errorId": <log_id:uuid>,
      "errorType": <error_type:str>
   },
   "message": <message:str>
}
```

{% endtab %}
{% endtabs %}

**Error 5XX**

**F**or every 5XX http code response, there will be no charge.