Expert in Blazor development. Available for project collaborations!
Contact me

Face Extraction API with Flask and DeepFace

Apr 3, 2025

Description

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

Features

  • Image URL Input: Supports processing images by downloading them from a provided URL.
  • File Upload: Accepts image files uploaded directly via a multipart/form-data POST request.
  • Utilizes the DeepFace library, specifically the Yunet detector, for face detection.
  • Automatically selects the face detected with the highest confidence score.
  • Enlarges the bounding box of the detected face by 20% to ensure complete capture.
  • Provides the cropped face image as a downloadable JPEG attachment.
  • Minio Integration: Features optional endpoints for uploading the extracted face (or the original image with the detected face highlighted) directly to a Minio object storage server.

Example

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

Original Image Cropped Face Image

Requirements

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

Installation and Running Locally

  1. Clone this repository to your local machine:

    git clone https://github.com/neozhu/face-extraction-api.git 
    # Replace with your fork if necessary
    cd face-extraction-api
    
  2. Install the required Python dependencies:

    pip install -r requirements.txt
    
  3. Create a .env file in the project’s root directory and populate it with your Minio server configuration details, similar to the example below:

    # Example .env Configuration
    MINIO_ENDPOINT=minio.example.com
    MINIO_ACCESS_KEY=YOUR_MINIO_ACCESS_KEY
    MINIO_SECRET_KEY=YOUR_MINIO_SECRET_KEY
    MINIO_BUCKET_NAME=your-target-bucket
    

    Ensure you replace placeholder values with your actual Minio credentials and endpoint.

  4. Run the Flask application:

    python app.py
    

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

Running with Docker

  1. Build the Docker image:

    docker build -t face-extraction-api .
    
  2. Run the Docker container, mapping port 5000:

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

    (Ensure your .env file is accessible to Docker if not using build arguments for secrets.)

  3. Example Docker Compose configuration:

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      

API Endpoints

1. Extract Face by Image URL

  • Endpoint: /extract_face

  • Method: POST

  • Request Payload: JSON object containing the image_url key.

    Example JSON Payload:

    {
      "image_url": "https://example.com/path/to/your_image.jpg"
    }
    
  • Success Response: Returns the cropped face image as a downloadable JPEG file (image/jpeg).

2. Extract Face by File Upload

  • Endpoint: /upload_extract_face

  • Method: POST

  • Request Payload: multipart/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
    
  • Success Response: Returns the cropped face image as a downloadable JPEG file (image/jpeg).

3. Extract Face from Image URL and Upload to Minio

  • Endpoint: /extract_face_to_minio

  • Method: POST

  • Request Payload: JSON object containing the image_url key.

    Example JSON Payload:

    {
      "image_url": "https://example.com/path/to/your_image.jpg"
    }
    
  • Success Response: JSON object with:

    • status (string): Operation status (e.g., “success”).
    • message (string): Confirmation message indicating successful extraction and upload.
    • url (string): The full URL of the uploaded cropped face image in Minio.
    • source_type (string): Indicates if the source image URL was from the Minio server itself (“minio”) or an external location (“external”).

4. Upload Image, Extract Face, and Upload Both to Minio

  • Endpoint: /upload_face_to_minio

  • Method: POST

  • Request Payload: multipart/form-data with:

    • An image file in the file field.
    • A path parameter (string, optional) specifying the target directory in Minio for the original image.

    Example using curl:

    curl -X POST -F "file=@/path/to/your_image.jpg" -F "path=uploads/test_images" http://localhost:5000/upload_face_to_minio
    
  • Success Response: JSON object with:

    • status (string): Operation status.
    • message (string): Confirmation of successful upload to Minio.
    • storage_destination (string): Confirms the file was uploaded to Minio.
    • original_url (string): The full URL of the original uploaded image in Minio.
    • face_image_url (string): The full URL of the cropped face image, typically saved under a faces/ subdirectory relative to the original image path in Minio.

License

This project is licensed under the MIT License.

Want to know more about what I am working on?

My GitHub showcases most of my projects and ideas. Feel free to take a look and explore more technical possibilities together.

Check out my GitHub