# Face Comparison

### Headers

| Header          | Value                                           |
| --------------- | ----------------------------------------------- |
| `Content-Type`  | `application/json`                              |
| `Authorization` | `Bearer` [`YOUR_API_KEY`](/authentication-1.md) |

### **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>](/responses-and-errors.md) 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.


---

# 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.kredibel.io/api-references/face-recognition/face-comparison.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.