> For the complete documentation index, see [llms.txt](https://spoofsense.gitbook.io/spoofsense-triton-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://spoofsense.gitbook.io/spoofsense-triton-documentation/api-usage.md).

# API Usage

## Authentication

You will require **x-api-key** in order to use the API. 

Contact *<kartikeya@spoofsense.com>* in case you do not already have it.&#x20;

## 1. POST /antispoofing

Performs a Passive Liveness Check.&#x20;

Detects all types of PAD attacks under ISO 30107 Level-2

```
https://z3jwq0rjyj.execute-api.ap-south-1.amazonaws.com/prod/antispoofing
```

## 2. /v3/antispoofing

Our latest SpoofSense FaceLive V3 model for higher-security workflows.&#x20;

```
https://z3jwq0rjyj.execute-api.ap-south-1.amazonaws.com/prod/v3/antispoofing
```

### Response

### Understanding the Response

Following table shows the API responses and behaviours in different cases

<table><thead><tr><th width="136">HTTP Code</th><th width="151.33333333333331">Type of Image</th><th>Raw Output</th></tr></thead><tbody><tr><td>200</td><td>Live Face </td><td><p></p><pre class="language-json"><code class="lang-json">{
    "success": true,
    "message": "Process finished successfully",
    "model_output": {
        "pred_idx": "real",
        "prob_real": 0.9997915625572205
}
</code></pre></td></tr><tr><td>200</td><td>Spoof Face</td><td><p></p><pre class="language-json"><code class="lang-json">{
    "success": true,
    "message": "Process finished successfully",
    "model_output": {
        "pred_idx": "spoof",
        "prob_real": 0.00045343424235454
}
</code></pre></td></tr><tr><td>200</td><td>No Face</td><td><p></p><pre class="language-json"><code class="lang-json">{
    "success": false,
    "message": "Face detection failed",
    "error_code": "FACE_NOT_DETECTED"
}
</code></pre></td></tr><tr><td>200</td><td>Bad Input</td><td><p></p><pre class="language-json"><code class="lang-json">{
    "success": false,
    "message": "Invalid input image payload",
    "error_code": "INVALID_IMAGE_PAYLOAD"
}
</code></pre></td></tr><tr><td>413</td><td>Image Size > 10MB</td><td><pre class="language-json"><code class="lang-json">HTTP content length exceeded 10485760 bytes.
</code></pre></td></tr><tr><td>200</td><td>Face Size &#x3C; 224X224 pixels</td><td><pre class="language-json"><code class="lang-json">{
    "success": false,
    "message": "Detected face box: {Height}x{Width} smaller than minimum required size: 224X224",
    "error_code": "FACE_TOO_SMALL"
}
</code></pre></td></tr></tbody></table>

### model\_output

model\_output contains everything needed to check for facial liveness

**"pred\_idx"** refers to the predicted class of the face and has two possible values:

* "real": A Live Face&#x20;
* "spoof": A Spoof Face / Presentation Attack

**"prob\_real"** refers to the probability of the face being "real" (live). A score above `THRESHOLD` means the face is "real". A score less than `THRESHOLD`means the face is "spoof". **"prob\_real"** metric should be used for writing the liveness check logic in your app.

## Default Thresholds

for /antispoofing: Default `THRESHOLD` is 0.55

for /antispoofing\_plus: Default `THRESHOLD` is 0.50

for /v3/antispoofing: Default `THRESHOLD` is 0.50

## Perform Liveness Check&#x20;

```
if model_output[“prob_real”] > THRESHOLD: 
    return “Liveness Confirmed” 
else: 
    return “Liveness Failed”
```

THRESHOLD can be changed based on your requirements. A very high THRESHOLD is more strict, can cause more False Negatives (Real faces getting incorrectly classified as Spoofs). You can start with recommended default thresholds for both /antispoofing and /robust.&#x20;