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

### 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; 128X128 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: 128x128",
    "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

## 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;


---

# 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://spoofsense.gitbook.io/spoofsense-triton-documentation/api-usage.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.