Hugging Face's logo

Spaces:
Jay9115
/
Deep_fake_Model_load
Sleeping

App Files Community
Deep_fake_Model_load / API_DOCUMENTATION.md
Jay9115's picture
Jay9115
api_modify
f24b1d0
preview code
|
Raw History Blame Contribute Delete
14 kB

Deepfake Detection API - Complete API Reference

Base URL 

http://localhost:8000

API Endpoints Overview

1. Root Endpoint

  • Endpoint: GET /
  • Description: Returns API status and available endpoints
  • Authentication: None
  • Response Format: JSON

2. Health Check (Comprehensive)

  • Endpoint: GET /api/health
  • Description: Comprehensive health check with system diagnostics
  • Authentication: None
  • Response Format: JSON

3. Health Check (Simple)

  • Endpoint: GET /api/health/simple
  • Description: Simple health check for load balancers
  • Authentication: None
  • Response Format: JSON

4. Readiness Probe

  • Endpoint: GET /api/health/ready
  • Description: Kubernetes-style readiness probe
  • Authentication: None
  • Response Format: JSON

5. Liveness Probe

  • Endpoint: GET /api/health/live
  • Description: Kubernetes-style liveness probe
  • Authentication: None
  • Response Format: JSON

6. Combined Prediction

  • Endpoint: POST /api/predict
  • Description: Combined prediction using both XceptionNet and MesoNet models
  • Parameter: file (multipart/form-data)
  • Authentication: None
  • Response Format: JSON

3. XceptionNet Prediction

  • Endpoint: POST /api/xceptionnet/predict
  • Description: Deepfake detection using XceptionNet model
  • Parameter: image (multipart/form-data)
  • Authentication: None
  • Response Format: JSON

4. XceptionNet Model Info

  • Endpoint: GET /api/xceptionnet/info
  • Description: Get XceptionNet model information
  • Authentication: None
  • Response Format: JSON

5. MesoNet Prediction

  • Endpoint: POST /api/mesonet/predict
  • Description: Deepfake detection using MesoNet model
  • Parameter: image (multipart/form-data)
  • Authentication: None
  • Response Format: JSON

6. MesoNet Model Info

  • Endpoint: GET /api/mesonet/info
  • Description: Get MesoNet model information
  • Authentication: None
  • Response Format: JSON

7. GradCAM Analysis

  • Endpoint: POST /api/gradcam/analyze
  • Description: Generate GradCAM analysis with prediction and visualization (PDF report)
  • Parameter: image (multipart/form-data)
  • Authentication: None
  • Response Format: JSON with base64 encoded PDF

8. GradCAM Batch Analysis

  • Endpoint: POST /api/gradcam/analyze-batch
  • Description: Batch GradCAM analysis for multiple images
  • Parameter: images (multipart/form-data, multiple files)
  • Authentication: None
  • Response Format: JSON with array of results

9. GradCAM Model Info

  • Endpoint: GET /api/gradcam/model-info
  • Description: Get GradCAM model information
  • Authentication: None
  • Response Format: JSON

10. GradCAM Test

  • Endpoint: GET /api/gradcam/test
  • Description: Test GradCAM functionality
  • Authentication: None
  • Response Format: JSON

Detailed API Specifications

1. Root Endpoint

Request:

GET /

Response:

{
  "status": "ok",
  "message": "Deepfake Detection API Backend is running",
  "available_endpoints": {
    "combined_prediction": "/api/predict",
    "xceptionnet_prediction": "/api/xceptionnet/predict",
    "xceptionnet_info": "/api/xceptionnet/info",
    "mesonet_prediction": "/api/mesonet/predict",
    "mesonet_info": "/api/mesonet/info",
    "gradcam_analysis": "/api/gradcam/analyze",
    "gradcam_batch": "/api/gradcam/analyze-batch",
    "gradcam_info": "/api/gradcam/model-info",
    "gradcam_test": "/api/gradcam/test"
  },
  "usage": {...},
  "new_features": {...}
}

2. Health Check API (Comprehensive)

Request:

GET /api/health

Success Response (200):

{
  "status": "healthy",
  "timestamp": "2025-10-14T12:30:45.123456",
  "uptime": "running",
  "models": {
    "xceptionnet": "loaded",
    "mesonet": "loaded"
  },
  "system_resources": {
    "memory": {
      "total_gb": 16.0,
      "available_gb": 8.5,
      "used_percent": 46.9
    },
    "disk": {
      "total_gb": 500.0,
      "free_gb": 250.0,
      "used_percent": 50.0
    },
    "cpu_percent": 25.3
  },
  "directories": {
    "uploads": true,
    "models": true
  },
  "api_version": "1.0.0",
  "service": "Deepfake Detection API"
}

Degraded Response (200):

{
  "status": "degraded",
  "timestamp": "2025-10-14T12:30:45.123456",
  "uptime": "running",
  "models": {
    "xceptionnet": "loaded",
    "mesonet": "not available"
  },
  "system_resources": {...},
  "directories": {...},
  "api_version": "1.0.0",
  "service": "Deepfake Detection API"
}

Unhealthy Response (200):

{
  "status": "unhealthy",
  "timestamp": "2025-10-14T12:30:45.123456",
  "error": "Error message",
  "service": "Deepfake Detection API"
}

3. Health Check API (Simple)

Request:

GET /api/health/simple

Success Response (200):

{
  "status": "healthy",
  "timestamp": "2025-10-14T12:30:45.123456"
}

Degraded Response (200):

{
  "status": "degraded",
  "timestamp": "2025-10-14T12:30:45.123456",
  "reason": "models not loaded"
}

4. Readiness Probe API

Request:

GET /api/health/ready

Success Response (200):

{
  "ready": true,
  "timestamp": "2025-10-14T12:30:45.123456"
}

Not Ready Response (200):

{
  "ready": false,
  "timestamp": "2025-10-14T12:30:45.123456",
  "reason": "models not loaded"
}

5. Liveness Probe API

Request:

GET /api/health/live

Success Response (200):

{
  "alive": true,
  "timestamp": "2025-10-14T12:30:45.123456"
}

6. Combined Prediction API

Request:

POST /api/predict
Content-Type: multipart/form-data

Parameters:

  • file: Image file (JPG, PNG, JPEG)

Success Response (200):

{
  "prediction": {
    "combined": 0.7234,
    "xceptionnet": 0.7856,
    "mesonet": 0.6234
  },
  "interpretation": {
    "result": "Fake",
    "confidence": 0.8934
  }
}

Error Responses:

  • 400: No file provided / Invalid image format
  • 500: Model not available / Prediction failed

3. XceptionNet Prediction API

Request:

POST /api/xceptionnet/predict
Content-Type: multipart/form-data

Parameters:

  • image: Image file (JPG, PNG, JPEG)

Success Response (200):

{
  "prediction": {
    "probability": 0.7856,
    "label": "fake",
    "confidence": 0.8934
  }
}

Error Responses:

  • 400: No file provided / Invalid image format
  • 500: XceptionNet model not available / Prediction failed

4. XceptionNet Model Info API

Request:

GET /api/xceptionnet/info

Success Response (200):

{
  "model_info": {
    "name": "XceptionNet",
    "input_shape": "(299, 299, 3)",
    "type": "CNN with Face Detection",
    "task": "Deepfake Detection",
    "status": "loaded"
  }
}

Error Response:

  • 500: Server error

5. MesoNet Prediction API

Request:

POST /api/mesonet/predict
Content-Type: multipart/form-data

Parameters:

  • image: Image file (JPG, PNG, JPEG)

Success Response (200):

{
  "prediction": {
    "probability": 0.6234,
    "label": "fake",
    "confidence": 0.7689
  }
}

Error Responses:

  • 400: No file provided / Invalid image format
  • 500: MesoNet model not available / Prediction failed

6. MesoNet Model Info API

Request:

GET /api/mesonet/info

Success Response (200):

{
  "model_info": {
    "name": "MesoNet",
    "input_shape": "(256, 256, 3)",
    "type": "CNN with Face Detection",
    "task": "Deepfake Detection",
    "status": "loaded"
  }
}

Error Response:

  • 500: Server error

7. GradCAM Analysis API

Request:

POST /api/gradcam/analyze
Content-Type: multipart/form-data

Parameters:

  • image: Image file (JPG, PNG, JPEG)
  • userId: User ID (string, required) - Identifies the user making the request

Success Response (200):

{
  "prediction": {
    "probability": 0.7856,
    "label": "fake",
    "confidence": 0.8934,
    "classification": "deepfake"
  },
  "technical_details": {
    "face_confidence": 0.95,
    "processing_time_ms": 1234,
    "model_layer": "block14_sepconv2_act",
    "image_hash": "a1b2c3d4e5f6g7h8..."
  },
  "report_info": {
    "format": "application/pdf",
    "status": "generated_and_saved",
    "message": "PDF report has been generated and saved to cloud storage",
    "access_via": "Use the URL in saved_files to access the PDF report"
  },
  "saved_files": {
    "pdf_filename": "gradcam_deepfake_image_20250114_123045.pdf",
    "pdf_url": "https://supabase.co/storage/v1/object/public/...",
    "supabase_path": "deepfake-reports/gradcam_deepfake_image_20250114_123045.pdf",
    "primary_storage": "supabase",
    "saved_at": "2025-01-14T12:30:45.123456",
    "file_size_mb": 2.45,
    "storage_locations": ["supabase", "local"]
  },
  "database": {
    "record_id": "uuid-here",
    "stored": true
  }
}

Error Responses:

  • 400: No file provided / Invalid image format / userId is required
  • 500: GradCAM analysis failed

8. GradCAM Batch Analysis API

Request:

POST /api/gradcam/analyze-batch
Content-Type: multipart/form-data

Parameters:

  • images: Multiple image files (JPG, PNG, JPEG)
  • userId: User ID (string, required) - Identifies the user making the request

Success Response (200):

{
  "batch_summary": {
    "total_images": 5,
    "successful": 4,
    "failed": 1,
    "deepfakes_detected": 2,
    "authentic_detected": 2,
    "batch_processing_time_ms": 5234,
    "average_time_per_image_ms": 1046
  },
  "results": [
    {
      "filename": "image1.jpg",
      "success": true,
      "prediction": {
        "probability": 0.7856,
        "label": "fake",
        "confidence": 0.8934,
        "classification": "deepfake"
      },
      "technical_details": {
        "face_confidence": 0.95,
        "processing_time_ms": 1234,
        "image_hash": "a1b2c3d4e5f6g7h8..."
      },
      "report_format": "application/pdf",
      "saved_files": {
        "pdf_filename": "gradcam_deepfake_batch_001_image1_20250114_123045.pdf",
        "pdf_url": "https://supabase.co/storage/v1/object/public/...",
        "supabase_path": "deepfake-reports/gradcam_deepfake_batch_001_image1_20250114_123045.pdf",
        "primary_storage": "supabase",
        "saved_at": "2025-01-14T12:30:45.123456",
        "file_size_mb": 2.45,
        "storage_locations": ["supabase", "local"]
      },
      "database": {
        "record_id": "uuid-here",
        "stored": true
      }
    },
    {
      "filename": "image2.jpg",
      "success": false,
      "error": "Invalid image format"
    }
  ]
}

Error Responses:

  • 400: No images provided / userId is required
  • 500: Batch analysis failed

9. GradCAM Model Info API

Request:

GET /api/gradcam/model-info

Success Response (200):

{
  "model": {
    "name": "XceptionNet",
    "status": "loaded",
    "target_layer": "block14_sepconv2_act"
  },
  "gradcam": {
    "type": "Optimized GradCAM",
    "memory_optimization": "enabled"
  }
}

Error Response:

  • 500: Server error

10. GradCAM Test API

Request:

GET /api/gradcam/test

Success Response (200):

{
  "status": {
    "model_loaded": true,
    "memory_optimization": "enabled",
    "gradcam_ready": true
  }
}

Error Response:

  • 500: Server error

Error Handling

All endpoints follow a consistent error response format:

{
  "detail": "Error message describing what went wrong"
}

Common HTTP Status Codes:

  • 200: Success
  • 400: Bad Request (invalid input)
  • 404: Not Found
  • 500: Internal Server Error

Image Requirements

Supported Formats:

  • JPEG (.jpg, .jpeg)
  • PNG (.png)

Recommendations:

  • Image should contain a clear, visible face
  • Minimum resolution: 256x256 pixels
  • Maximum file size: 10MB (recommended)
  • Face should be well-lit and clearly visible

Testing with cURL

Test Root Endpoint: 

curl -X GET http://localhost:8000/

Test Combined Prediction: 

curl -X POST http://localhost:8000/api/predict \
  -F "file=@/path/to/image.jpg"

Test XceptionNet Prediction: 

curl -X POST http://localhost:8000/api/xceptionnet/predict \
  -F "image=@/path/to/image.jpg"

Test XceptionNet Info: 

curl -X GET http://localhost:8000/api/xceptionnet/info

Test MesoNet Prediction: 

curl -X POST http://localhost:8000/api/mesonet/predict \
  -F "image=@/path/to/image.jpg"

Test MesoNet Info: 

curl -X GET http://localhost:8000/api/mesonet/info

Test GradCAM Analysis: 

curl -X POST http://localhost:8000/api/gradcam/analyze \
  -F "image=@/path/to/image.jpg" \
  -F "userId=user123" \
  --output response.json

Test GradCAM Batch: 

curl -X POST http://localhost:8000/api/gradcam/analyze-batch \
  -F "images=@/path/to/image1.jpg" \
  -F "images=@/path/to/image2.jpg" \
  -F "userId=user123" \
  --output batch_response.json

Test GradCAM Model Info: 

curl -X GET http://localhost:8000/api/gradcam/model-info

Test GradCAM Test: 

curl -X GET http://localhost:8000/api/gradcam/test

Notes

  1. Port Configuration: Default port is 8000. Can be changed in app.py
  2. CORS: Enabled for all origins (configured for development)
  3. Model Loading: Models are cached after first load for better performance
  4. Face Detection: Uses MTCNN for automatic face detection
  5. PDF Reports: GradCAM endpoints generate professional A4 PDF reports
  6. Memory Optimization: Server uses optimized memory management for production deployment