Public Repository

Last pushed: 5 months ago
Short Description
Image service with advanced capabilities : on the fly resizing + caching.
Full Description


This is an image service with on the fly resize, filling, fitting capabilities. The service always keep aspect ratio of image, thus filling to a given size will scale + crop to avoid deformation.

More, the service also supports extraction of a source rectangle on images.

All returned images can be cached on the server if redis is available (recommended), and HTTP caching (Cache-Control header is filled properly) information is always sent for proper handling by the client (usually a browser).

A simple token authentication scheme is also provided, and is usable in production as long as you serve over HTTPS.

Launch the service

Here is a docker-compose.yml sample to get you started:

version: '2'
    image: clems71/imapi
      - redis
      - mongodb
      - 8080:8080
      - REDIS_HOST=redis
      - MONGODB_URL=mongodb://mongodb:27017/imapi-test
    image: redis:3-alpine
    image: mvertes/alpine-mongo

$ docker-compose run --service-ports imapi

And you should have an instance of imAPI available on http://localhost:8080.

Upload an image

$ curl -F "image=@image.jpg" http://<imapiHost>/images


Get an image

All modes will output the image in the same format as the originally uploaded image. If JPG was uploaded then JPG is given back to you. You can change this by querying a different format with ?format=png or ?format=jpg

Supported queries

  • mode: original (default) | fill | fit
  • width: not specified = same as original | integer
  • height: not specified = same as original | integer
  • format: not specified = same as original | jpg | png
  • background: default to rgba(0,0,0,255)
  • sharpen: false (default) or true | on

background is used when performing a fit operation, to select the background color. It is alos used when asking for JPG format when the source was PNG with transparent background, to select the new background color. It hence flatten the image.

Original image


Fill to a given width (keep aspect ratio)


Fill to a given height (keep aspect ratio)


Fill to a given size


Fit to a given rectangle


Extract a rectangle


200x200, top-left extraction

rect format is the following rect=X,Y,W,H, in a top-left coordinates basis:

  • X: distance from left of image
  • Y: distance from top of image
  • W: width
  • H: height

rect also supports basic math expression evaluation. Available variables include w and h for respectively the width and height of original image. As an example, to extract a centered 100x100 patch from an image, you can use the following rect expression:


Of course, all operators are still available when extracting a part of an image (mode, format, ...).



Docker Pull Command