> For the complete documentation index, see [llms.txt](https://neuraldefend.gitbook.io/neural-defend/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://neuraldefend.gitbook.io/neural-defend/unified-face-authenticity.md).

# Unified Face Authenticity

## Unified Face Authenticity Score

#### NeuroVerify API — AI-Powered Face Authenticity Detection

**`POST`**

**Endpoint**

```
https://deepscan.neuraldefend.com/detect/unified
```

***

### Overview

The **Unified Face Authenticity Score** is NeuroVerify's flagship face verification endpoint. It runs a multi-layered AI detection pipeline — combining **Visual Safety Screening**, **Liveness Verification**, **Face Swap Detection**, **AI Generative Model Analysis**, and **AI Content Compliance** — and returns a single, opaque **risk score** indicating how likely the submitted image is AI-generated or manipulated.

**Key benefits:**

* Single API call replaces multiple detection endpoints
* Opaque scoring protects proprietary model IP
* Deterministic, consistent risk bands for easy integration
* Enterprise-grade security validation on every upload

***

### Endpoint Details

| Property           | Value                                 |
| ------------------ | ------------------------------------- |
| **URL**            | `/detect/unified`                     |
| **Method**         | `POST`                                |
| **Content-Type**   | `multipart/form-data`                 |
| **Authentication** | API Key required (`x-api-key` header) |
| **Rate Limiting**  | Per-key, contact sales for limits     |
| **SLA**            | 99.9% uptime (production tier)        |

***

### Supported Image Formats

| Format | MIME Type                 | File Extensions  | Notes                                |
| ------ | ------------------------- | ---------------- | ------------------------------------ |
| JPEG   | `image/jpeg`, `image/jpg` | `.jpg`, `.jpeg`  | **Recommended** — best compatibility |
| PNG    | `image/png`               | `.png`           | Supports transparency                |
| BMP    | `image/bmp`               | `.bmp`           | Windows bitmap format                |
| TIFF   | `image/tiff`              | `.tiff`, `.tif`  | High-quality format                  |
| WebP   | `image/webp`              | `.webp`          | Modern compressed format             |
| HEIC   | `image/heic`              | `.heic`, `.heif` | Auto-converted to JPEG internally    |

***

### File & Image Requirements

| Constraint             | Value          | Notes                                     |
| ---------------------- | -------------- | ----------------------------------------- |
| **Maximum file size**  | 10 MB          | Files exceeding this are rejected         |
| **Minimum resolution** | 224 × 224 px   | Below this, analysis cannot run reliably  |
| **Face count**         | Exactly 1      | Multi-face or no-face images are rejected |
| **Orientation**        | Auto-corrected | EXIF rotation (90°, 180°, 270°) handled   |

***

### Request Format

#### Headers

| Header         | Required | Description                           |
| -------------- | -------- | ------------------------------------- |
| `x-api-key`    | Yes      | Your API key (provided at onboarding) |
| `Content-Type` | Yes      | `multipart/form-data`                 |

#### Body

| Field  | Type | Required | Description           |
| ------ | ---- | -------- | --------------------- |
| `file` | File | Yes      | Image file to analyze |

#### Example Request — cURL

```bash
curl -X POST "https://deepscan.neuraldefend.com/detect/unified" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/image.jpg"
```

#### Example Request — Python

```python
import requests

url = "https://deepscan.neuraldefend.com/detect/unified"
headers = {"x-api-key": "YOUR_API_KEY"}
files = {"file": open("image.jpg", "rb")}

response = requests.post(url, headers=headers, files=files)
data = response.json()

# Access the result
result = data["unified_face_authenticity_score"]
print(f"Risk Score: {result['risk_score']}")
print(f"Risk Level: {result['risk_level']}")
print(f"Message: {result['message']}")
```

#### Example Request — JavaScript (Node.js)

```javascript
const FormData = require("form-data");
const fs = require("fs");
const axios = require("axios");

const form = new FormData();
form.append("file", fs.createReadStream("image.jpg"));

const response = await axios.post(
  "https://deepscan.neuraldefend.com/detect/unified",
  form,
  {
    headers: {
      "x-api-key": "YOUR_API_KEY",
      ...form.getHeaders(),
    },
  }
);

const result = response.data.unified_face_authenticity_score;
console.log(`Risk Score: ${result.risk_score}`);
```

***

### Response Format

All responses are wrapped in the **`unified_face_authenticity_score`** envelope:

```json
{
  "unified_face_authenticity_score": {
    "unique_trx_id": "...",
    "filename": "...",
    "content_type": "...",
    "status": "success | rejected | error",
    "status_code": 1,
    "billable": "Y | N",
    "risk_score": 3.2,
    "risk_level": "low | medium | high",
    "message": "...",
    "ai_threat_signals": [...]
  }
}
```

#### Response Field Reference

| Field               | Type            | Description                                                                        |
| ------------------- | --------------- | ---------------------------------------------------------------------------------- |
| `unique_trx_id`     | string          | Unique transaction identifier for audit trail                                      |
| `filename`          | string          | Name of the uploaded file                                                          |
| `content_type`      | string          | Detected MIME type                                                                 |
| `status`            | string          | `"success"`, `"rejected"`, or `"error"`                                            |
| `status_code`       | integer         | Numeric status (see Status Codes)                                                  |
| `billable`          | string          | `"Y"` if the request counts toward billing; `"N"` otherwise                        |
| `risk_score`        | float \| null   | **0.1 – 10.0** (higher = higher AI/manipulation risk); `null` if rejected or error |
| `risk_level`        | string \| null  | `"low"`, `"medium"`, or `"high"`; `null` if not scored                             |
| `message`           | string          | Human-readable explanation of the result                                           |
| `ai_threat_signals` | array \| absent | List of checks performed (present only on scored responses)                        |

#### Risk Score Bands

| Risk Score | Risk Level | Message                          | Interpretation                       |
| ---------- | ---------- | -------------------------------- | ------------------------------------ |
| 0.1 – 3.9  | `low`      | "Not likely to be AI-generated"  | Image appears authentic              |
| 4.0 – 6.9  | `medium`   | "Less likely to be AI-generated" | Inconclusive — review recommended    |
| 7.0 – 10.0 | `high`     | "Likely to be AI-generated"      | Strong indicators of AI manipulation |

### Status Codes

| `status_code` | `status`   | HTTP    | Billable | Meaning                                             |
| ------------- | ---------- | ------- | -------- | --------------------------------------------------- |
| 1             | `success`  | 200     | Yes      | Analysis completed — `risk_score` present           |
| 2             | `rejected` | 400     | No       | Input validation failed (quality, format, security) |
| 5             | `error`    | 500/503 | No       | Server-side failure — retry with backoff            |
| 6             | `rejected` | 200     | Yes      | No face detected in image                           |
| 7             | `rejected` | 200     | Yes      | Multiple faces detected — single face required      |

***

### Response Scenarios

#### Group 1 — Successful Analysis (scored)

`status: "success"` · `status_code: 1` · `risk_score` present · `ai_threat_signals` present

***

**GENUINE — Low risk (all checks passed)**

**HTTP Status:** `200 OK`

```json
{
  "unified_face_authenticity_score": {
    "unique_trx_id": "trx_c1r7n6oy69zhunjrkp0p",
    "filename": "selfie.jpg",
    "content_type": "image/jpeg",
    "status": "success",
    "status_code": 1,
    "billable": "Y",
    "risk_score": 2.2,
    "risk_level": "low",
    "message": "Not likely to be AI-generated",
    "ai_threat_signals": [
      "Visual Safety Screening",
      "Liveness Verification",
      "Face Swap Detection",
      "AI Generative Model Analysis",
      "AI Content Compliance"
    ]
  }
}
```

***

**Medium risk band (inconclusive)**

**HTTP Status:** `200 OK`

```json
{
  "unified_face_authenticity_score": {
    "unique_trx_id": "trx_med123abc456def789",
    "filename": "portrait.jpg",
    "content_type": "image/jpeg",
    "status": "success",
    "status_code": 1,
    "billable": "Y",
    "risk_score": 5.5,
    "risk_level": "medium",
    "message": "Less likely to be AI-generated",
    "ai_threat_signals": [
      "Visual Safety Screening",
      "Liveness Verification",
      "Face Swap Detection",
      "AI Generative Model Analysis",
      "AI Content Compliance"
    ]
  }
}
```

***

**SPOOF detected — High risk (presentation attack)**

**HTTP Status:** `200 OK`

```json
{
  "unified_face_authenticity_score": {
    "unique_trx_id": "trx_k8mdf2ab1xpqr7w3e9t6",
    "filename": "printed_photo.jpg",
    "content_type": "image/jpeg",
    "status": "success",
    "status_code": 1,
    "billable": "Y",
    "risk_score": 8.7,
    "risk_level": "high",
    "message": "Likely to be AI-generated",
    "ai_threat_signals": [
      "Visual Safety Screening",
      "Liveness Verification",
      "Face Swap Detection",
      "AI Generative Model Analysis",
      "AI Content Compliance"
    ]
  }
}
```

***

**FACESWAP detected — High risk (face manipulation)**

**HTTP Status:** `200 OK`

```json
{
  "unified_face_authenticity_score": {
    "unique_trx_id": "trx_m3nqw8yz5abcdef12gh4",
    "filename": "swapped.jpg",
    "content_type": "image/jpeg",
    "status": "success",
    "status_code": 1,
    "billable": "Y",
    "risk_score": 8.4,
    "risk_level": "high",
    "message": "Likely to be AI-generated",
    "ai_threat_signals": [
      "Visual Safety Screening",
      "Liveness Verification",
      "Face Swap Detection",
      "AI Generative Model Analysis",
      "AI Content Compliance"
    ]
  }
}
```

***

**AI\_GENERATED detected — High risk (synthetic face)**

**HTTP Status:** `200 OK`

```json
{
  "unified_face_authenticity_score": {
    "unique_trx_id": "trx_p9rst4uv6wxyz78klm01",
    "filename": "ai_generated.png",
    "content_type": "image/png",
    "status": "success",
    "status_code": 1,
    "billable": "Y",
    "risk_score": 8.4,
    "risk_level": "high",
    "message": "Likely to be AI-generated",
    "ai_threat_signals": [
      "Visual Safety Screening",
      "Liveness Verification",
      "Face Swap Detection",
      "AI Generative Model Analysis",
      "AI Content Compliance"
    ]
  }
}
```

***

#### Group 2 — Rejected (not scored)

`status: "rejected"` · `risk_score: null` · `risk_level: null` · no `ai_threat_signals`

The image did not pass pre-analysis validation. No AI detection models were run.

***

**No face detected**

**HTTP Status:** `200 OK` · **Billable:** Yes

```json
{
  "unified_face_authenticity_score": {
    "unique_trx_id": "trx_nf123abc456def789",
    "filename": "landscape.jpg",
    "content_type": "image/jpeg",
    "status": "rejected",
    "status_code": 6,
    "billable": "Y",
    "risk_score": null,
    "risk_level": null,
    "message": "No face detected in the image"
  }
}
```

***

**Multiple faces detected**

**HTTP Status:** `200 OK` · **Billable:** Yes

```json
{
  "unified_face_authenticity_score": {
    "unique_trx_id": "trx_mf456def789abc012",
    "filename": "group_photo.jpg",
    "content_type": "image/jpeg",
    "status": "rejected",
    "status_code": 7,
    "billable": "Y",
    "risk_score": null,
    "risk_level": null,
    "message": "Multiple faces detected in the image"
  }
}
```

***

**Image quality error (blur, brightness, contrast, dimensions)**

**HTTP Status:** `400 Bad Request` · **Billable:** Yes

```json
{
  "unified_face_authenticity_score": {
    "unique_trx_id": "trx_qe789abc012def345",
    "filename": "blurry.jpg",
    "content_type": "image/jpeg",
    "status": "rejected",
    "status_code": 2,
    "billable": "Y",
    "risk_score": null,
    "risk_level": null,
    "message": "Image is too blurry for analysis"
  }
}
```

Other quality messages you may receive:

| Message                                         | Cause                    |
| ----------------------------------------------- | ------------------------ |
| "Image brightness is outside acceptable range"  | Too dark or overexposed  |
| "Image contrast is outside acceptable range"    | Insufficient contrast    |
| "Image dimensions are outside acceptable range" | Below minimum resolution |
| "Image quality is insufficient for analysis"    | Generic quality failure  |

***

**NSFW content detected**

**HTTP Status:** `400 Bad Request` · **Billable:** Yes

```json
{
  "unified_face_authenticity_score": {
    "unique_trx_id": "trx_nsfw012abc345def67",
    "filename": "flagged.jpg",
    "content_type": "image/jpeg",
    "status": "rejected",
    "status_code": 2,
    "billable": "Y",
    "risk_score": null,
    "risk_level": null,
    "message": "Image contains inappropriate content"
  }
}
```

***

**Security rejection**

**HTTP Status:** `400 Bad Request` · **Billable:** Yes

```json
{
  "unified_face_authenticity_score": {
    "unique_trx_id": "trx_sec345def678abc901",
    "filename": "suspicious.jpg.php",
    "content_type": "application/octet-stream",
    "status": "rejected",
    "status_code": 2,
    "billable": "Y",
    "risk_score": null,
    "risk_level": null,
    "message": "File failed security validation"
  }
}
```

***

**Unsupported file format**

**HTTP Status:** `400 Bad Request` · **Billable:** No

```json
{
  "unified_face_authenticity_score": {
    "unique_trx_id": "trx_fmt678abc901def234",
    "filename": "document.pdf",
    "content_type": "application/pdf",
    "status": "rejected",
    "status_code": 2,
    "billable": "N",
    "risk_score": null,
    "risk_level": null,
    "message": "Unsupported file format"
  }
}
```

***

**File too large**

**HTTP Status:** `400 Bad Request` · **Billable:** No

```json
{
  "unified_face_authenticity_score": {
    "unique_trx_id": "trx_big901def234abc567",
    "filename": "huge_image.jpg",
    "content_type": "image/jpeg",
    "status": "rejected",
    "status_code": 2,
    "billable": "N",
    "risk_score": null,
    "risk_level": null,
    "message": "File exceeds maximum size limit"
  }
}
```

***

#### Group 3 — Server Errors

`status: "error"` · `status_code: 5` · not billable

A server-side issue prevented analysis. Retry with exponential backoff.

***

**Service unavailable (503)**

**HTTP Status:** `503 Service Unavailable`

```json
{
  "unified_face_authenticity_score": {
    "unique_trx_id": "trx_503abc123def456789",
    "filename": "photo.jpg",
    "content_type": "image/jpeg",
    "status": "error",
    "status_code": 5,
    "billable": "N",
    "risk_score": null,
    "risk_level": null,
    "message": "Internal server error during unified detection"
  }
}
```

***

**Internal server error (500)**

**HTTP Status:** `500 Internal Server Error`

```json
{
  "unified_face_authenticity_score": {
    "unique_trx_id": "trx_500def789abc012345",
    "filename": "photo.jpg",
    "content_type": "image/jpeg",
    "status": "error",
    "status_code": 5,
    "billable": "N",
    "risk_score": null,
    "risk_level": null,
    "message": "Internal server error during unified detection"
  }
}
```

***

### Integration Guide

#### Recommended Client Logic

```
1. POST image to /detect/unified
2. Check HTTP status code:
   - 401 → Invalid API key
   - 200/400/500/503 → Parse JSON response
3. Read response.unified_face_authenticity_score.status:
   - "success" → Read risk_score, risk_level, message
   - "rejected" → Show message to user, prompt re-upload
   - "error" → Retry with exponential backoff
4. Apply business rules based on risk_level:
   - "low" → Accept
   - "medium" → Flag for manual review
   - "high" → Reject / escalate
```

#### Retry Strategy

| Scenario              | Recommended action                                        |
| --------------------- | --------------------------------------------------------- |
| HTTP 500 / 503        | Retry up to 3 times with exponential backoff (1s, 2s, 4s) |
| HTTP 429 (rate limit) | Wait for `Retry-After` header value, then retry           |
| HTTP 400              | Do NOT retry — fix the input                              |
| HTTP 401              | Do NOT retry — check API key                              |

#### Idempotency

Each request generates a unique `unique_trx_id`. Requests are **not** idempotent — re-submitting the same image produces a new transaction. Store the `unique_trx_id` if you need audit trail correlation.

***

### Best Practices

#### Recommended

* Use **JPEG format** for best compatibility and fastest processing
* Ensure the subject's face is **clearly visible, frontal, and well-lit**
* Keep file size **under 5 MB** for optimal latency (10 MB max)
* Store `unique_trx_id` for dispute resolution and audit trails
* Implement proper error handling for all three response statuses
* Use `risk_level` (or  `risk_score`) for business decisions — band thresholds may be tuned

#### Avoid

* Submitting images with **multiple faces** — crop to a single subject first
* Sending **extremely low resolution** images (below 224×224)
* Images with **poor lighting** (overexposed, underexposed, or washed out)
* **Blurry or out-of-focus** captures
* **Non-image files** disguised with image extensions (security rejection)
* Retrying on HTTP 400 without fixing the input

***

### Error Handling Summary

| HTTP Code | Meaning                                     | Client Action                         |
| --------- | ------------------------------------------- | ------------------------------------- |
| 200       | Analysis completed or face policy rejection | Parse `status` field for outcome      |
| 400       | Input validation failed                     | Fix input per `message`, do not retry |
| 401       | Unauthorized                                | Verify API key is valid and active    |
| 403       | Forbidden                                   | Endpoint not included in your plan    |
| 429       | Rate limit exceeded                         | Wait per `Retry-After`, then retry    |
| 500       | Internal server error                       | Retry with backoff (max 3 attempts)   |
| 503       | Service unavailable                         | Retry with backoff (max 3 attempts)   |

***

### SDKs & Libraries

| Language              | Package                                 | Status      |
| --------------------- | --------------------------------------- | ----------- |
| Python                | `pip install neuraldefend`              | Coming soon |
| JavaScript/TypeScript | `npm install @neuraldefend/sdk`         | Coming soon |
| Go                    | `go get github.com/neuraldefend/go-sdk` | Planned     |

For early access to SDKs, contact your account manager.

***

### Support

| Channel           | Details                    |
| ----------------- | -------------------------- |
| Technical support | <support@neuraldefend.com> |

***

*Last updated: June 2026*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://neuraldefend.gitbook.io/neural-defend/unified-face-authenticity.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.