Image API

Image manipulation is achieved by Image API. You just need to provide query string parameters to manipulate images. Each query string parameter is described below. Any parameter having invalid value will be discarded and will not have any effect on output.

Let us remind you again that you just need a free Gumlet account to get started. You can create one here.

Size

The size parameters allow you to control all aspects of resizing, cropping, and the fit-to-crop behavior of your image.

width (w)

This parameter sets width of output image. w is an alias for this parameter.

If this parameter is omitted, and the height parameter is set, the output width is set automatically such that aspect ratio is preserved. If both height and width parameters are set, the output image dimensions are set as per mode parameter.

If none of the height and width parameters are set, original aspect ratio is preserved and output dimensions depend on parameters like scale if provided.

Maximum value for this is 8192 and any output which has more than this width will be scaled down to this value.

width=250

original

width=250

original

height (h)

This parameter sets height of output image. h is an alias for this parameter.

If this parameter is omitted, and the width parameter is set, the output height is set automatically such that aspect ratio is preserved. If both height and width parameters are set, the output image dimensions are set as per mode setting.

If none of the height and width parameters are set, original aspect ratio is preserved and output dimensions depend on parameters like scale if provided.

Maximum value for this is 8192 and any output which has more than this height will be scaled down to this value.

height=200

original

height=200

original

dpr

Specifies device pixel ratio. Valid values are 1, 2 and 3. This acts as multiplier to both width and height. width=200&height=300&dpr=2 is equivalent to width=400&height=600.

This makes it easy to specify image with correct resolution when using srcset attribute of <img> tag.

enlarge

This boolean parameter specifies whether the output image should be enlarged if input image dimensions are smaller than required dimensions.

For example, if input image width is 800px wide and width=1000 is specified, the output image will still remain 800px. If enlarge=true is set then only the output image will have 1000px width.

Default value of this parameter is false if mode is crop or stretch and true otherwise. You can't override the default false if mode is set to crop or stretch

mode

Specifies the resize behavior when width or height parameters are provided.

fit: Resize to fit within boundaries specified by width and height parameters. If ratio given differs from original aspect ratio, only one dimension will be set as per given value and other dimension will be smaller such that original aspect ratio is maintained.

crop: Entire area defined is filled maintaining aspect ratio but might crop part of image. The type of cropping is determined by crop parameter.

stretch: Resize to fill area defined by height and width. It might not preserve aspect ratio and image might be distorted.

min: Preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than or equal to the width and height specified.

max: Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to the width and height specified.

fill: Preserving aspect ratio, resize the image to the maximum width or height specified then embed on a background of the exact width and height as original image. You can fill excess space with fill parameter.

Default mode is fit.

mode=fit

mode=crop

mode=stretch

mode=fit

mode=crop

mode=stretch

fill

This parameter specifies how to fill the extra space created by mode=fill.

solid Fills access space with solid color specified by parameter fill-color. If fill-color is not specified then access space will be filled with white.

blur Fills access space with blurred original image.

Default value of this parameter is solid.

mode=fit

mode=fill&fill=solid&fill-color=c0c0c0

mode=fill&fill=blur

mode=fit

mode=fill&fill=solid&fill-color=c0c0c0

mode=fill&fill=blur

crop

Allows you to define crop position when using crop as mode parameter.

Valid values are entropy, smart, top, topleft, left, bottomleft, bottom, bottomright, right, topright , faces and center.

While other modes are self explanatory, let us describe first some special crop modes.

faces: detects all faces in an image and tries to keep them in center in cropped image.

entropy: focus on region with highest Shanon Entropy.

smart: focus on region with highest luminance frequency and skin tones. Gumlet automatically finds person or other objects in image and keeps them in center while cropping.

Default mode if no parameter is provided is center.

mode=crop

mode=crop&crop=smart

original

mode=crop

mode=crop&crop=smart

original

extract (rect)

Extract a region from image. rect is an alias for this parameter. This operation is always applied before resize operation. Please give the parameters according to original image.

The value should be provided as comma separated list left,top,width,height.

• left is zero-indexed offset from left edge

• top is zero-indexed offset from top edge

• width of extracted image

• height of extracted image

extract=0,0,300,300

extract=300,300,200,200

original

extract=0,0,300,300

extract=300,300,200,200

original

aspect ratio (ar)

Resize and crop the image to given aspect ratio. This parameter will work only with mode=crop. ar is proportional representation between width and height.

E.g. ar=3:4&mode=crop will crop image in aspect ratio of 3:4. You can add one dimension (height or width) along with ar and other dimension will be automatically calculated based on aspect ratio. height=400&ar=3:4&mode=crop here width 300 will be automatically calculated.

height=400&ar=3:4&mode=crop

ar=1:1&mode=crop&crop=smart

original

height=400&ar=3:4&mode=crop

ar=1:1&mode=crop&crop=smart

original

pad

Pads/Extends the edges of the image with the color provided by the background parameter. The value should either be integer which adds padding of same number of pixel to all edges or it should be comma separated list of 4 integers as top,right,bottom,left.

E.g. pad=40,20,40,30 will add 40px padding on top, 20px on right, 40px on bottom and 30px on left. If you want to add same padding to all sides, you can provide just one number like pad=40 and it will add 40px on all sides.

Please note this operation will add additional pixels and hence increase height and width of image. This operation is applied after resize. Please provide padding parameters accordingly.

pad=30,30,30,30&bg=b03e5c

original

pad=30,30,30,30&bg=b03e5c

original

trim

Trim "boring" pixels from all edges that contain values within a percentage similarity of the top-left pixel. The value of this parameter is number between 1 to 99 representing the percentage similarity.

This operation is applied after resize.

trim=50

original

trim=50

original

Image Formats

These parameters allow changing image formats and different parameters related to those formats.

input formats

Gumlet supports following input formats: JPEG, PNG, WebP, TIFF, PDF, GIF, SVG, RAW, HEIF.

output formats

Gumlet supports image output in following formats: JPEG, PNG, WebP, TIFF, GIF, SVG, RAW, HEIF.

metadata

Controls whether image metadata from original image should be kept in output image. If this parameter is set to true all metadata is kept.

Default value is false means all metadata will be removed to ensure smallest output image size.

format

Gumlet serves same image format as source image after performing operations. If you want to change output image format, you can use this parameter.

You can use auto, jpeg, jpg, png, webp, tiff, json or raw. If original image has alpha channel and output does not support transparency, a white background is applied if background parameter is not provided.

If you use format=auto, Gumlet automatically detects best format according to user browser. For example, Google Chrome supports WebP hence that format will be delivered to users visiting with Chrome browser. When user browser does not support WebP, default image format as per original image is served. WebP image is almost always lesser size for same image quality which results in lower bandwidth usage and faster load times.

json

format=json will return information about the original image or PDF. For example: https://demo.gumlet.com/boat.jpeg?format=json​

{
  "format": "jpeg",
  "size": 68751,
  "width": 752,
  "height": 498,
  "space": "srgb",
  "channels": 3,
  "density": 72,
  "chromaSubsampling": "4:2:0",
  "isProgressive": true,
  "hasProfile": true,
  "hasAlpha": false
}

If you would like to detect faces along with JSON information, you can pass faces=true along with format=json and the API will return detected face co-ordinates with other information.

For example if you are using Chrome, all images you saw above are delivered as WebP and not as JPEG. You can check it in content-type response header.

If you check total downloaded content in "Network" tab of Chrome and Firefox, you will see Chrome uses lesser bandwidth because of WebP image delivery.

pdf

PDF files can be converted to image using Gumlet API. You need to use page parameter to extract given page from a PDF file.

gif

We also support processing GIF images. If source image is GIF, you can pass any of width, height, stretch, extract, flip, rotate and gamma parameters while processing them. Other operations are not supported for GIF images as of now.

width=200

original

width=200

original

Converting other formats to GIF or converting GIF to other format is also not supported. Please contact us if you need any such support.

quality (q)

Sets output quality of image. q is an alias for this parameter. Valid values are between 0 and 100 inclusive of them.

This parameter only takes effect when using jpeg or webp as output format

Setting this parameter to 100 will produce highest quality image. Default value is 85.

page

If input is multi page image like GIF or anitmated WebP or PDF file, this parameter will extract page from the input and convert it to output format specified.

subsample

Enables or disables chroma subsampling. When it's set to true it applies 4:2:0 chroma subsampling. When it's set to false, it keeps chroma subsampling parameter to 4:4:4.

Default value is true.

compress

Gumlet automatically converts all JPEG images to progressive image and applies lossless quality optimizations by default.

If you set compress=true, we further apply lossy optimizations on image which can greatly reduce resultant image size without perceptual loss of quality. As illustrated in example below, most of time, it results in 30-50% reduction in resultant image size with almost no loss in quality.

This feature only works when output is produced in JPEG or PNG format.

compress=true (2.4 MB)

original (3.8 MB)

compress=true (2.4 MB)

original (3.8 MB)

Color Manipulations

These parameters allow changing colors of the image.

colorspace (colourspace)

This parameter changes colorspace of a given image. It's very useful to convert one colorspace to another for example RGB to CMYK.

Supported values include srgb, rgb, lab, cmyk and b-w.

background (bg)

Value of this parameter is used when mode is set as fill or you are converting other image type to jpeg or you are padding image with pad parameter.

This can be any of valid css color name like white or yellow. You can also set RGB hex value like bg=ff00bb to set background to #ff00bb value.

If you don't pass any parameter, default value is white.

brightness (bri)

You can change brightness of image with this parameter. Valid values are from -100 to 100 . Default value 0 means no change in original image brightness.

saturation (sat)

You can change saturation of image with this parameter. Valid values are from -100 to 100 . Default value 0 means no change in original image saturation.

hue (hue)

You can change hue of image with this parameter. Valid values are from 0 to 360 . Default value 0 means no change in original image hue.

tint

This can be used to set a tint to the image.

This can be any of valid css color name like white or yellow. You can also set RGB hex value like tint=ff00bb to set tint to #ff00bb value.

If you don't pass any parameter, default behaviour is to not apply any tint.

bri=10

sat=-50

hue=90

tint=blue

original

bri=10

sat=-50

hue=90

tint=blue

original

grayscale (greyscale)

Convert to 8-bit greyscale; 256 shades of grey. This is a linear operation. If the input image is in a non-linear colour space such as sRGB, use gamma with greyscale for the best results. By default the output image will be web-friendly sRGB and contain three (identical) color channel.

greyscale=true or grayscale=true are both valid parameters.

greyscale=true

original

greyscale=true

original

invert

Produces negative of image. You can use it as invert=true

invert=true

original

invert=true

original

enhance

Enhance output image contrast by stretching its luminance to cover the full dynamic range. Enable it by setting enhance=true

Image Operations

Perform most commonly used image operations.

rotate

Rotates the image as per number of degrees provided as 0, 90, 180 or 270

flip

flip=v will vertically flip the image. flip=h will horizontally flip the image. flip=hv or flip=vh will flip both horizontally and vertically.

blur

Applies Gaussian blur of a given blur radius in float. blur=2.5 will blur the image by taking gaussian blur of 2.5 pixel radius. Valid values are between 0 and 100.

blur=10

original

blur=10

original

threshold

Any pixel value greather than or equal to the threshold value will be set to 255, otherwise it will be set to 0. The parameter should be integer between 0 and 255

threshold=100

original

threshold=100

original

opacity (o)

You can change image opacity by using this parameter. The value can be between 0 and 100 . 0 being fully transparent and 100 being most opaque. The default value is undefined

For JPEG output, the image will be put on white background as it's default value for background parameter. You can always specify different value for background parameter along with opacity.

opacity=50

opacity=50&bg=ff0000

original

opacity=50

opacity=50&bg=ff0000

original

gamma

Apply a gamma correction by reducing the encoding (darken) pre-resize at a factor of 1/gamma then increasing the encoding (brighten) post-resize at a factor of gamma. This can improve the perceived brightness of a resized image in non-linear color spaces. JPEG and WebP input images will not take advantage of the shrink-on-load performance optimization when applying a gamma correction.

Valid value is between 1.0 and 3.0. Default is 2.2

sharp

Sharpen the image. This operation performs accurate sharpen of the L channel in the LAB color space. Valid values are between 0 and 100.

sharp=10

original

sharp=10

original

Text

These parameters are used when you want to overlay text over an image.

text

This parameter takes UTF-8 text strings as input. If this parameter is omitted, none of the other text related parameters will work.

If you want to write multiple lines, you can pass the \n character. For example, you can do text=simple\ntext.

text=example

original image

text=example

original image

text_top

This parameter specifies position of text in an image. It's given as number of pixel from top edge of image. Default value for this parameter is 0.

text_left

This parameter specifies position of text in an image. It's given as number of pixel from left edge of image. Default value for this parameter is 0.

text_font

This parameter specifies font-face to use while writing text over image. Default font is is sans-serif but you can specify any web-safe fonts to use here.

text_font_size

This parameter specifies font-size of the fonts to use in pixels. Default value is 48px.

text_line_height

This parameter specifies line height to use in pixels. Default value is 0 pixels.

text_align

Decides alignment of the text. Valid values are left, right and center. Default value is center.

text_color

You can provide any web-safe color name or a hex coded color name like '#2d2d2d'. Default value is black.

text_bg_color

This parameter can change background of the text. Default value is transparent.

text_padding

If you have specified text_bg_color other than transparent, this parameter will be able to put padding around text. Default value is 0 pixels.

text_position

Decides position of text on an image. Valid values are topleft, top, topright, right, bottomright, bottom, bottomleft, left and center.

text_rotate

Rotates text about its center. The rotation angle can be any angle between 0 and 360.

text_wrap

Automatically puts text in newline if it overflows the given width. Default value is false

text_width_pct

Maximum width of text overlay as percentage of output width. This parameter can be between 0 and 1. For example if output image width is 500 pixel and if text_width_pct is 0.1, the text overlay layer will be of maximum width of 50 pixel.

text_height_pct

Maximum height of text overlay as percentage of output height. This parameter can be between 0 and 1. For example if output image height is 500 pixel and if text_height_pct is 0.1, the text overlay layer will be of maximum height of 50 pixel.

Overlay

These parameters are used when you want to overlay one image over another.

overlay

This parameter takes image URL as its input. It overlays the image fetched from URL over the image being processed. The default option is to put the overlay at center. This can be modified with below parameters.

overlay_position=bottomleft

default position

overlay_position=bottomleft

default position

overlay_position

This parameter specifies position of image overlay.

Valid values are top, topleft, left, bottomleft, bottom, bottomright, right, topright and center.

overlay_top

Specifies overlay offset in number of pixels from top edge of image. This parameter overrides overlay_position.

overlay_left

Specifies overlay offset in number of pixels from left edge of image. This parameter overrides overlay_position.

overlay_tile

This boolean parameter repeats the overlay image like tiles over the image being processed. Default value is false.