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. You can fill excess space with fill parameter.
Default mode is fit.
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.
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. 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.
leftis zero-indexed offset from left edgetopis zero-indexed offset from top edgewidthof extracted imageheightof extracted image
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.
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 supports following input formats: JPEG, PNG, WebP, TIFF, PDF, GIF, SVG, RAW, HEIF.
Gumlet supports image output in following formats: JPEG, PNG, WebP, TIFF, GIF, SVG, RAW, HEIF.
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.
format=json will return information about the original image or PDF. For example: https://demo.gumlet.com/boat.jpeg?format=json​
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 files can be converted to image using Gumlet API. You need to use page parameter to extract given page from a PDF file.
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. 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.
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.
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.
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.
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.
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.
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.
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.
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.
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 text over an image.
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.
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.
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.
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.
This parameter specifies font-size of the fonts to use in pixels. Default value is 48px.
This parameter specifies line height to use in pixels. Default value is 0 pixels.
Decides alignment of the text. Valid values are left, right and center. Default value is center.
You can provide any web-safe color name or a hex coded color name like '#2d2d2d'. Default value is black.
This parameter can change background of the text. Default value is transparent.
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.
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.
