API Reference

The Image API allows for real-time image manipulation, using query string parameters appended to image URLs. The following are a list of query parameters and their descriptions, which are available for use.

auto_fix

Automatically adjust the brightness and contrast of an image.

GET /image.jpg?auto_fix=true HTTP/1.1

auto_level

Automatically adjust the white balance level of an image.

GET /image.jpg?auto_level=true HTTP/1.1

autorotate

Disable image auto-rotation based on EXIF orientation tag. Default value is true.

GET /image.jpg?autorotate=false HTTP/1.1

blur

Apply a blur effect to an image (0 to 100).

GET /image.jpg?blur=100 HTTP/1.1

brightness

Adjust the brightness of an image (-1.0 to 1.0).

GET /image.jpg?brightness=0.5 HTTP/1.1

bucket

Override the awsAuthorization S3 bucket name. Imagizer will continue to use the configure keys or IAM role for authorization to the specified bucket.

GET /image.png?bucket=my.s3.bucket HTTP/1.1

TIP

The bucket parameter can be restricted by setting the bucketsAllowed configuration or disabled completely using the Allow Dynamic Origin configuration.

TIP

Specify the AWS region using the region parameter. In the absence of the region parameter, Imagizer will attempt to look up the region of the bucket.

cache_processed

Preprocess the image by applying all given parameters first before caching the origin image. All subsequent requests for the original image will return the modified cached version.

TIP

Works with POST Requests only.

Example: Perform redeye correction and auto_fix then cache the preprocessed image. The image will be cached at /image.jpg.

POST http://IMAGIZER_HOSTNAME/image.jpg HTTP/1.1
Content-Type: multipart/form-data;

file=@image.jpg
redeye=true
auto_fix=true
cache_processed=true

cache_queries

Pass an array of query strings to be preprocessed and cached.

TIP

Works with Post Requests and Async Requests only.

WARNING

Make sure to URL encode the cache_queries value.

Example: Preprocess and cache an image with a width of 200px, a width of 400px, and a height of 500px.
The following URLs will be processed and cached /image.jpg, /image.jpg?width=200, /image.jpg?width=400, and /image.jpg?height=500.

POST http://IMAGIZER_HOSTNAME/image.jpg HTTP/1.1
Content-Type: multipart/form-data;

file=@image.jpg
cache_queries[]=width%3D200
cache_queries[]=width%3D400
cache_queries[]=height%3D500

contrast

Adjust the contrast of an image (-1.0 to 1.0).

GET /image.jpg?contrast=1 HTTP/1.1

crop

Crop the image. There are eight different crop modes. See below for details on each.

TIP

Both the width and height parameters are required.

fit

Crop any excess image data outside the given width and height dimensions, after scaling has been completed. The crop will be centered on the image. The output image will match the dimensions precisely as given.

GET /image.jpg?width=400&height=300&crop=fit HTTP/1.1

top

Crop any excess image data outside the given width and height dimensions, after scaling has been completed. Crop from the top of the image down. The output image will match the dimensions precisely as given.

GET /image.jpg?width=400&height=300&crop=top HTTP/1.1

bottom

Crop any excess image data outside the given width and height dimensions, after scaling has been completed. Crop from the bottom of the image up. The output image will match the dimensions precisely as given.

GET /image.jpg?width=400&height=300&crop=bottom HTTP/1.1

pad

Scale an image to the given dimensions and fill the extra space with the given pad_color. The default pad_color is white.

GET /image.jpg?width=400&height=300&crop=pad HTTP/1.1

zoom

Zoom in on an image during rotation and crop out any extra white space.

TIP

Requires the rotate parameter.

GET /image.jpg?rotate=30&crop=zoom HTTP/1.1

face

Crop the image around any detected faces.

GET /image.jpg?crop=face HTTP/1.1

entropy

Detect and return the area of interest of the image, crop out insignificant areas.

GET /image.jpg?crop=entropy HTTP/1.1

custom

Return a region of the image. The region is specified by four numbers representing x-coordinate, y-coordinate, width, and height separated by commas.

GET /image.jpg?crop=160,435,300,300 HTTP/1.1

TIP

Use center in place of the x-coordinate or y-coordinate values to automatically detect the center of the image.

dpr

Set the device pixel ratio (DPR). The device pixel ratio is the ratio between physical pixels and logical pixels. For example, the device pixel ratio of an iPhone 7 is 2, because the physical resolution is double the logical resolution.

GET /image.jpg?dpr=2&width=300 HTTP/1.1

TIP

The width and/or height parameters are required.

fill_flash

Adjust the fill flash of an image (0 to 1).

GET /image.jpg?fill_flash=1 HTTP/1.1

filter

Apply various effects to the image. Imagizer offers 20 different filters.

GET /image.jpg?filter=2 HTTP/1.1

flatten

Remove the alpha channel (transparency) from the image. Removing the alpha channel reduces the resulting image size, and therefore, can improve image delivery times.

GET /image-trans.png?flatten=1 HTTP/1.1

TIP

Use the pad_color parameter to specify the background color.

flip

Flip the image horizontally. To flip vertically, first rotate the image by 180 degrees.

GET /image.jpg?flip=true HTTP/1.1

format

Set the output format of the image. Supported output formats are JPEG, PNG, and WEBP.

GET /image.png?format=webp HTTP/1.1

TIP

Not all browsers support WEBP. Please see the supported browser list here.

auto

Automatically format the image into the most optimized version supported by the client. The default format is WEBP. If the client does not support WEBP, the output format will be set to JPEG, or PNG if the image has transparency.

GET /image.png?format=auto HTTP/1.1

gamma

Adjust the gamma of an image (-1 to 1).

GET /image.jpg?gamma=1 HTTP/1.1

height

Scale the image by the given height. The aspect ratio of the source image will be used to calculate the width.

GET /image.jpg?height=200 HTTP/1.1

TIP

You may also use the h alias (h=200).s

TIP

If both the width and height are supplied, the image will be scaled to fit within the bounds of both dimensions while preserving the aspect ratio. Use the crop parameter to fit the image in the exact size specified.

highlight

Adjust the brightness of the image highlights (-1 to 1).

GET /image.jpg?highlights=1 HTTP/1.1

host_header

Override the Host header on the origin request to the image storage.

GET /img.jpg?host_header=images.example.com&origin=example.com HTTP/1.1

TIP

Works well with the origin parameter.

interlace

Set the output image as an interlaced (progressive) image.

GET /image.png?interlace=true HTTP/1.1

TIP

Supports PNG and JPEG only.

layers

Combine multiple images and text layers into one image. The layers parameter accepts a JSON array of layer objects.

GET /image.jpg?layers=<JSON> HTTP/1.1

WARNING

URL encoding of the JSON string is required for most clients.

Image layer object

Attribute Description
url A relative or absolute URL to the layer image.
pos The position of the layer. Possible values are left, right, top and bottom (default center).
scale Percentage to scale the layer to the source image. (default 100).
upscale When true allow upscaling of the layer image. (default: true).
x The X coordinate of the layer.
y The Y coordinate of the layer.
alpha Percentage of the transparency of the layer. (default 100).
offset The number of pixels to offset the layer from the given position (default 0).
angle Rotate the layer counterclockwise by given degrees (default 0).
required When true return an error when any individual layer fetch fails.

The JSON can look something like this:

[
   {
      "url":"/image-trans.png",
      "pos":"top|left",
      "scale":50
   },
   {
      "url":"/image-trans.png",
      "pos":"top|right",
      "scale":30
   },
   {
      "url":"/image-transparent.png",
      "pos":"bottom|left",
      "scale":20
   },
   {
      "url":"/image-transparent.png",
      "pos":"bottom|right",
      "scale":60
   }
]

Text layer object

In addition to Image Layer attributes, the Text Layer uses the following attributes:

Attribute Description
color The color of the text.
font The font family, style and size in one declaration. Font size will increase the text quality. Use scale to change the size.
text The text string to display.

Generates text in italic.

{"text":"Some text","font":"italic"}

Generates text in font size 20.

{"text":"Some text","font":"20"}

Generates text in Arial Bold.

{"text":"Some text","font":"Arial Bold"}

Combine all of the elements together.

{"text":"Some text","font":"Arial italic 20"}

The JSON string can look something like this:

[
    {
        "font":"arial bold 20",
        "text":"red",
        "color":"red",
        "pos":"top",
        "scale":30
    },
    {
        "font":"Times 20",
        "text":"green",
        "color":"green",
        "pos":"center",
        "scale":30
    },
    {
        "font":"italic 20",
        "text":"blue",
        "color":"blue",
        "pos":"bottom",
        "scale":30
    }
]

mark

Provides the location of the watermark image. May be a relative or absolute path.

GET /image.jpg?mark=<URL> HTTP/1.1

Watermarking can be globally set by using the ImageParamsAllowed config.

mark_alpha

Adjust the watermark alpha (0-100 where 0 means fully transparent and 100 is fully opaque).

GET /image.jpg?mark=<URL>&mark_alpha=true HTTP/1.1

TIP

Requires the mark parameter.

mark_scale

Scale the watermark to a percentage of the smallest dimension.

GET /image.jpg?mark=<URL>&mark_scale=60 HTTP/1.1

TIP

Requires the mark parameter.

mark_pos

Position the watermark within the source image. Possible values are top, right, bottom, and left; the default position is center.

GET /image.jpg?mark=<URL>&mark_pos=top HTTP/1.1

TIP

Requires the mark parameter.

mark_offset

Offset the watermark position by a given percentage.

GET /image.jpg?mark=/image-trans.png&mark_pos=top&mark_offset=40 HTTP/1.1

TIP

Requires the mark and mark_pos parameters.

mark_upscale

When true upscale the watermark image to better cover the image. The default value is false.

GET /image.jpg?mark=<URL>&mark_upscale=true HTTP/1.1

TIP

Requires the mark and mark_scale parameters.

meta

Return image metadata, including EXIF, in JSON format.

GET /image.png?meta=true HTTP/1.1

Example image metadata.

{  
   "fileSize":4428575,
   "width":4032,
   "height":3024,
   "fileType":"jpeg",
   "mimeType":"image/jpeg",
   "hasAlpha":false,
   "colorSpace":"srgb",
   "exif":{  
      "ApertureValue":"2159/1273",
      "BrightnessValue":"3497/314",
      "DateTime":"2017:04:02 16:08:21",
      "DateTimeDigitized":"2017:04:02 16:08:21",
      "DateTimeOriginal":"2017:04:02 16:08:21",
      "ExifImageLength":3024,
      "ExifImageWidth":4032,
      "ExifOffset":180,
      "ExifVersion":"48, 50, 50, 49",
      "ExposureBiasValue":"0/1",
      "ExposureMode":0,
      "ExposureProgram":2,
      "ExposureTime":"1/3690",
      "Flash":24,
      "FNumber":"9/5",
      "FocalLength":"399/100",
      "FocalLengthIn35mmFilm":28,
      "ISOSpeedRatings":20,
      "Make":"Apple",
      "MeteringMode":5,
      "Model":"iPhone 7",
      "Orientation":1,
      "ResolutionUnit":2,
      "SensingMethod":2,
      "ShutterSpeedValue":"29588/2497",
      "Software":10.3,
      "SubjectArea":"2015, 1511, 2217, 1330"
   },
   "faces":[],
   "server":{  
      "host":"ip-10-0-1-96",
      "ip":"10.0.1.96"
   }
}

face

Return facial coordinates along with meta data.

TIP

Requires the meta parameter.

GET /image.png?meta=true&face=true HTTP/1.1
{  
   "fileSize":215707,
   "width":1710,
   "height":1140,
   "fileType":"jpeg",
   "mimeType":"image/jpeg",
   "hasAlpha":false,
   "colorSpace":"srgb",
   "exif":{  
      "ColorSpace":65535,
      "ExifOffset":90,
      "ExifVersion":"48, 50, 50, 49",
      "Orientation":1,
      "Software":"Adobe Photoshop CS6 (Macintosh)"
   },
   "faces":[  
      {  
         "xPos":926,
         "yPos":524,
         "width":137,
         "height":137
      },
      {  
         "xPos":1012,
         "yPos":311,
         "width":140,
         "height":140
      },
      {  
         "xPos":516,
         "yPos":228,
         "width":200,
         "height":200
      },
      {  
         "xPos":1163,
         "yPos":148,
         "width":157,
         "height":157
      },
      {  
         "xPos":125,
         "yPos":362,
         "width":285,
         "height":285
      }
   ],
   "server":{  
      "host":"ip-10-0-1-81",
      "ip":"10.0.1.81"
   },
   "jpeg":{  
      "colorspace":2,
      "sampling-factor":"2x2,1x1,1x1"
   }
}

include_image_data

Include the image data, embedded in the metadata JSON object, as a base64 string.

TIP

Requires the meta parameter.

GET /image.jpg?meta=true&include_image_data=true HTTP/1.1
{  
   "fileSize":4428575,
   "width":4032,
   "height":3024,
   "fileType":"jpeg",
   "mimeType":"image/jpeg",
   "hasAlpha":false,
   "colorSpace":"srgb",
   "exif":{},
   "faces":[],
   "imageData":"...",
   "server":{  
      "host":"ip-10-0-1-96",
      "ip":"10.0.1.96"
   }
}

origin

Override the image storage backend server.

GET /image.png?origin=http://images.example.com HTTP/1.1

TIP

The origin parameter can be restricted by setting the Hostname Allowed config or disabled completely using the Allow Dynamic Origin config.

pad

Add padding around an image with a given pad_color as a hex string. The default color is white.

GET /image.jpg?pad=30 HTTP/1.1

TIP

See the crop parameter to automatically pad images.

pad_color

Set the color of the padding.

Some of the predefined values are: white, black, red, green, blue, yellow, magenta, and cyan. pad_color will also accept a hex string (e.g. fff, ffffff).

GET /image.jpg?pad=30&pad_color=555 HTTP/1.1

TIP

Requires the pad, crop or flatten parameters.

quality

Set the image quality. A lower setting will reduce the file size. Possible value ranges from 1 to 100. The quality of the initial image will be applied if the quality parameter is not explicitly set. If the initial image quality cannot be detected, a quality of 90 will be applied.

GET /image.jpg?quality=80 HTTP/1.1

recognition

WARNING

Recognition is currently available only on our cloud service from https://cloud.imagizer.com.

nsfw

Detect if an image contains nudity.

GET /image.png?recognition=nsfw HTTP/1.1

Example JSON response object:

{
   "nsfw": {
      "nudity": {
      "confidence": 98.48,
      "value": false
    }
  }
}

labels

Detect and return a list of labels describing the image. Recognition is able to identify thousands of objects such as vehicles, pets, or furniture, and provides a confidence score. Recognition also detects scenes within an image, such as a sunset or beach.

GET /image.png?recognition=labels HTTP/1.1

Example JSON response object:

{  
   "labels":[  
      {  
         "Name":"Animal",
         "Confidence":98.966850280762
      },
      {  
         "Name":"Horse",
         "Confidence":98.966850280762
      },
      {  
         "Name":"People",
         "Confidence":98.813423156738
      },
      {  
         "Name":"Human",
         "Confidence":98.749732971191
      },
      {  
         "Name":"Cafe",
         "Confidence":87.56616973877
      },
      {  
         "Name":"Vehicle",
         "Confidence":83.645690917969
      },
      {  
         "Name":"Bazaar",
         "Confidence":71.16487121582
      },
      {  
         "Name":"Market",
         "Confidence":71.16487121582
      },
      {  
         "Name":"Carriage",
         "Confidence":67.355987548828
      },
      {  
         "Name":"Horse Cart",
         "Confidence":67.355987548828
      }
   ]
}

redeye

Apply red-eye correction to any detected faces.

GET /image.jpg?redeye=true HTTP/1.1

region

Override the awsAuthorization S3 region.

GET /image.png?bucket=my.s3.bucket&region=us-west-1 HTTP/1.1

TIP

Requires the bucket parameter.

resolve

Provide a custom address for a specific host and port pair. Using this, you can make the origin image fetches using a specified address and prevent the otherwise normally resolved address to be used.

GET /image.png?origin=https://www.example.com&resolve=www.example.com:80:192.0.2.1 HTTP/1.1

TIP

Requires the origin parameter.

rotate

Rotate the image counterclockwise N degrees.

GET /image.jpg?rotate=90 HTTP/1.1

TIP

The image will be auto-rotated according to the origination flag in the image EXIF metadata first before applying the angle parameter.

saturation

Adjust the saturation of the image (-1 to 1).

GET /image.jpg?saturation=1 HTTP/1.1

shadow

Adjust the brightness of the image shadows (-1 to 1).

GET /image.jpg?shadow=1 HTTP/1.1

sharp_amount

Set the overall strength of the sharpening effect (1 to 100).

GET /image.jpg?sharp_amount=100 HTTP/1.1

sharp_radius

Set the size of the edges to enhance (1 to 100).

GET /image.jpg?sharp_amount=100&sharp_radius=100 HTTP/1.1

TIP

Requires the sharp_amount parameter.

source_url

Provide the full URL of the origin image including the hostname.

GET /?source_url=http://example.com/image1.jpg?width=100 HTTP/1.1

TIP

The source_url parameter can be disabled in config.

strip_exif

Strip all EXIF data from the image. In some cases you can significantly reduce an image file size by stripping EXIF data.

GET /image.png?strip_exif=true HTTP/1.1

trim

Trim the image to remove a border around the image. By default the border color white is trimmed. See trim_color to change the color.

GET /image.png?trim=color HTTP/1.1

trim_color

The color to trim when trim=color.

Some of the predefined values are: white, black, red, green, blue, yellow, magenta, and cyan. trim_color will also accept a hex string (e.g. fff, ffffff).

GET /image.png?trim=color&trim_color=555 HTTP/1.1

TIP

Requires the trim parameter.

vibrance

Adjust the vibrance of an image (-1 to 1).

GET /image.jpg?vibrance=1 HTTP/1.1

warmth

Adjust the warmth of an image (-1 to 1).

GET /image.jpg?warmth=1 HTTP/1.1

width

Scale the image by the given width. The aspect ratio of the source image will be used to calculate the height.

TIP

You may also use the w alias (ex: w=200).

GET /image.jpg?width=200 HTTP/1.1