A simple Flask-based API that extracts the highest-confidence face from an image, expands its bounding box by 20%, and returns the cropped image as a downloadable JPEG file without saving it on the server. The API supports two methods of image input: providing an image URL or uploading an image file.

• Image URL Input: Downloads an image from a given URL.
• File Upload: Accepts an image file uploaded via a form-data POST request.
• Detects faces using the DeepFace library with the Yunet detector.
• Selects the face with the highest confidence.
• Expands the detected face region by 20%.
• Returns the cropped image as a downloadable attachment.
• Minio Integration: Two additional endpoints allow uploading the extracted face (or the original image with the cropped face) directly to a Minio storage server.

The following demonstrates the original image and the cropped face image side by side:

• Python 3.9+
• Docker (optional, for containerized deployment)

1. Clone this repository:

   git clone https://github.com/your_username/face-extraction-api.git
   cd face-extraction-api

2. Install the required dependencies:

   pip install -r requirements.txt

3. Create a .env file in the project root with your Minio configuration. See the example below:

   # .env Example File
   MINIO_ENDPOINT=minio.blazorserver.com
   MINIO_ACCESS_KEY=your_minio_access_key
   MINIO_SECRET_KEY=your_minio_secret_key
   MINIO_BUCKET_NAME=your_bucket_name

4. Run the Flask application:

   python app.py

The API will be available at http://localhost:5000.

1. Build the Docker image:

   docker build -t face-extraction-api .

2. Run the Docker container:

   docker run -p 5000:5000 face-extraction-api

3. Docker compose file:

   version: '3.8'
   services:
     face-extraction-api:
       image: blazordevlab/face-extraction-api:latest
       container_name: faceextraction
       ports:
         - "5000:5000"
       labels:
         - "traefik.enable=true"
         # Replace 'faceextraction.example.com' with your actual domain
         - "traefik.http.routers.faceextraction.rule=Host(`faceextraction.example.com`)"
         - "traefik.http.routers.faceextraction.tls=true"
         - "traefik.http.routers.faceextraction.entrypoints=https"
         - "traefik.http.services.faceextraction.loadbalancer.server.port=5000"
         - "traefik.docker.network=proxy"
       networks:
         proxy:
       security_opt:
         - no-new-privileges:true
   networks:
      proxy:
         external: true      

• Endpoint: /extract_face

• Method: POST

• Payload: JSON object containing the image_url key.

  Example JSON Payload:

  {
    "image_url": "https://example.com/your_image.jpg"
  }

• Response: Returns the cropped face image as a downloadable JPEG file.

• Endpoint: /upload_extract_face

• Method: POST

• Payload: Form-data with an image file in the file field.

  Example using curl:

  curl -X POST -F "file=@/path/to/your_image.jpg" http://localhost:5000/upload_extract_face --output extracted_face.jpg

• Response: Returns the cropped face image as a downloadable JPEG file.

• Endpoint: /extract_face_to_minio

• Method: POST

• Payload: JSON object containing the image_url key.

  Example JSON Payload:

  {
    "image_url": "https://example.com/your_image.jpg"
  }

• Response: Returns a JSON response with:

  • status: Operation status.
  • message: Confirmation that the face has been extracted and uploaded.
  • url: The full URL of the uploaded cropped face image.
  • source: Indicates whether the source URL was from the Minio server or external.

• Endpoint: /upload_face_to_minio

• Method: POST

• Payload: Form-data with:

  • an image file in the file field,
  • a path parameter specifying the target directory in Minio.

  Example using curl:

  curl -X POST -F "file=@/path/to/your_image.jpg" -F "path=test_upload" http://localhost:5000/upload_face_to_minio

• Response: Returns a JSON response with:

  • status: Operation status.
  • message: Confirmation that the file was uploaded to Minio successfully.
  • uploaded_to: Indicates that the file was uploaded to Minio.
  • original_url: The full URL of the original image.
  • face_url: The full URL of the cropped face image (saved under a faces/ subdirectory).

This project is licensed under the MIT License.