Content

Optimize and transform images with Akamai

The image manager is commonly used when you want dynamic image sizing for different page views (e.g., mobile device types), the same picture to display in different sizes (e.g., thumbnails and enlargements), or to convert image formats (e.g., converting a TIFF to a JPEG).

For example, you could use image manager when you want to display images originating from your desktop site on your mobile site. For desktop sites, images are generally designed for fast connections and large browser display areas. Image manager allows you to transform these images so they work better with the layout and performance considerations of all your client devices, but without the need to create, maintain, store, and serve multiple versions of the same images. Customers subscribing to image manager can perform image manipulations as clients request the images. Operations include resizing, cropping, and transcoding.

Image manager can be used with any of these image formats:

  • GIF
  • JPEG
  • PNG
  • TIFF

Use the image manager

To use the image manager, you must append the image manager commands to either an image’s URL or HTML tag.
Examples:
URL

HTML tag

Common elements of the Image Manager

The image manager reads commands sequentially from left to right, so you must ensure the order of your commands for accurate results.

Use the following table to help determine the correct order of your commands:

Command Type
Image Manager Commands
Usage Considerations

Measurement

Define custom units in terms of pixels:

unit

The definitions you create with the unit command affect only the commands that follow it. Therefore, it is recommended that the unit command be the first command (if used).

Pixels are the default unit of measurement. To use a different unit of measurement, you must define it with the unit command. The unit command defines a new measurement unit in terms of existing units.

unit=<sizeunit>::<sizecurrent>

Operations

Manipulating an image:

box

composite

composite-to

crop

downsize

fit

resize

The order of operations commands is important.

If you use the same operations command twice, each command is performed based on its order of appearance. As image manager reads query strings sequentially from left to right, the left-most command would be performed first. The second command would then be performed based on the output of the first command.

Output

Change image format characteristics:

background-color

output-format

output-quality

It is recommended that output commands follow operations commands.

If you repeat an output command, only the right-most command is performed.

Some of the image manager commands require values for location, dimensions, or both.

  • A location is given as a pair of x- and y-coordinates
  • Dimensions are given as a ratio of width to height
  • A rectangle is an example of a combination of dimensions and a location

Use the following table to determine which image manager commands use which values:

Command
Location
Dimensions

box

Required

Required

composite

Required

Required

composite-to

Required

Optional

crop

Required

Required

downsize

n/a

Required

fit

n/a

Required

resize

n/a

Required

Location

Basic syntax: <x>,<y>
The <x> and <y> parameters correspond to the image’s x- and y-axis. They are used in the box, crop, composite, and composite-to commands:

  • In the box command, this is the upper-left corner of the box being drawn on the base image.
  • In the crop command, this is the upper-left corner of the region being cropped.
  • In the composite and composite-to commands, this is the upper-left corner of the image being superimposed on the base image.

Use the following table to see details about the ways to describe location:
Basic Values

Value
Description
Example

<integer>

A coordinate on the x- or y-axis given in pixels. Equivalent to <integer>px.

100, 120

<integer><unit>

A coordinate on the x- or y-axis given in units you’ve defined with the unit command.

3cm, 4cm

w

A variable that represents the width of the image. Can be used with modifiers to indicate a position along the x-axis.

See Combination (Rectangle)

h

A variable that represents the height of the image. Can be used with modifiers to indicate a position along the y-axis. See Combination (Rectangle)

See Combination (Rectangle)

Modifiers

Value
Description
Example

<decimal>x

Use in front of a basic coordinate value to multiply it by the given decimal value. If using a decimal value that is less than 1, enter a 0 before the decimal point.

0.1wv,0.25xh

2x90px,3x1cm

<integer>/<integer>x

Use in front of a basic coordinate value to multiply it by the given fractional value.

1/10xw,1/4xh

1/10x90px,0.25xh

Alignment Values

Value
Description
Example

*

center

Use in place of the x- or y-axis value to align the center of the rectangle or superimposed image with the center of the base image.

*,0.25xh

center,0.25xh

left

right

Use in place of the x-axis value to align the left or right edge of the rectangle or superimposed image flush with the corresponding edge of the base image.

left,0.25xh

right,10

top

bottom

Use in place of the y-axis value to align the top or bottom edge of the rectangle or superimposed image flush with the corresponding edge of the base image.

0.25xw,top

10,bottom

left[<offset>]

right[<offset>]

top[<offset>]

bottom[<offset>]

Behaves similarly to the other alignment values but shifts the rectangle or superimposed image away from the edge by the offset amount specified.

left[0.1xw],0.25xh

right[1/10xw],10

0.25xw,top[10]

10,bottom[1/10xh]

Dimension

Basic syntax: <width>:<height>
Dimensions can be used in the box, crop, downsize, fit, and resize commands. In the composite and composite-to commands, dimensions are used when indicating placement as a rectangle.

Use the following table to see the available options for dimension values:
Basic Values

Value
Description
Example

<integer>

A position on the x- or y-axis given in pixels. Equivalent to <integer>px.

100:120

<integer><unit>

A position on the x- or y-axis given in units you’ve defined with the unit command.

3cm:4cm

w

A variable that represents width. Use alone to indicate that the width should not be altered. Use with a modifier to scale the width.

w:300

h

A variable that represents height. Use alone to indicate that the height should not be altered. Use with a modifier to scale the height.

300:h

w:h

Modifiers

Value
Description
Example

<decimal>x

Use in front of a basic dimension value to multiply it by the given decimal value. If using a decimal value that is less than 1, enter a 0 before the decimal point.

0.25xw:0.25xh

1.2xw:1.3xh

<integer>/<integer>x

Use in front of a basic dimension value to multiply it by the given fractional value.

1/4xw:1/4xh

1/10xw:1/4xh

Variable that preserves aspect ratio

Value
Description
Example

*

Use in place of a dimension value to preserve the aspect ratio relative to the other dimension value.

*:120

2in:*

0.25xw:*

Combination (Rectangles)

Basic syntax: <width>:<height>;<x>,<y> (Where <width> and <height> are dimension parameters, and <x> and <y> are location parameters)
A rectangle value is required for the box and crop commands and is optional for the composite and composite-to commands.

  • In the crop command, the dimensions indicate the size of the area of the image you want to keep. The location indicates the upper-left corner of the area you want to keep.
  • In the composite command, the dimensions indicate the size of the image you want to superimpose on the base image. The location indicates the upper-left corner of the image being superimposed on the base image.

Available commands with the image manager

The following table shows the available commands with the Akamai image manager:

Command
Description
Syntax
Values

background-color

Sets the background color for transparent portions of images.

background-color=<color>

HTML color

Hex color

box

Draws a rectangle on the image.

box=<rectangle>|color[<color>]|
fill|stroke[<linewidth>]

If you omit an optional value, also omit the associated pipe (|) symbol.

rectangle

color

fill

linewidth

composite

composite-to

Combines two images. Commonly used to apply a watermark to an image.

The difference between these commands is which of the two images, the one in the Image Manager command or the one in the base URL or image tag, is superimposed:

  • composite superimoses the image in the Image Manager command to the base image

  • composite-to superimposes the base image onto the image in the Image Manager command

composite=<placement>|<image-URL>

composite=<opacity>|<placement>|<image-URL>

composite-to=<placement>|<image-URL>

composite-to=<opacity>|<placement>|<image-URL>

opacity

placement

image URL: With composite, the image URL is the URL of the top image. With composite-to, the image URL is the URL of the bottom image.

crop

Cuts out a section of an image

crop=<dimensions>;<location>

dimensions

location

downsize

Scales, or resizes, the image to the dimensions you specify. However, if you enter a dimension that is larger than the original, the image’s dimension will not be changed.

downsize=<width>:<height>

dimensions

fit

Resize an image into the specified dimensions while maintaining aspect ratio.

fit=inside|<dimensions>

fit=around|<dimensions>

inside

around

dimensions

interpolation

Indicates which algorithm to use when changing the size of an image.

interpolation=<algorithm>

bilinear

bicubic

nearest-neighbor

progressive-bilinear

progressive-bicubic

lanczos-none

output-format

Renders the image in the specified format.

The output formats available are GIF, JPEG, and PNG.

output-format=<image-format>

gif or image/gif

jpeg, image/jpeg, jpg, or image/jpg

png or image/png

webp or image/webp

jp2 or image/jpeg2000

jpegxr or image/vnd.ms-photo

output-quality

For JPEG output, sets the desired quality of the output image.

output-quality=<quality-value>

integer from 1 to 100

resize

Scales, or resizes, the image to the dimensions you specify.

resize=<width>:<height>

dimensions

unit

Defines a new measurement unit in terms of existing units.

unit=<sizeunit>::<sizecurrent>

sizeunit is one or more integers followed by letters representing the unit of measurement

sizecurrent is either pixels (default) or a unit of measurement you previously defined in your query string

Expected outcome

You are able to manipulate images through Akamai API commands appended to an image’s URL.

Updated 5 months ago


Optimize and transform images with Akamai


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.