# 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"
}
```


---

# 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.kby-ai.com/help/product/id-document-liveness-detection-sdk.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.