Image Merger API

A Flask based Web API to merge a two PNG images(i.e may be background and foreground) and it returns the output image url and in base64 format also. The API is REST API and uses nothing for user authentication purposes. Currently, return format for all endpoints is JSON.

Instructions

1. Clone repository to local machine and go to project directory

2. Setup virtual environment based on python3.8.X and activate it

3. Install all project's python depenedencies

   pip install -r requirements.txt

4. Create .env file by copying .env.example in project directory

   cp .env.example .env

5. Set proper values as per environment in .env file

6. Run following command to run flask development server

   flask run

7. To run in production mode, use gunicorn app server

   gunicorn app:app

   Please note, always set FLASK_ENV=Production and APP_SETTINGS=config.Production in .env file.

API Resources and URI Structure

URIs for a Image Merging REST API resource have the following structure:

https://image-merger.herokuapp.com/api/v1.0/merge-images/

Method Supported : POST

Send a payload of JSON format like this:

{
    "foreground_url" : "image url",
    "background_url" : "image url"
}

Note :

1. Request must be JSON type i.e Content-Type : application/json
2. Images should be of same sizes and of PNG format.

Media Types

This REST API return HTTP responses in JSON formats:

{
    "output_image" : {
        "name" : "Image Name",
        "url" : "Image Absolute Url",
        "base64" : "Image in base64 format"
    }
}

You can download the merged output image through url returned in reponse. It is recommended to consume base64 output of image.

HTTP Error Response

This REST API also return HTTP error response in JSON formats with proper HTTP Status Code as follows:

{
    "Error" : "Message"
}

Error Message may be of following types:

• Not Valid Url ( HTTP Status Code : 202 )
• Images Not Found ( HTTP Status Code : 202 )
• Format Not Supported ( HTTP Status Code : 202 )
• Not Same Size Images ( HTTP Status Code : 202 )
• Internal Error. Please Try Again ( HTTP Status Code : 202 )
• Bad Request ( HTTP Status Code : 400 )
• Not Found ( HTTP Status Code : 404 )
• Method Not Allowed ( HTTP Status Code : 405 )
• Internal Server Error ( HTTP Status Code : 500 )

Examples

Let we make a POST request with payload in valid format, like this:

{
    "foreground_url" : "https://image-merger.herokuapp.com/static/img/foreground.png",
    "background_url" : "https://image-merger.herokuapp.com/static/img/background.png"
}

Foreground Image

Background Image

Then , we get a response in JSON style , like this:

{
    "output_image" : {
        "name" : "5c359e06d7b9e4c21b699758c18ce335.jpeg",
        "url" : "https://image-merger.herokuapp.com/merged-images/5c359e06d7b9e4c21b699758c18ce335.jpeg",
        "base64" : "iVBORw0KGgoAAAANSUhEUgA.....SUVORK5CYII="
    }
}

Merged Output Image