API Reference - Maksim3l/MassHealth-Excercise GitHub Wiki

This API provides face verification functionality using a pre-trained deep learning model. It supports comparing individual images, verifying user identities based on stored images, and batch comparisons.

API Endpoints

1. GET /health

Health check for the API and system. Response Example:

{
  "status": "healthy",
  "model_loaded": true,
  "model_path": "/app/models/face_verification_v2.h5",
  "model_exists": true,
  "tensorflow_version": "2.x.x",
  "working_directory": "/app",
  "port": 9002,
  "supabase_connected": true,
  "supabase_url": "https://your.supabase.url"
}

2. GET /model_info

Returns basic information about the loaded face verification model. Response:

{
  "model_loaded": true,
  "total_parameters": 1253737,
  "input_shape": "(None, 100, 100, 3)",
  "output_shape": "(None, 1)",
  "model_layers": 42
}

3. POST /compare

Compare two base64-encoded face images. Request Body:

{
  "image1": "<base64_image_1>",
  "image2": "<base64_image_2>",
  "threshold": 0.5
}

Response:

{
  "match": true,
  "similarity_score": 0.83,
  "threshold": 0.5,
  "confidence": "high"
}

Notes:

  • Default threshold: 0.5
  • confidence is categorized as low, medium, or high based on closeness to the threshold.

4. POST /verify_user

Verify a list of user-provided images against stored verification images on Supabase. Request Body:

{
  "userId": "user123",
  "images": [
    "<base64_img1>", "<base64_img2>", "<base64_img3>"
  ],
  "threshold": 0.5
}

Response:

{
  "user_id": "user123",
  "verification_passed": true,
  "images_matched": 2,
  "total_images_provided": 3,
  "match_percentage": 66.67,
  "threshold": 0.5,
  "verification_images_found": 10,
  "detailed_comparisons": [
    {
      "provided_image_index": 0,
      "matches": [...],
      "has_match": true,
      "best_score": 0.87
    },
    ...
  ]
}

Errors:

  • 503: Model not loaded or Supabase not connected.
  • 400: Missing userId or images.

5. POST /batch_compare

Compare multiple image pairs at once. Request Body:

{
  "pairs": [
    { "image1": "<base64_img1>", "image2": "<base64_img2>" },
    { "image1": "<base64_img3>", "image2": "<base64_img4>" }
  ],
  "threshold": 0.5
}

Response:

{
  "matches": [true, false],
  "detailed_results": [
    {
      "pair_index": 0,
      "match": true,
      "similarity_score": 0.77,
      "confidence": "medium"
    },
    {
      "pair_index": 1,
      "match": false,
      "error": "Failed to process this pair"
    }
  ],
  "threshold": 0.5,
  "total_pairs": 2,
  "successful_pairs": 1
}

Notes:

  • Accepts up to 10 pairs.
  • Returns both a summary and detailed diagnostic info.

Model Information

  • Format: .h5 Keras model
  • Input shape: (100, 100, 3)
  • Output: Similarity score between 0 and 1
  • Custom layers:
    • L1Dist, EuclideanDistance, ContrastiveLoss, Cast

Supabase Integration

Used to store and retrieve verification images
Bucket: `images`
Path: `<userId>/verify1.jpg, ..., verify10.jpg`

Security & Limits

  • Max 10 images per request (/verify_user)
  • Threshold adjustable per request
  • Does not currently support authentication/authorization
  • Avoid sending full images in logs for privacy

Error Handling

Status Message
400 Missing fields (e.g. image1, userId)
404 No images found in Supabase
500 Internal server error
503 Model not loaded or Supabase not connected
⚠️ **GitHub.com Fallback** ⚠️