Skip to content

A flask based web api to merge a two PNG images(i.e background and foreground) and return the merged image url and in base64 format


Notifications You must be signed in to change notification settings


Repository files navigation

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.


  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:

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 )


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

    "foreground_url" : "",
    "background_url" : ""

Foreground Image

Foreground Image

Background Image

Background Image

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

    "output_image" : {
        "name" : "5c359e06d7b9e4c21b699758c18ce335.jpeg",
        "url" : "",
        "base64" : "iVBORw0KGgoAAAANSUhEUgA.....SUVORK5CYII="

Merged Output Image

Merged Image


A flask based web api to merge a two PNG images(i.e background and foreground) and return the merged image url and in base64 format







No packages published