> 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
### 🔐 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.**
## /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.
---
# 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/ai-generated-image-detection.md?ask=&goal=
```
`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.