# ID Document Liveness Detection SDK

## Features

* [x] ID document Liveness Check
* [x] Document Detection
* [x] Preveinting Screen Replay Attacks
* [x] Preventing Printed Copy Attacks
* [x] Preventing Portrait Substitution Attacks
* [x] Available with Docker Image

## System Requirement

### 1. Windows

* **`CPU`:** `2` cores or more (Recommended: `2` cores)
* **`RAM`:** `4 GB` or more (Recommended: `8 GB`)
* `HDD`: `4 GB` or more (Recommended: `8 GB`)
* **`OS`:** Windows 7 or later
* **Architecture:** `x64`

### 2. Linux

* **`CPU`:** `2` cores or more (Recommended: `2` cores)
* **`RAM`:** `4 GB` or more (Recommended: `8 GB`)
* `HDD`: `4 GB` or more (Recommended: `8 GB`)
* **`OS`:** `Ubuntu 20.04` or later
* **Architecture:** `x64`

## How to Run SDK from Docker Image

> pull docker image

```bash
sudo docker pull kbyai/idl:latest
```

> run docker

```bash
sudo docker run -v ./license.txt:/root/kby-ai-idl/license.txt -p 7860:7860 -p 9005:9000 kbyai/idl:latest
```

## SDK License

The `Docker` image utilizes `KBY-AI`'s `SDK`, which requires a license for each machine or instance on which it runs.

* To get a `machine code` (`HWID`) for license, run the following command:

```bash
sudo docker run -e LICENSE="xxxxx" kbyai/idl:latest
```

* To request the license, please provide us with the `machine code` (`HWID`) obtained from your console.

<figure><img src="https://2589216230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1WwtQK0VFwKRGmIjGA3I%2Fuploads%2FQRr8XS2T8Sv215hoCoCz%2Fidlive-hwid.png?alt=media&#x26;token=3763feff-5f93-4108-807c-f9569cd8f191" alt=""><figcaption></figcaption></figure>

We offer `lifetime license(perpetual license)` tied to `machine code (HWID)` from the server. The license is available for `one-time payment`.

{% embed url="<https://wa.me/+19092802609>" %}

{% embed url="<https://t.me/kbyaisupport>" %}

{% embed url="<https://discord.gg/6wm383re2s>" %}

{% embed url="<https://teams.live.com/l/invite/FBAYGB1-IlXkuQM3AY>" %}

> Email: `contact@kby-ai.com`

## Test API in KBY-AI Online Demo Page

The `SDK` can be tested against static image [here](https://web.kby-ai.com/).

<figure><img src="https://2589216230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1WwtQK0VFwKRGmIjGA3I%2Fuploads%2FAApItYWsI3daYnll5tqA%2Fidlive-online-demp.png?alt=media&#x26;token=f44d294c-3e9f-4847-aa46-cf2dd5b12d83" alt=""><figcaption></figcaption></figure>

## Test API with Gradio Demo

To test the `Gradio` demo from the `Docker` image, access it at [http://127.0.0.1:7860](http://127.0.0.1:7860/) or [http://localhost:7860](http://localhost:7860/) after running `Docker` container.

<figure><img src="https://2589216230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1WwtQK0VFwKRGmIjGA3I%2Fuploads%2F38LozbE4BkRNK1oiHVJq%2FScreenshot%202025-12-04%20182627.png?alt=media&#x26;token=a1823848-53d0-4efe-b992-65ad4fbc0a9a" alt=""><figcaption></figcaption></figure>

## API Instruction

`API` can be tested through `Postman` based on the following `endpoint` details.

### 1. Processing Image with File

* `API` endpoint: `<base URL>/process_image`
* Method: `POST`
* Content-type: `multipart/form-data`
* Request Parameters:

  | Parameter | Type | Description                                              |
  | --------- | ---- | -------------------------------------------------------- |
  | image     | File | ID document image file with `*.jpg` or `*.png` extension |
* Request example

<figure><img src="https://2589216230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1WwtQK0VFwKRGmIjGA3I%2Fuploads%2FLuBl54DhECs4fAm7UEcI%2F521658203-97516d98-06ce-4f20-acd6-04ae942a3ad0.png?alt=media&#x26;token=f2afe6f4-7295-44d8-abe6-09c0bedbd3e5" alt=""><figcaption></figcaption></figure>

### &#x20;2. Processing with Base64-Encoded String

* `API` endpoint: `<base URL>/process_image_base64`
* Method: `POST`
* Content-type: `application/json`
* Request Parameters:<br>

  | Parameter | Type   | Description                                        |
  | --------- | ------ | -------------------------------------------------- |
  | base64    | String | The base64-encoded string of the ID document image |
* Request example

<figure><img src="https://2589216230-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1WwtQK0VFwKRGmIjGA3I%2Fuploads%2FUKjV27LYOGUlPfKtjk7y%2FScreenshot%202025-12-05%20205353.png?alt=media&#x26;token=747ee016-982c-473a-8863-acf21c22c059" alt=""><figcaption></figcaption></figure>

## API Response Description in JSON

### 1. portraitReplace:

* Type: `Float`
* Description: A score indicating the likelihood that the portrait on the ID document has been tampered with or replaced. Higher values (closer to 1) suggest the portrait is likely original, while lower values may indicate potential tampering.

### 2. printedCopy:

* Type: `Float`
* Description: A score that assesses whether the document is a printed copy rather than an original document. Values close to zero suggest the document might be a printed copy, while higher values indicate originality.

### 3. screenReply:

* Type: `Float`
* Description: A score that determines if the document was displayed on a screen rather than being a physical ID. Lower values (closer to zero) imply a higher likelihood that the document is displayed on a screen.

### 4. Result status:

* Type: `String`
* Description: Indicates the status of the liveness check on the document. "Ok" typically means that the document passed initial verification. Other statuses could indicate different levels of authenticity or potential issues with the document.
* Status: `Ok`, `Too close to camera!`, `Too close to border!`, `Document cropped!`, `Too small!`, `Multiple documents`, `Is Colorless!`, `Document not found!`, `Unknown`
* Resonpse Example:

```json
{
    "result": {
        "portraitReplace": 0.590566158294678,
        "printedCopy": 2.0435e-11,
        "screenReply": 0.002031173091382,
        "status": "Ok"
    },
    "resultCode": "Ok"
}
```