The Image Manager API

Image Manager transforms a website’s images by creating derivative images of various sizes and formats, and dynamically selecting the best image when requested by an end user.

The Image Manager API is an end-to-end solution to archive, manage, and deliver transformed images based on customer defined policies.

Getting Started

To get started with this API:

  • Contact your Akamai representative to enable Image Manager for your account.

  • Review the Get Started section on available tools.

  • Review the Authorize Your Client section to create your OPEN API access credentials and authorizations, making sure you enable both read and write access for this API grant.

  • Enable Image Manager on a property in Property Manager.

  • Retrieve the Luna-Token header generated once Image Manager is enabled on a property. This header, or API key, is required for all API calls and may look something like this: default-022335.

  • If you want to generate a custom Image Manager API token to apply a corresponding policy, use the imageManager behavior in PAPI.

  • Disable any behaviors that are incompatible with Image Manager, like adaptiveImageCompression and edgeImageConversion.

  • If using Front-End Optimization (FEO), disable the Optimize Images, Optimize CSS: Image Compression, and Optimize CSS: Use Web Resolution optimizations.

  • For on-demand transformations and testing, apply optional query string parameters to image requests.

Testing Images On-Demand

For on-demand transformations and testing, you can add the following optional query string parameters to a website’s image URLs:

Parameter Type Description
imformat Enumeration Requests a specific browser type. Supported browser types are chrome, ie, safari, generic. By default, Image Manager detects the browser and returns the appropriate image.
imwidth Integer Requests an image with a specific width.
impolicy String Request a specific image policy to be applied.

You can combine the impolicy, imwidth and imformat query parameters in a single request to perform multiple transformations. Here are some examples of using these query strings individually and grouped together:

  • www.example.com/assets/images/image001.jpg?imformat=safari: Returns the best image, in all format types (JPG, PNG, GIF, WEBP, JXR, and JP2) for the Safari browser.

  • www.example.com/assets/images/image001.jpg?imwidth=300: Returns an image the next size up from the 300px width defined in the query parameter. In this case, assuming the .auto policy is used, Image Manager returns the 320px image.

  • www.example.com/assets/images/image001.jpg?impolicy=watermark: Combines image001.jpg with an image the policy provides and returns a composite image.

  • www.example.com/assets/images/image001.jpg?impolicy=watermark&imwidth=300&imformat=safari: Returns an 320px image with the company logo added, and in the format best for Safari.

Image Manager Concepts

This section provides information about common Image Manager concepts.

  • Preset Transformations: Image Manager automatically transforms a website’s images by creating derivative images of various sizes and formats, and dynamically selecting the appropriate image when requested by an end user. You can create policies to modify how a website’s images are transformed.

  • On-Demand Transformations: Image Manager also supports on-demand transformations, using query string parameters. These parameters allow you to specify which derivative image to select, force the selection of a particular output format, or specify a different Image Manager policy.

  • API Key: This value, also known as the Luna-Token header, is required for all API calls. Each instance of the Image Manager behavior has a unique API key.

  • Policy: An Image Manager policy is a set of specifications applied to a derivative image. Policies may contain information about the image sizes to use for various screens, desired output formats (WebP, JPEG, and PNG), and image manipulations like watermarks. After a policy is applied to a derivative image, Image Manager transforms the image based on the information in that policy.

  • Default Policy: Image Manager automatically applies the default .auto policy unless a request includes a parameter indicating a valid custom policy name. It provides the baseline settings that determine how Image Manager generates derivatives. You can modify the .auto policy to select different image transformations, but you can’t delete it. The .auto policy is always active on both the staging and production networks. By default, the .auto policy has a quality setting of 85. The default image widths in pixels are 320, 640, 1024, 2048, and 5000.

  • Cache Key: Image Manager adds the policy name and version to an image’s cache key. Be aware that any policy modification will invalidate any images using the policy. For the default policy, this may cause an unexpected surge in traffic to your origin image content. You should test out any policy changes in the Akamai staging network. Once you complete testing, activate the policy in production.

  • Transformations: Each policy specifies a set of transformations to perform on a source image. Some transformations are only performed if certain conditions are met. See the Transformation object type for more information.

  • Variables: Within a policy, you can define a set of variables that supply the values to use with transformations.

  • Image Collections: Image, or media, collections let you organize images and other media assets into logical groups, which is useful for viewing these assets together on a website. A collection might represent a particular product on an e-commerce site or a set of images related to a news article.

  • Quality (default): Using a quality value from 1–100 resembles JPEG quality across output formats. The default is 85.

  • Perceptual Quality: Dynamically tunes the quality parameter for each image format based on the human-perceived quality of the output image. Using perceptualQuality instead of quality can result in better byte savings because many images can be encoded at a much lower quality without compromising perception of the image. In addition, certain images may need to be encoded at a slightly higher quality in order to maintain human-perceived quality.


Last modified: 12/12/2017