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

# AI Generated Image Detection

Neural Defend endpoints are optimised for speed and performance.

### 🔐 NeuroVerify API – AI generated Deepfake Image Detection

#### `POST` 

**🔗 Endpoint**

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

Performs a **Deepfake/ AI generated Image check** on an image or video.\
For **images**, input should be sent as a **form-data.**<br>

## /detect/image

Detect deepfake (AI-generated) images.

***

### Endpoint Details

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

***

### Supported Image Formats

The `/detect/image` endpoint accepts the following 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 |

#### File Size Validation

* Files exceeding the limit will be rejected with HTTP 400 error
* Error message: `"File size too large. Maximum 10MB allowed."`
* File size is checked before processing begins

***

### Image Dimension Requirements

#### Minimum Dimensions

* Minimum size: **256×256 pixels**
* Images smaller than this will fail quality checks
* This is the minimum required input size for the model

#### Maximum Dimensions

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

#### Model Input Processing

* Images are automatically resized to the required input size during processing
* No manual resizing needed - the system handles this automatically
* Original image quality is preserved during resizing

***

### Image Quality Requirements

The `/detect/image` endpoint performs automatic quality checks on all uploaded images. Images must meet the following criteria:

#### 1. Brightness Requirements

* Images must have adequate brightness (not too dark or too bright)
* Images that are too dark or too bright will be rejected

#### 2. Contrast Requirements

* Images must have sufficient contrast
* Low contrast images will be rejected

#### 3. Blur Detection

* Images must be sharp and in focus
* Blurry images will be rejected

#### 4. Face Size Requirements

* Face must occupy at least **10%** of the total image area
* Faces that are too small relative to the image will be rejected

***

### Face Detection Requirements

#### Face Detection Rules

**Single Face Required**

* The endpoint requires **exactly one face** in the image
* Multiple faces will result in rejection
* Error message: `"Multiple faces detected"`

**Face Visibility**

* Face must be clearly visible
* Face should occupy a reasonable portion of the image
* Faces that are too small will be filtered out

#### Rotation Support 🔄

* **EXIF Orientation**: Automatically corrected using image metadata
* **Automatic Rotation**: The endpoint automatically handles rotated images (90°, 180°, 270°)
* No manual rotation needed - the endpoint handles rotated images automatically

#### Face Detection Failure Scenarios

| Scenario                | Status           | Error Message                       | HTTP Status |
| ----------------------- | ---------------- | ----------------------------------- | ----------- |
| No face detected        | `no_face`        | `"No face detected in image"`       | 200         |
| Multiple faces detected | `multiple_faces` | `"Multiple faces detected"`         | 200         |
| Face too small          | `no_face`        | Filtered by size requirements       | 200         |
| Face detection error    | `error`          | `"Face detection error: {details}"` | 200         |

***

### Best Practices

#### ✅ Recommended Practices

**Image Format**

* Use **JPEG format** for best compatibility and performance
* Ensure proper compression (not too compressed, not uncompressed)
* Quality setting: **85-95%** recommended

**Image Size**

* Use images between **256×256 and 2048×2048 pixels**
* Avoid extremely large images (>4096px) as they may be rejected
* Minimum required: **256×256 pixels**

**Image Quality**

* Ensure good lighting (not too dark or too bright)
* Maintain good contrast (avoid washed-out images)
* Use sharp, in-focus images (avoid blurry photos)
* Ensure face occupies at least **10%** of image area

**Face Positioning**

* Face should be clearly visible and centered
* Face should be facing forward (rotation is handled automatically)
* Avoid extreme angles (>45°)
* Ensure face is not partially obscured
* Maintain appropriate distance (face should fill reasonable portion of image)

**File Size**

* Keep file size under **5 MB** for faster processing
* Use appropriate compression to reduce file size
* Avoid uncompressed formats for large images

**Lighting Conditions**

* Use natural or well-distributed lighting
* Avoid harsh shadows or extreme backlighting
* Ensure face is evenly lit

#### ❌ Common Mistakes to Avoid

**File Size**

* ❌ Uploading files larger than 10 MB
* ❌ Using uncompressed formats for large images

**Image Quality**

* ❌ Uploading blurry or out-of-focus images
* ❌ Using images that are too dark or too bright
* ❌ Using low-contrast images
* ❌ Using heavily compressed images (artifacts)

**Face Detection**

* ❌ Images with multiple faces
* ❌ Images with no visible face
* ❌ Faces that are too small relative to image size
* ❌ Faces partially obscured by hands, masks, or objects
* ❌ Extreme face angles (>45°)

**Image Dimensions**

* ❌ Images smaller than 256×256 pixels
* ❌ Images larger than 4096×4096 pixels
* ❌ Extremely wide or tall images (extreme aspect ratios)

***

### Quality Check Summary

All images are automatically validated against these criteria before processing:

| Check            | Requirement         | Action on Failure                  |
| ---------------- | ------------------- | ---------------------------------- |
| File Format      | Supported MIME type | Reject with HTTP 400               |
| File Size        | ≤ 10 MB             | Reject with HTTP 400               |
| Image Dimensions | 256px - 4096px      | Reject with quality check failure  |
| Brightness       | Adequate brightness | Reject with quality check failure  |
| Contrast         | Sufficient contrast | Reject with quality check failure  |
| Blur             | Sharp and in focus  | Reject with quality check failure  |
| Face Presence    | Exactly 1 face      | Reject with face detection failure |
| Face Size        | ≥ 10% of image      | Reject with face detection failure |

***

### 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/image" \
  -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/image"
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": "Deepfake analysis completed successfully",
    "inference_time": 0.523,
    "original_filename": "photo.jpg",
    "face_count": 1,
    "face_confidence": 0.95,
    "prediction_tag": "GENUINE",
    "deepfake_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 (format: `trx_` + 20 char alphanumeric) |
| `filename`                      | string      | Original filename of uploaded image                                   |
| `content_type`                  | string      | MIME type of the uploaded file                                        |
| `status`                        | string      | Overall status: `"success"`, `"skipped"`, or `"failed"`               |
| `status_code`                   | integer     | Numeric status code (1-8) for billing/tracking                        |
| `billable`                      | string      | Billing flag: `"Y"` (billable) or `"N"` (non-billable)                |
| `message`                       | string      | Human-readable message describing the result                          |
| `inference_time`                | float       | Total processing time in seconds                                      |
| `original_filename`             | string      | Original filename                                                     |
| `face_count`                    | integer     | Number of faces detected (0, 1, or >1)                                |
| `face_confidence`               | float/null  | Confidence score of face detection (0.0-1.0) or null                  |
| `prediction_tag`                | string      | Categorical tag indicating the detection result (see below)           |
| `deepfake_check.prediction`     | string/null | Detection result: `"Genuine"`, `"AI-Generated"`, or null              |
| `deepfake_check.confidence`     | float/null  | Detection confidence score (0.0-1.0) or null                          |
| `deepfake_check.inference_time` | float/null  | Detection processing time in seconds or null                          |
| `deepfake_check.status`         | string      | Status: `"performed"` (analysis done) or `"skipped"` (not performed)  |

***

### Prediction Tags Reference

The `prediction_tag` field provides a categorical classification of the detection result or rejection reason:

#### Deepfake Detection Tags

| Tag            | Scenario            | Description                             |
| -------------- | ------------------- | --------------------------------------- |
| `GENUINE`      | Real image detected | The image is genuine (not AI-generated) |
| `AI_GENERATED` | Deepfake detected   | The image appears to be AI-generated    |

#### Face Detection Tags

| Tag          | Scenario                | Description                                        |
| ------------ | ----------------------- | -------------------------------------------------- |
| `NO_FACE`    | No face detected        | No human face found in the image                   |
| `MULTI_FACE` | Multiple faces detected | More than one face detected (single face required) |

#### File Validation Tags

| Tag               | Scenario                 | Description                      |
| ----------------- | ------------------------ | -------------------------------- |
| `INVALID_FORMAT`  | Unsupported file type    | File format not supported        |
| `FILE_TOO_LARGE`  | File size > 10MB         | Uploaded file exceeds size limit |
| `INVALID_SIZE`    | Image < 256×256 pixels   | Image dimensions too small       |
| `IMAGE_TOO_LARGE` | Image > 4096×4096 pixels | Image dimensions too large       |

#### Quality Check Tags

| Tag                | Scenario                | Description                         |
| ------------------ | ----------------------- | ----------------------------------- |
| `BRIGHTNESS_ERROR` | Image too dark/bright   | Brightness outside acceptable range |
| `CONTRAST_ERROR`   | Low contrast            | Insufficient contrast in image      |
| `BLUR_ERROR`       | Image too blurry        | Image is out of focus or blurry     |
| `QUALITY_ERROR`    | Generic quality failure | General image quality check failed  |

#### Processing Tags

| Tag                | Scenario                   | Description                              |
| ------------------ | -------------------------- | ---------------------------------------- |
| `CONVERSION_ERROR` | HEIC conversion failed     | HEIC file could not be converted to JPEG |
| `Security-Error`   | Security validation failed | Security check failed                    |
| `Validation-Error` | Generic validation failed  | Validation check failed                  |
| `PROCESSING_ERROR` | Image processing error     | Error during image processing            |
| `UNKNOWN`          | Fallback/error             | Unexpected scenario or error             |

***

### Status Code Mapping

| Status Code | Billable | Scenario                                         |
| ----------- | -------- | ------------------------------------------------ |
| 1           | Y        | Successful complete analysis                     |
| 2           | N        | Bad request (file type, size, validation errors) |
| 3           | N        | Unauthorized (invalid API key)                   |
| 4           | N        | Not found                                        |
| 5           | N        | Internal server error                            |
| 6           | Y        | No face detected                                 |
| 7           | Y        | Multiple faces detected                          |
| 8           | Y        | Image quality issue (skipped analysis)           |

***

### Response Scenarios

#### 1. Successful Analysis - Genuine Image

**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": "Deepfake analysis completed successfully",
    "inference_time": 0.523,
    "original_filename": "real_photo.jpg",
    "face_count": 1,
    "face_confidence": 0.95,
    "prediction_tag": "GENUINE",
    "deepfake_check": {
      "prediction": "Genuine",
      "confidence": 0.987,
      "inference_time": 0.421,
      "status": "performed"
    }
  }
}
```

#### 2. Successful Analysis - AI-Generated Image

**HTTP Status:** `200 OK`

```json
{
  "image_analysis": {
    "unique_trx_id": "trx_b2c3d4e5f67890123bc",
    "filename": "ai_generated.jpg",
    "content_type": "image/jpeg",
    "status": "success",
    "status_code": 1,
    "billable": "Y",
    "message": "Deepfake analysis completed successfully",
    "inference_time": 0.612,
    "original_filename": "ai_generated.jpg",
    "face_count": 1,
    "face_confidence": 0.95,
    "prediction_tag": "AI_GENERATED",
    "deepfake_check": {
      "prediction": "AI-Generated",
      "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",
    "deepfake_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 (2 faces). Single face required.",
    "inference_time": 0.312,
    "original_filename": "group_photo.jpg",
    "face_count": 2,
    "face_confidence": null,
    "prediction_tag": "MULTI_FACE",
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped"
    }
  }
}
```

#### 5. Image Quality Issue (Blur)

**HTTP Status:** `200 OK`

```json
{
  "image_analysis": {
    "unique_trx_id": "trx_e5f67890123456ef",
    "filename": "blurry.jpg",
    "content_type": "image/jpeg",
    "status": "skipped",
    "status_code": 8,
    "billable": "Y",
    "message": "Image too blurry (variance=50, min=100)",
    "inference_time": 0.156,
    "original_filename": "blurry.jpg",
    "face_count": 0,
    "face_confidence": null,
    "prediction_tag": "BLUR_ERROR",
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": 0.089,
      "status": "skipped"
    }
  }
}
```

#### 6. Unsupported File Type

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

```json
{
  "image_analysis": {
    "unique_trx_id": "trx_f67890123456789fg",
    "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",
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped"
    }
  }
}
```

#### 7. File Too Large

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

```json
{
  "image_analysis": {
    "unique_trx_id": "trx_g7890123456789agh",
    "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",
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped"
    }
  }
}
```

#### 8. 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",
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped"
    }
  }
}
```

#### 9. 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",
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped"
    }
  }
}
```

#### 10. 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",
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped"
    }
  }
}
```

#### 11. Quality Error (Generic)

**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",
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped"
    }
  }
}
```

#### 12. 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",
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped"
    }
  }
}
```

#### 13. 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",
    "deepfake_check": {
      "prediction": null,
      "confidence": null,
      "inference_time": null,
      "status": "skipped"
    }
  }
}
```

#### 14. Internal Server Error

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

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

***

### New Fields Summary

Every API response includes these tracking fields:

| Field           | Symbol | Type    | Purpose                 | Example Values                                 |
| --------------- | ------ | ------- | ----------------------- | ---------------------------------------------- |
| `unique_trx_id` | 🆕     | String  | Transaction tracking    | `"trx_a1b2c3d4e5f6789012ab"`                   |
| `status_code`   | 🆕     | Integer | Billing/monitoring code | `1` (success), `6` (no face), `7` (multi-face) |
| `billable`      | 🆕     | String  | Billing flag            | `"Y"` (billable), `"N"` (non-billable)         |

***

***

### 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, retry later |

#### Retry Strategy

* For 5xx errors, implement exponential backoff
* Wait 1s, 2s, 4s between retries
* Maximum 3 retry attempts recommended

#### 🧩 Scalability

**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.