> 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/advanced-image-ai-gen-and-faceswap-detection.md).

# Advanced  Image AI Gen & Faceswap Detection

### 🔐 NeuroVerify API – Combined AI Image Detection

#### `POST` 

**🔗 Endpoint**

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

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

## /detect/advanced-ai-manipulation

**Advanced AI Manipulation detection** combining **Faceswap deepfake  + Gen AI Image** analysis in sequence (without Liveness check).

***

### Endpoint Details

| Property           | Value                                 |
| ------------------ | ------------------------------------- |
| **URL**            | `/detect/image`                       |
| **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`  | **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          |
| HEIC   | `image/heic`              | `.heic`, `.heif` | Auto-converted to JPEG |

***

### File Size Limits

| Limit             | Value     | Notes                         |
| ----------------- | --------- | ----------------------------- |
| Maximum File Size | **10 MB** | Same limit as other endpoints |

***

### Face Detection Requirements

#### Single Face Required

* **Exactly one face** required in the image
* Multiple faces → `MULTI_FACE` response
* No face → `NO_FACE` response<br>

#### Rotation Support 🔄

* EXIF orientation automatically corrected
* Handles rotated images (90°, 180°, 270°)

***

### Request Format

#### Headers

| Header         | Required | Description           |
| -------------- | -------- | --------------------- |
| `x-api-key`    | Yes      | Your API key          |
| `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/advanced-ai-manipulation" \
  -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/advanced-ai-manipulation"
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
{
  "manipulation_analysis": {
    "unique_trx_id": "trx_a1b2c3d4e5f6789012ab",
    "filename": "photo.jpg",
    "content_type": "image/jpeg",
    "status": "success",
    "status_code": 1,
    "billable": "Y",
    "message": "All manipulation checks passed successfully",
    "inference_time": 0.934,
    "original_filename": "photo.jpg",
    "face_count": 1,
    "face_confidence": 0.95,
    "prediction_tag": "GENUINE",
    "final_prediction": "Genuine - All manipulation checks passed",
    "faceswap_check": {
      "prediction": "Genuine",
      "confidence": 0.945,
      "inference_time": 0.412,
      "status": "performed"
    },
    "deepfake_check": {
      "prediction": "Genuine",
      "confidence": 0.923,
      "inference_time": 0.501,
      "status": "performed"
    }
  }
}
```

#### Response Field Descriptions

| Field              | Type       | Description                     |
| ------------------ | ---------- | ------------------------------- |
| `unique_trx_id`    | string     | Unique transaction identifier   |
| `filename`         | string     | Uploaded filename               |
| `content_type`     | string     | MIME type                       |
| `status`           | string     | `"success"` or `"failed"`       |
| `status_code`      | integer    | Status code (1-8)               |
| `billable`         | string     | `"Y"` or `"N"`                  |
| `message`          | string     | Human-readable result message   |
| `inference_time`   | float      | Total processing time (seconds) |
| `face_count`       | integer    | Number of faces detected        |
| `face_confidence`  | float/null | Face detection confidence       |
| `prediction_tag`   | string     | Final classification            |
| `final_prediction` | string     | Human-readable verdict          |
| `faceswap_check`   | object     | Faceswap detection result       |
| `deepfake_check`   | object     | Deepfake detection result       |

#### Check Object Structure

Each check (`faceswap_check`, `deepfake_check`) contains:

| Field            | Type        | Description                                          |
| ---------------- | ----------- | ---------------------------------------------------- |
| `prediction`     | string/null | Detection result                                     |
| `confidence`     | float/null  | Confidence score (0.0-1.0)                           |
| `inference_time` | float/null  | Processing time (seconds)                            |
| `status`         | string      | `"performed"`, `"skipped"`, or `"failed"`            |
| `skip_reason`    | string      | Reason if skipped (present when status is "skipped") |

***

### Prediction Tags Reference

#### Final Verdict Tags

| Tag            | Scenario          | Description                       |
| -------------- | ----------------- | --------------------------------- |
| `GENUINE`      | All checks passed | Image is genuine, no manipulation |
| `FACESWAP`     | Faceswap detected | Face manipulation detected        |
| `AI_GENERATED` | Deepfake detected | AI-generated content detected     |

#### Face Detection Tags

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

#### Error Tags

| Tag                | Scenario                   | Description                               |
| ------------------ | -------------------------- | ----------------------------------------- |
| `INVALID_FORMAT`   | Bad file type              | Unsupported file format                   |
| `FILE_TOO_LARGE`   | Size > 10MB                | File exceeds limit                        |
| `INVALID_SIZE`     | Resolution too low         | Image dimensions below minimum (256x256)  |
| `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-Error` | Server error               | Processing failed                         |

***

### Status Code Mapping

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

***

### Response Scenarios

#### 1. All Checks Passed - GENUINE

**HTTP Status:** `200 OK`

```json
{
  "manipulation_analysis": {
    "unique_trx_id": "trx_a1b2c3d4e5f6789012ab",
    "filename": "selfie.jpg",
    "content_type": "image/jpeg",
    "status": "success",
    "status_code": 1,
    "billable": "Y",
    "message": "All manipulation checks passed successfully",
    "inference_time": 0.934,
    "original_filename": "selfie.jpg",
    "face_count": 1,
    "face_confidence": 0.95,
    "prediction_tag": "GENUINE",
    "final_prediction": "Genuine - All manipulation checks passed",
    "faceswap_check": {
      "prediction": "Genuine",
      "confidence": 0.945,
      "inference_time": 0.412,
      "status": "performed"
    },
    "deepfake_check": {
      "prediction": "Genuine",
      "confidence": 0.923,
      "inference_time": 0.501,
      "status": "performed"
    }
  }
}
```

#### 2. Faceswap Detected (Pipeline Stops at Step 1)

**HTTP Status:** `200 OK`

```json
{
  "manipulation_analysis": {
    "unique_trx_id": "trx_b2c3d4e5f67890123bc",
    "filename": "faceswap.jpg",
    "content_type": "image/jpeg",
    "status": "success",
    "status_code": 1,
    "billable": "Y",
    "message": "Face manipulation detected",
    "inference_time": 0.523,
    "original_filename": "faceswap.jpg",
    "face_count": 1,
    "face_confidence": 0.95,
    "prediction_tag": "FACESWAP",
    "final_prediction": "Face manipulation detected",
    "faceswap_check": {
      "prediction": "Face manipulation detected",
      "confidence": 0.912,
      "inference_time": 0.412,
      "status": "performed"
    },
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Faceswap detected"
    }
  }
}
```

#### 3. AI-Generated Detected (Pipeline Completes All Steps)

**HTTP Status:** `200 OK`

```json
{
  "manipulation_analysis": {
    "unique_trx_id": "trx_c3d4e5f678901234cd",
    "filename": "ai_generated.jpg",
    "content_type": "image/jpeg",
    "status": "success",
    "status_code": 1,
    "billable": "Y",
    "message": "AI-Generated content detected",
    "inference_time": 0.934,
    "original_filename": "ai_generated.jpg",
    "face_count": 1,
    "face_confidence": 0.95,
    "prediction_tag": "AI_GENERATED",
    "final_prediction": "AI-Generated content detected",
    "faceswap_check": {
      "prediction": "Genuine",
      "confidence": 0.812,
      "inference_time": 0.412,
      "status": "performed"
    },
    "deepfake_check": {
      "prediction": "AI-Generated content detected",
      "confidence": 0.945,
      "inference_time": 0.501,
      "status": "performed"
    }
  }
}
```

#### 4. No Face Detected

**HTTP Status:** `200 OK`

```json
{
  "manipulation_analysis": {
    "unique_trx_id": "trx_d4e5f6789012345de",
    "filename": "landscape.jpg",
    "content_type": "image/jpeg",
    "status": "success",
    "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",
    "final_prediction": "No face detected, face is too far from camera, or no reliable face suitable for prediction",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "No face detected"
    },
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "No face detected"
    }
  }
}
```

#### 5. Multiple Faces Detected

**HTTP Status:** `200 OK`

```json
{
  "manipulation_analysis": {
    "unique_trx_id": "trx_e5f67890123456ef",
    "filename": "group_photo.jpg",
    "content_type": "image/jpeg",
    "status": "success",
    "status_code": 7,
    "billable": "Y",
    "message": "Multiple faces detected (4 faces). Use multiface endpoint for group images.",
    "inference_time": 0.312,
    "original_filename": "group_photo.jpg",
    "face_count": 4,
    "face_confidence": null,
    "prediction_tag": "MULTI_FACE",
    "final_prediction": "Multiple faces detected (4 faces)",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Multiple faces detected (4 faces)"
    },
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Multiple faces detected (4 faces)"
    }
  }
}
```

#### 6. Invalid Format

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

```json
{
  "manipulation_analysis": {
    "unique_trx_id": "trx_xxx",
    "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/webp",
    "inference_time": 0.011,
    "original_filename": "document.pdf",
    "face_count": 0,
    "face_confidence": null,
    "prediction_tag": "INVALID_FORMAT",
    "final_prediction": "Validation failed",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Unsupported file type. Supported types: image/jpeg, image/png, image/webp"
    },
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Unsupported file type. Supported types: image/jpeg, image/png, image/webp"
    }
  }
}
```

#### 7. File Too Large

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

```json
{
  "manipulation_analysis": {
    "unique_trx_id": "trx_xxx",
    "filename": "large_image.jpg",
    "content_type": "image/jpeg",
    "status": "failed",
    "status_code": 2,
    "billable": "N",
    "message": "File size too large. Maximum 10MB allowed.",
    "inference_time": 0.012,
    "original_filename": "large_image.jpg",
    "face_count": 0,
    "face_confidence": null,
    "prediction_tag": "FILE_TOO_LARGE",
    "final_prediction": "Validation failed",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "File size too large. Maximum 10MB allowed."
    },
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "File size too large. Maximum 10MB allowed."
    }
  }
}
```

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

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

```json
{
  "manipulation_analysis": {
    "unique_trx_id": "trx_72vksvwx26sk0aekt7dy",
    "filename": "Invalid_size.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": "Invalid_size.jpeg",
    "face_count": 0,
    "face_confidence": null,
    "prediction_tag": "INVALID_SIZE",
    "final_prediction": "Validation failed",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Image resolution too low (178x218, min=224x224)"
    },
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Image resolution too low (178x218, min=224x224)"
    }
  }
}
```

#### 9. Brightness Error

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

```json
{
  "manipulation_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",
    "final_prediction": "Validation failed",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Image too bright (brightness=250, max=220)"
    },
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Image too bright (brightness=250, max=220)"
    }
  }
}
```

#### 10. Contrast Error

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

```json
{
  "manipulation_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",
    "final_prediction": "Validation failed",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Image has low contrast (contrast=15, min=20)"
    },
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Image has low contrast (contrast=15, min=20)"
    }
  }
}
```

#### 11. Blur Error

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

```json
{
  "manipulation_analysis": {
    "unique_trx_id": "trx_xxx",
    "filename": "blurry.jpg",
    "content_type": "image/jpeg",
    "status": "failed",
    "status_code": 2,
    "billable": "N",
    "message": "Image too blurry (variance=50, min=100)",
    "inference_time": 0.012,
    "original_filename": "blurry.jpg",
    "face_count": 0,
    "face_confidence": null,
    "prediction_tag": "BLUR_ERROR",
    "final_prediction": "Validation failed",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Image too blurry (variance=50, min=100)"
    },
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Image too blurry (variance=50, min=100)"
    }
  }
}
```

#### 12. Quality Error

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

```json
{
  "manipulation_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",
    "final_prediction": "Validation failed",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Quality check failed"
    },
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Quality check failed"
    }
  }
}
```

#### 13. Security Error

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

```json
{
  "manipulation_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",
    "final_prediction": "Validation failed",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Security validation failed"
    },
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Security validation failed"
    }
  }
}
```

#### 14. Validation Error

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

```json
{
  "manipulation_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",
    "final_prediction": "Validation failed",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Validation failed"
    },
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Validation failed"
    }
  }
}
```

#### 15. Internal Server Error

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

```json
{
  "manipulation_analysis": {
    "unique_trx_id": "trx_f67890123456789fg",
    "filename": "photo.jpg",
    "content_type": "image/jpeg",
    "status": "failed",
    "status_code": 5,
    "billable": "N",
    "message": "Internal server error during manipulation detection",
    "inference_time": 0.234,
    "original_filename": "photo.jpg",
    "face_count": 0,
    "face_confidence": null,
    "prediction_tag": "Processing-Error",
    "final_prediction": "Validation failed",
    "faceswap_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Internal server error during manipulation detection"
    },
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped",
      "skip_reason": "Internal server error during manipulation detection"
    }
  }
}
```

***

### Best Practices

#### ✅ Recommended

* Use **JPEG format** for best compatibility
* Face should be **clearly visible and frontal**
* Keep file size under **10 MB** for faster processing
* Use this endpoint when you don't need liveness verification

#### ❌ Avoid

* ❌ Files larger than 10 MB
* ❌ Images with multiple faces
* ❌ Blurry or low-quality images
* ❌ Extreme face angles

***

### Error Handling

| HTTP 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 | Models not initialized   |

***


---

# 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/advanced-image-ai-gen-and-faceswap-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.