API Reference

Color Operations

These parameters allow changing colors of the image.

colorspace (colourspace)(cs)

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, hsv, rgb16, grey16, cmyk, labq, cmc, lch, labs 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=10sat=-50hue=90tint=blue
bri=10sat=50hue=90tint=blue

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=trueoriginal
greyscale=trueoriginal

invert

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

invert=trueoriginal
invert=trueoriginal

enhance

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

colors

Number of colors to output when using palette API to extract color palettes. Default value of this parameter is 6.

palette

The palette parameter extracts a palette of color values from an image and returns them in the specified format. Palette extraction occurs after image processing, so applying any adjustments and cropping effects will change the color palette response. Valid values are css and json.

This parameter generally outputs two palette sets—both choose colors based on their dominance in the image. The default set is strictly algorithmic, based on frequency of the color in the image, and is always available. The "dominance" set also weights frequency, but selects the colors to provide a more coordinated palette across the image's colorspace and names the colors by their relative values, like Vibrant.js does.

The default palette set defaults to six colors, but can be overridden with the colors parameter. Valid values are in the range 0 – 16 The dominance palette set provides up to six named colors:

  • Vibrant
  • Vibrant Dark
  • Vibrant Light
  • Muted
  • Muted Dark
  • Muted Light

The dominance palette will vary (and may not be generated) depending on whether the image's colors meet the criteria for each name. It may return all six colors, a portion, or none, although most images will return a complete set.

palette=css

The response to the image request will be a CSS file with the text/css MIME type. Class pairs have a "foreground" and a "background" defintion. The foreground class has a color property defined, while the background class has a background-color property defined. The CSS output also includes white and black, to make displaying a colorPalette-swatch set easier.

If prefix is also set, its value will replace "image" in the CSS class names in the output CSS file. For example:

<link rel="stylesheet" href="https://demo.gumlet.io/lemon.jpeg?mode=fit&width=400&height=400&palette=css&prefix=lemon">

Above link tag gives below output.

.lemon-fg-1 { color:#cda156 !important; }
.lemon-bg-1 { background-color:#cda156 !important; }
.lemon-fg-2 { color:#1c3738 !important; }
.lemon-bg-2 { background-color:#1c3738 !important; }
.lemon-fg-3 { color:#85674a !important; }
.lemon-bg-3 { background-color:#85674a !important; }
.lemon-fg-4 { color:#94a194 !important; }
.lemon-bg-4 { background-color:#94a194 !important; }
.lemon-fg-5 { color:#98949c !important; }
.lemon-bg-5 { background-color:#98949c !important; }
.lemon-fg-6 { color:#ac5c3c !important; }
.lemon-bg-6 { background-color:#ac5c3c !important; }
.lemon-fg-ex-1 { color:#ffffff !important; }
.lemon-bg-ex-1 { background-color:#ffffff !important; }
.lemon-fg-ex-2 { color:#000000 !important; }
.lemon-bg-ex-2 { background-color:#000000 !important; }
.lemon-fg-vibrant { color:#c08041 !important; }
.lemon-bg-vibrant { background-color:#c08041 !important; }
.lemon-fg-vibrant-light { color:#dabf55 !important; }
.lemon-bg-vibrant-light { background-color:#dabf55 !important; }
.lemon-fg-vibrant-dark { color:#255248 !important; }
.lemon-bg-vibrant-dark { background-color:#255248 !important; }
.lemon-fg-muted { color:#82674a !important; }
.lemon-bg-muted { background-color:#82674a !important; }
.lemon-fg-muted-light { color:#c8b3b5 !important; }
.lemon-bg-muted-light { background-color:#c8b3b5 !important; }
.lemon-fg-muted-dark { color:#27424c !important; }
.lemon-bg-muted-dark { background-color:#27424c !important; }

palette=json

The response will be a JSON object with the application/json MIME type. The JSON object has three top-level properties: a floating-point average_luminance value, a colors array of colors for the original palette, and a dominant_colors array that represents the Vibrant.js-style values.

Each color in the colors and dominant_colors arrays contains a hash describing its red, green, and blue components (expressed as floating point numbers between 0.0 and 1.0), and a hex value.

If palette is set to json, the prefix parameter is ignored.

Here is the JSON payload from the tree lemon image used above:

{
   "average_luminance":0.5,
   "colors":[
      {
         "red":0.803922,
         "hex":"#cda156",
         "blue":0.337255,
         "green":0.631373
      },
      {
         "red":0.109804,
         "hex":"#1c3738",
         "blue":0.219608,
         "green":0.215686
      },
      {
         "red":0.521569,
         "hex":"#85674a",
         "blue":0.290196,
         "green":0.403922
      },
      {
         "red":0.580392,
         "hex":"#94a194",
         "blue":0.580392,
         "green":0.631373
      },
      {
         "red":0.596078,
         "hex":"#98949c",
         "blue":0.611765,
         "green":0.580392
      },
      {
         "red":0.67451,
         "hex":"#ac5c3c",
         "blue":0.235294,
         "green":0.360784
      }
   ],
   "dominant_colors":{
      "vibrant":{
         "red":0.752941,
         "hex":"#c08041",
         "blue":0.254902,
         "green":0.501961
      },
      "vibrant_light":{
         "red":0.854902,
         "hex":"#dabf55",
         "blue":0.333333,
         "green":0.74902
      },
      "vibrant_dark":{
         "red":0.145098,
         "hex":"#255248",
         "blue":0.282353,
         "green":0.321569
      },
      "muted":{
         "red":0.509804,
         "hex":"#82674a",
         "blue":0.290196,
         "green":0.403922
      },
      "muted_light":{
         "red":0.784314,
         "hex":"#c8b3b5",
         "blue":0.709804,
         "green":0.701961
      },
      "muted_dark":{
         "red":0.152941,
         "hex":"#27424c",
         "blue":0.298039,
         "green":0.258824
      }
   }
}