API Reference
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.
The size parameters allow you to control all aspects of resizing, cropping, and the fit-to-crop behavior of your image.
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.
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.
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.
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
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. The color of background can be specified by background parameter.
Default mode is fit.
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 and center.
While other modes are self explanatory, let us describe first two crop modes.
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.
Extract a region from image. 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.
leftis zero-indexed offset from left edgetopis zero-indexed offset from top edgewidthof extracted imageheightof extracted image
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.
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.
These parameters allow changing image formats and different parameters related to those formats.
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 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.
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.
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.
Converting other formats to GIF or converting GIF to other format is also not supported. Please contact us if you need any such support.
Sets output quality of image. 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.
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.
These parameters allow changing colors of the image.
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.
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.
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.
Produces negative of image. You can use it as invert=true
Enhance output image contrast by stretching its luminance to cover the full dynamic range. Enable it by setting enhance=true
Perform most commonly used image operations.
Rotates the image as per number of degrees provided as 0, 90, 180 or 270
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.
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.
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
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
Sharpen the image. This operation performs accurate sharpen of the L channel in the LAB color space. Valid values are between 0 and 100.
These parameters are used when you want to overlay one image over another.
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.
This parameter specifies position of image overlay.
Valid values are top, topleft, left, bottomleft, bottom, bottomright, right, topright and center.
Specifies overlay offset in number of pixels from top edge of image. This parameter overrides overlay_position.
Specifies overlay offset in number of pixels from left edge of image. This parameter overrides overlay_position.
This boolean parameter repeats the overlay image like tiles over the image being processed. Default value is false.
postPurge Cache
/public/images/profile.jpg{success: true}
Example cURL request is given below.
curl -X POST -H "Content-Type: application/json" -d '{"access_token": "<your_api_key>", "path": "/public/images/profile.jpg"}' https://www.gumlet.com/api/purge/myimg
Any other response means the cache purge was unsuccessful and the server will return error message along with reason for the same.
Please note, the cache purge can be done for single image only. When you purge for an image, all the derivatives of that image are also purged from cache. We don't provide any API for clearing cache in bulk. If you need any support for such API, please contact us.
