> 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/faceswap-image-detection.md).

# FaceSwap  Image Detection

### 🔐 NeuroVerify API – Deepfake Image Detection

#### `POST` 

**🔗 Endpoint**

```json
https://deepscan.neuraldefend.com/detect/faceswap
```

Performs a **faceswap check** on an image.\
For **images**, input should be sent as a **form-data.**<br>

***

#### 📤 Request Format

**Image Upload (form-data)**

```json
{
    "file": "filename.jpeg/jpg/png"  // In Body → form-data || Key: file
}
```

## /detect/faceswap

Detect **face manipulation/faceswap** in images.

***

### Endpoint Details

| Property           | Value                                 |
| ------------------ | ------------------------------------- |
| **URL**            | `/detect/faceswap`                    |
| **Method**         | `POST`                                |
| **Content-Type**   | `multipart/form-data`                 |
| **Authentication** | API Key required (`x-api-key` header) |

***

### Supported Image Formats

| Format | MIME Type                 | File Extensions  | Notes                                          |
| ------ | ------------------------- | ---------------- | ---------------------------------------------- |
| JPEG   | `image/jpeg`, `image/jpg` | `.jpg`, `.jpeg`  | Most common format, **recommended**            |
| 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 format with good compression            |
| HEIC   | `image/heic`              | `.heic`, `.heif` | Apple format (automatically converted to JPEG) |

#### HEIC Support

* HEIC images are automatically converted to JPEG format during processing
* No additional configuration required
* Conversion happens transparently before analysis

***

### File Size Limits

| Limit             | Value     | Notes                                       |
| ----------------- | --------- | ------------------------------------------- |
| Maximum File Size | **10 MB** | Files exceeding this limit will be rejected |

***

### Image Dimension Requirements

#### Minimum Dimensions

* Minimum size: **256×256 pixels**
* Images smaller than this will fail quality checks

#### Maximum Dimensions

* Maximum size: **4096×4096 pixels**
* Images larger than this will fail quality checks

***

### Face Detection Requirements

#### Single Face Required

* The endpoint requires **exactly one face** in the image
* Multiple faces will result in rejection with `MULTI_FACE` tag
* No face will result in rejection with `NO_FACE` tag

#### Rotation Support 🔄

* **EXIF Orientation**: Automatically corrected
* **Automatic Rotation**: Handles rotated images (90°, 180°, 270°)

***

### Best Practices

#### ✅ Recommended Practices

* Use **JPEG format** for best compatibility
* Keep file size under **5 MB** for faster processing
* Ensure good lighting and sharp focus
* Face should occupy at least **10%** of image area
* Face should be clearly visible and facing forward

#### ❌ Common Mistakes to Avoid

* ❌ Uploading files larger than 10 MB
* ❌ Images with multiple faces
* ❌ Blurry or low-quality images
* ❌ Faces partially obscured

***

### Request Format

#### Headers

| Header         | Required | Description                     |
| -------------- | -------- | ------------------------------- |
| `x-api-key`    | Yes      | Your API key for authentication |
| `Content-Type` | Yes      | Must be `multipart/form-data`   |

#### Body

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

#### Example Request (cURL)

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

#### Example Request (Python)

```python
import requests

url = "https://api.neuroverify.com/detect/faceswap"
headers = {"x-api-key": "your-api-key"}
files = {"file": open("image.jpg", "rb")}

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

***

### Response Format

#### Success Response Structure

```json
{
  "image_analysis": {
    "unique_trx_id": "trx_a1b2c3d4e5f6789012ab",
    "filename": "photo.jpg",
    "content_type": "image/jpeg",
    "status": "success",
    "status_code": 1,
    "billable": "Y",
    "message": "Analysis completed successfully",
    "inference_time": 0.523,
    "original_filename": "photo.jpg",
    "face_count": 1,
    "face_confidence": 0.95,
    "prediction_tag": "GENUINE",
    "faceswap_check": {
      "prediction": "Genuine",
      "confidence": 0.987,
      "inference_time": 0.421,
      "status": "performed"
    }
  }
}
```

#### Response Field Descriptions

| Field                           | Type        | Description                                    |
| ------------------------------- | ----------- | ---------------------------------------------- |
| `unique_trx_id`                 | string      | Unique transaction identifier                  |
| `filename`                      | string      | Original filename of uploaded image            |
| `content_type`                  | string      | MIME type of the uploaded file                 |
| `status`                        | string      | Overall status: `"success"` or `"failed"`      |
| `status_code`                   | integer     | Numeric status code (1-8) for billing/tracking |
| `billable`                      | string      | Billing flag: `"Y"` or `"N"`                   |
| `message`                       | string      | Human-readable message                         |
| `inference_time`                | float       | Total processing time in seconds               |
| `face_count`                    | integer     | Number of faces detected                       |
| `face_confidence`               | float/null  | Face detection confidence (0.0-1.0)            |
| `prediction_tag`                | string      | Categorical classification                     |
| `faceswap_check.prediction`     | string/null | `"Genuine"` or `"Face manipulation detected"`  |
| `faceswap_check.confidence`     | float/null  | Detection confidence (0.0-1.0)                 |
| `faceswap_check.inference_time` | float/null  | Processing time in seconds                     |
| `faceswap_check.status`         | string      | `"performed"` or `"skipped"`                   |

***

### Prediction Tags Reference

#### Faceswap Detection Tags

| Tag        | Scenario              | Description                     |
| ---------- | --------------------- | ------------------------------- |
| `GENUINE`  | Real face detected    | No face manipulation detected   |
| `FACESWAP` | Manipulation detected | Face swap/manipulation detected |

#### Face Detection Tags

| Tag          | Scenario         | Description                 |
| ------------ | ---------------- | --------------------------- |
| `NO_FACE`    | No face detected | No human face found         |
| `MULTI_FACE` | Multiple faces   | More than one face detected |

#### File Validation Tags

| Tag                | Scenario                   | Description                               |
| ------------------ | -------------------------- | ----------------------------------------- |
| `INVALID_FORMAT`   | Unsupported file type      | File format not supported                 |
| `FILE_TOO_LARGE`   | File size > 10MB           | File exceeds size limit                   |
| `INVALID_SIZE`     | Resolution too low         | Image dimensions below minimum (224x224)  |
| `IMAGE_TOO_LARGE`  | Resolution too large       | Image dimensions exceed maximum           |
| `BRIGHTNESS_ERROR` | Too dark/bright            | Image brightness outside acceptable range |
| `CONTRAST_ERROR`   | Low contrast               | Insufficient contrast in image            |
| `BLUR_ERROR`       | Too blurry                 | Image is out of focus or blurry           |
| `QUALITY_ERROR`    | Generic quality failure    | General image quality check failed        |
| `CONVERSION_ERROR` | HEIC conversion failed     | HEIC file could not be converted          |
| `Security-Error`   | Security validation failed | Security check failed                     |
| `Validation-Error` | Generic validation failed  | Validation check failed                   |

#### Processing Tags

| Tag                | Scenario         | Description             |
| ------------------ | ---------------- | ----------------------- |
| `PROCESSING_ERROR` | Processing error | Error during processing |

***

### Status Code Mapping

| Status Code | Billable | Scenario                        |
| ----------- | -------- | ------------------------------- |
| 1           | Y        | Successful complete analysis    |
| 2           | N        | Bad request (validation errors) |
| 5           | N        | Internal server error           |
| 6           | Y        | No face detected                |
| 7           | Y        | Multiple faces detected         |

***

### Response Scenarios

#### 1. Successful Analysis - Genuine Face

**HTTP Status:** `200 OK`

```json
{
  "image_analysis": {
    "unique_trx_id": "trx_a1b2c3d4e5f6789012ab",
    "filename": "real_photo.jpg",
    "content_type": "image/jpeg",
    "status": "success",
    "status_code": 1,
    "billable": "Y",
    "message": "Analysis completed successfully",
    "inference_time": 0.523,
    "original_filename": "real_photo.jpg",
    "face_count": 1,
    "face_confidence": 0.95,
    "prediction_tag": "GENUINE",
    "faceswap_check": {
      "prediction": "Genuine",
      "confidence": 0.987,
      "inference_time": 0.421,
      "status": "performed"
    }
  }
}
```

#### 2. Successful Analysis - Faceswap Detected

**HTTP Status:** `200 OK`

```json
{
  "image_analysis": {
    "unique_trx_id": "trx_b2c3d4e5f67890123bc",
    "filename": "manipulated.jpg",
    "content_type": "image/jpeg",
    "status": "success",
    "status_code": 1,
    "billable": "Y",
    "message": "Analysis completed successfully",
    "inference_time": 0.612,
    "original_filename": "manipulated.jpg",
    "face_count": 1,
    "face_confidence": 0.95,
    "prediction_tag": "FACESWAP",
    "faceswap_check": {
      "prediction": "Face manipulation detected",
      "confidence": 0.934,
      "inference_time": 0.498,
      "status": "performed"
    }
  }
}
```

#### 3. No Face Detected

**HTTP Status:** `200 OK`

```json
{
  "image_analysis": {
    "unique_trx_id": "trx_c3d4e5f678901234cd",
    "filename": "landscape.jpg",
    "content_type": "image/jpeg",
    "status": "failed",
    "status_code": 6,
    "billable": "Y",
    "message": "No face detected, face is too far from camera, or no reliable face suitable for prediction",
    "inference_time": 0.234,
    "original_filename": "landscape.jpg",
    "face_count": 0,
    "face_confidence": null,
    "prediction_tag": "NO_FACE",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped"
    }
  }
}
```

#### 4. Multiple Faces Detected

**HTTP Status:** `200 OK`

```json
{
  "image_analysis": {
    "unique_trx_id": "trx_d4e5f6789012345de",
    "filename": "group_photo.jpg",
    "content_type": "image/jpeg",
    "status": "failed",
    "status_code": 7,
    "billable": "Y",
    "message": "Multiple faces detected (3 faces). Single face required.",
    "inference_time": 0.312,
    "original_filename": "group_photo.jpg",
    "face_count": 3,
    "face_confidence": null,
    "prediction_tag": "MULTI_FACE",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped"
    }
  }
}
```

#### 5. Unsupported File Type

**HTTP Status:** `400 Bad Request`

```json
{
  "image_analysis": {
    "unique_trx_id": "trx_e5f67890123456ef",
    "filename": "document.pdf",
    "content_type": "application/pdf",
    "status": "failed",
    "status_code": 2,
    "billable": "N",
    "message": "Unsupported file type. Supported types: image/jpeg, image/png, image/bmp, image/tiff, image/webp, image/heic",
    "inference_time": 0.012,
    "original_filename": "document.pdf",
    "face_count": 0,
    "face_confidence": null,
    "prediction_tag": "INVALID_FORMAT",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped"
    }
  }
}
```

#### 6. File Too Large

**HTTP Status:** `400 Bad Request`

```json
{
  "image_analysis": {
    "unique_trx_id": "trx_f67890123456789fg",
    "filename": "huge_image.jpg",
    "content_type": "image/jpeg",
    "status": "failed",
    "status_code": 2,
    "billable": "N",
    "message": "File size too large. Maximum 10MB allowed.",
    "inference_time": 0.008,
    "original_filename": "huge_image.jpg",
    "face_count": 0,
    "face_confidence": null,
    "prediction_tag": "FILE_TOO_LARGE",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped"
    }
  }
}
```

#### 7. Invalid Size (Resolution Too Low)

**HTTP Status:** `400 Bad Request`

```json
{
  "image_analysis": {
    "unique_trx_id": "trx_xxx",
    "filename": "small_image.jpeg",
    "content_type": "image/jpeg",
    "status": "failed",
    "status_code": 2,
    "billable": "N",
    "message": "Image resolution too low (178x218, min=224x224)",
    "inference_time": 0.011,
    "original_filename": "small_image.jpeg",
    "face_count": 0,
    "face_confidence": null,
    "prediction_tag": "INVALID_SIZE",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped"
    }
  }
}
```

#### 8. Brightness Error

**HTTP Status:** `400 Bad Request`

```json
{
  "image_analysis": {
    "unique_trx_id": "trx_xxx",
    "filename": "overexposed.jpg",
    "content_type": "image/jpeg",
    "status": "failed",
    "status_code": 2,
    "billable": "N",
    "message": "Image too bright (brightness=250, max=220)",
    "inference_time": 0.013,
    "original_filename": "overexposed.jpg",
    "face_count": 0,
    "face_confidence": null,
    "prediction_tag": "BRIGHTNESS_ERROR",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped"
    }
  }
}
```

#### 9. Contrast Error

**HTTP Status:** `400 Bad Request`

```json
{
  "image_analysis": {
    "unique_trx_id": "trx_xxx",
    "filename": "low_contrast.jpg",
    "content_type": "image/jpeg",
    "status": "failed",
    "status_code": 2,
    "billable": "N",
    "message": "Image has low contrast (contrast=15, min=20)",
    "inference_time": 0.014,
    "original_filename": "low_contrast.jpg",
    "face_count": 0,
    "face_confidence": null,
    "prediction_tag": "CONTRAST_ERROR",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped"
    }
  }
}
```

#### 10. Quality Error

**HTTP Status:** `400 Bad Request`

```json
{
  "image_analysis": {
    "unique_trx_id": "trx_xxx",
    "filename": "poor_quality.jpg",
    "content_type": "image/jpeg",
    "status": "failed",
    "status_code": 2,
    "billable": "N",
    "message": "Quality check failed",
    "inference_time": 0.011,
    "original_filename": "poor_quality.jpg",
    "face_count": 0,
    "face_confidence": null,
    "prediction_tag": "QUALITY_ERROR",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped"
    }
  }
}
```

#### 11. Security Error

**HTTP Status:** `400 Bad Request`

```json
{
  "image_analysis": {
    "unique_trx_id": "trx_xxx",
    "filename": "malicious.jpg",
    "content_type": "image/jpeg",
    "status": "failed",
    "status_code": 2,
    "billable": "N",
    "message": "Security validation failed",
    "inference_time": 0.010,
    "original_filename": "malicious.jpg",
    "face_count": 0,
    "face_confidence": null,
    "prediction_tag": "Security-Error",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped"
    }
  }
}
```

#### 12. Validation Error

**HTTP Status:** `400 Bad Request`

```json
{
  "image_analysis": {
    "unique_trx_id": "trx_xxx",
    "filename": "invalid.jpg",
    "content_type": "image/jpeg",
    "status": "failed",
    "status_code": 2,
    "billable": "N",
    "message": "Validation failed",
    "inference_time": 0.011,
    "original_filename": "invalid.jpg",
    "face_count": 0,
    "face_confidence": null,
    "prediction_tag": "Validation-Error",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped"
    }
  }
}
```

#### 13. Internal Server Error

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

```json
{
  "image_analysis": {
    "unique_trx_id": "trx_g7890123456789agh",
    "filename": "photo.jpg",
    "content_type": "image/jpeg",
    "status": "failed",
    "status_code": 5,
    "billable": "N",
    "message": "Internal server error during faceswap detection",
    "inference_time": 0.234,
    "original_filename": "photo.jpg",
    "face_count": 0,
    "face_confidence": null,
    "prediction_tag": "PROCESSING_ERROR",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped"
    }
  }
}
```

***

### Error Handling

#### HTTP Status Codes

| Code | Meaning             | Action                   |
| ---- | ------------------- | ------------------------ |
| 200  | Success             | Process the response     |
| 400  | Bad Request         | Check file format/size   |
| 401  | Unauthorized        | Check API key            |
| 500  | Server Error        | Retry or contact support |
| 503  | Service Unavailable | Service not available    |

**NeuroVerify** supports **high-volume** and **high-concurrency** environments, ensuring consistent performance for enterprise-scale demands. The architecture is cloud-optimized to handle thousands of requests per second, dynamically scaling based on customer requirements.


---

# 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/faceswap-image-detection.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.