> 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-api/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   |

***