Learn more:

• Image Manager

Overview

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.

Who should use this API

The Image Manager API allows developers and architects to automate their entire imaging workflow to create, store, manage and deliver a rich image experience to every user, on any device, anywhere. To use this API, you should be familiar with HTTP requests and responses, and should read all sections and complete all tasks included in this Overview.

Get started

To get started with this API:

• Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

• To enable this API, choose the API service named Image Manager, and set the access level to READ-WRITE.

• Get help from the Akamai developer community and provide feedback. You can also contact your account representative for support. We want to hear from you!

Image Manager API concepts

This section provides a road map of all the conceptual objects you deal with when interacting with this API, and provides pointers to where you can learn more.

• Automatic Transformations: Image Manager automatically transformation 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. Policies can be created to modify how a website’s images are transformed (see Policies).

• On-Demand Transformations: Image Manager also supports on-demand transformations, using query string parameters that allow web developers to: specify which of the derivative images should be selected; force a particular output format to be selected or specify a different policy. For detailed information on query string parameters and examples, see the Resources section.

• Policies: Policies are used to create variations (size and formats) to deliver the best image for the application. For detailed information on Image Manager policies and examples, see the Resources section.

Resources

The Image Manager API allows you to create, list, and modify policies, and organize images.

API summary

Get a policy

Retrieve the policy definition by ID.

{
    "id": "watermark",
    "transformations": [
        {
            "transformation": "Composite",
            "image": { "url": "www.customer.com/watermark.png" },
            "xPosition": 0,
            "yPosition": 0,
            "gravity": "SouthWest"
        }
    ]
    "resolutions": {
        "interpolation": "Lanczos",
        "widths": [ 500, 300 ]
    },
    "outputs": {
        "defaults": { "quality": 90 }
    }
}

Add or modify a policy

Update the policy definition for a given ID.

If you want to activate a policy on the staging network, add -staging to the hostname used for the request. For example, you would use https://akab-xxxxx-xxxxxxxxxx.imaging-staging.akamaiapis.net/imaging/v0/policies/mobile-policy to activate a policy with an ID of mobile-policy on staging. To activate the same policy on production, you would use the following hostname: https://akab-xxxxx-xxxxxxxxxx.imaging.akamaiapis.net/imaging/v0/policies/mobile-policy.

{
    "resolutions": {
        "widths": [ 240, 120, 60 ]
    }
}

{
    "operationPerformed": "UPDATED",
    "description": "Policy {id} updated.",
    "id": "{id}"
}

Remove a policy

Remove a policy by ID.

{
    "operationPerformed": "DELETED",
    "description": "Policy {id} deleted.",
    "id": "{id}"
}

List policies

Retrieve a list of all policy IDs.

{
    "totalItems": 2,
    "itemKind": "POLICY",
    "items": [
        { "id": ".auto" },
        { "id": "watermark" }
    ]
}

Get policy history

Retrieve policy history by policy ID.

The returned object contains a list of log entries with the following members:

 {
    "itemKind": "POLICIESLOG",
    "items": [
        {
            "id": "testpolicy",
            "dateCreated": "2015-06-09 15:41:37+0000",
            "policy": "{\"id\":\"grayscale\",\"transformations\":[{\"transformation\":\"Grayscale\"}],\"resolutions\":{\"widths\":[500]},\"currentVersion\":1}",
            "action": "UPSERT",
            "user": "Akamai_Internal"
        }
    ],
    "totalItems": 1
}

List images to a limit

{
    "totalItems": 2,
    "itemKind": "IMAGE",
    "items": [
        {
            "id": "/images/image1.png",
            "url": "http://www.customer.com/images/image1.png",
            "policies": {
                ".auto": {
                    "sizes": {
                        "50": {
                          "date": "2016-03-22 13:05:59+0000",
                          "policyVersion": 1,
                          "status": "PASSED"
                        }
                    }
                }
            }
        },
        {
            "id": "/images/image2.png",
            "url": "http://www.customer.com/images/image2.png",
            "policies": {
                "watermark": {
                    "sizes": {
                        "200": {
                          "date": "2016-03-23 13:05:59+0000",
                          "policyVersion": 1,
                          "status": "PASSED"
                        }
                    }
                }
            }
        }
    ]
}

List images matching a URL

{
    "totalItems": 1,
    "itemKind": "IMAGE",
    "items": [
        {
            "id": "/images/image2.png",
            "url": "http://www.customer.com/images/image2.png",
            "policies": {
                "watermark": {
                    "sizes": {
                        "200": {
                          "date": "2016-03-23 13:05:59+0000",
                          "policyVersion": 1,
                          "status": "PASSED"
                        }
                    }
                }
            }
        }
    ]
}

Get an image

Return detailed information about a specific image.

{
    "id": "/house/image1.jpg",
    "url": "http://www.customer.com/house/image1.jpg",
    "policies": {
        ".auto": {
            "sizes": {
                "50": {
                  "date": "2016-03-22 13:05:59+0000",
                  "policyVersion": 1,
                  "status": "PASSED"
                }
            }
        }
    }
}

The object returned contains the following members:

The policies section lists the following members for each applied policy:

List a policy’s images

{
    "totalItems": 1,
    "itemKind": "IMAGE",
    "items": [
        {
            "id": "/images/image2.png",
            "url": "http://www.customer.com/images/image2.png",
            "policies": {
                "watermark": {
                    "sizes": {
                        "200": {
                          "date": "2016-03-23 13:05:59+0000",
                          "policyVersion": 1,
                          "status": "PASSED"
                        }
                    }
                }
            }
        }
    ]
}

Usage

This section provides an end-to-end guide of Image Manager’s main capabilities, demonstrating how to interact with each API interface:

• Image Manager API Workflow Integration
• Image Manager Resources
• Policies

Image Manager workflow

The following is the basic workflow for Image Manager.

1. Upload or provide a link to an original (hi-res) image, along with the destination URL (target path).

2. The image is transformed and stored in NetStorage, and is available at the target path specified on any hosts named in the property associated with the Luna-token header.

   NOTE: A Luna-Token header is the Image Manager API token provided in Property Manager when the Image Manager rule is enabled on a site. The Luna-Token is required on all API calls.

   Example:

   Luna-Token: default-022335

3. A link to the target path is added to the customer’s website for end users to access.

4. As this new image is requested by end users, applied policies automatically create all the sizes and formats required.

See Image Manager for detailed information about acquiring a Luna-token.

Image Manager API resources

See Image Manager API Concepts to learn more about how these objects relate to each other. For information on specific use cases, the following table summarizes all of the basic actions the API enables, along with their corresponding combinations of methods and endpoints.

Policy endpoints

Images endpoints

Query string parameter

For on-demand transformations, the following query string parameters can be added to image URLs on the website that specify how an image is returned, including:

• Requests for a specific browser type
• Requests for a specific image width (pixels)
• Requests for a policy change
• Combining query string parameters

Query string parameter examples

The following examples are variations of URLs you can form, and are not valid link targets.

• www.customer.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.customer.com/assets/images/image001.jpg?imwidth=300: Returns the 320px image, which is the next size up from 300px specified in the policy.

• www.customer.com/assets/images/image001.jpg?impolicy=watermark: Combines the two images and returns a composite image.

• www.customer.com/assets/images/image001.jpg?impolicy=watermark&imwidth=300&imformat=safari: Returns a composite of the image in format best for Safari, with the company logo, at 320px (closest width based on policy).

Policies

An Image Manager policy is a set of specifications (see Policy Specifications) that is applied to a derivative image. Policies can contain information about an image’s size for varying screens, output formats (WebP, JPEG, and PNG), and image opacity manipulation such a watermark. After a policy is applied to a derivative image, Image Manager uses the policy to transform the image. For examples of Image Manager policies, see Policy Examples.

NOTE: It is very important to understand that the policy name and version are contained in the cache key for images. Be aware that any policy modification will result in an invalidation of any images using the policy. For the default policy, this can mean an invalidation of all images. It is recommended to test out any policy changes in Akamai Staging, then once finalized, modify the policy in Production.

Automatic image transformations (real-time) policy

A real-time policy works directly on a customer’s origin. The output of a real-touch policy produces many images. If a custom policy is not specified, the default policy (.auto) is applied to the image.

Real-time default policy

The real-time default policy, .auto is automatically created, and is the policy applied to all images unless a specific policy is selected. The default policy can be modified to select different image transformations.

The .auto policy specifications are as follows:

• Quality is 80
• Widths in pixels are 5000, 2048, 1024, 640, and 320

Definition: {} (use all defaults)

NOTE: The .auto policy cannot be deleted.

Policy specifications

The following policy specifications are used to compose Real-Time policies. For detailed information about using policy operations, see the Resources section.

Quality vs. perceptual quality

The outputs object offers two ways to specify output quality: quality and perceptualQuality. The default is quality 80. When specifying outputs, use the following guidelines:

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

• Perceptual Quality: Perceptual quality tunes each image format’s quality parameter dynamically based on the human-perceived quality of the output image.

This can result in better byte savings (as compared to using regular quality) as 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.

If selected, the presets available for perceptual quality are as follows:

• high: Approximately 95 JPEG quality or higher. When perceived quality is the most important factor. This will result in minimal byte savings compared to other presets.

• mediumHigh: (default) Recommended setting for most cases. A good balance of quality and byte savings appropriate for displaying on the web. Approximately 85–95 JPEG quality.

• medium: Approximately 75–85 JPEG quality.

• mediumLow: Approximately 65–75 JPEG quality. When byte savings is the most important actor.

• low: Approximately 65 JPEG quality or lower. This setting is mainly for placeholders, image preloading, and so forth.

Policy examples

Example 1: Overrides the default widths to have only two sizes (120 and 60 pixels wide), default quality.

{
    "resolutions": {
        "widths": [ 120, 60 ]
    }
}

Example 2: Overrides the default widths and sets a specific output quality of 85.

{
    "resolutions": {
        "widths": [ 640, 320 ]
    },
    "outputs": {
        "defaults": { "quality": 85 }
    }
}

Example 3: Overrides the default widths and sets a specific perceptual quality.

{
    "resolutions": {
        "widths": [ 640, 320 ]
    },
    "outputs": {
        "defaults": {
            "perceptualQuality": "mediumHigh"
        }
    }
}

Example 4: Adds a watermark to the source image in the lower left hand corner, and uses default resolutions and outputs.

{
    "transformations": [
        {
            "transformation": "Composite",
            "image": { "url": "www.customer.com/watermark.png" },
            "xPosition": 0,
            "yPosition": 0,
            "gravity": "SouthWest"
        }
    ]
}

Image transformations

The common constructs for image transformations are as follows:

Gravity: A string to represent eight cardinal directions and a center. Use Gravity when describing placement or regions of an image, including:

• North
• NorthEast
• NorthWest
• South
• SouthEast
• SouthWest
• Center
• East
• West

Gravity Example:

{
    "transformation": "Crop",
    "width": 60,
    "height": 70,
    "gravity": "NorthWest"
}

Image: A JSON object with a URL that points to an image resource and a transformation object that should be applied to that image.

Image Example:

{
    "url": "imageUrl",                     // Required.
    "transformation": transformationObject // Optional.
}

Transformations: A JSON object that specifies parameters for that type of transformation. All transformation object JSONs follow a similar pattern.

Transformation Example:

{
    "transformation": "TransformationName",
    // ... Specific parameters for that type of transformation
}

BackgroundColor: Place a transparent image on a set background color. Color is specified in the typical CSS hexadecimal format.

BackgroundColor Example:

{
    "transformation": "BackgroundColor",
    "color": "#ff00ff"  // Required. The color of the background.
}

Composite: Places one image on top of another.

Composite Example:

{
    "transformation": "Composite",
    "image": imageObject,       // Required. Image to compose.
    "xPosition": 0,             // Optional. Default = 0. Integer x position.
    "yPosition": 0,             // Optional. Default = 0. Integer y position.
    "gravity": "gravityString", // Optional. Default = "NorthWest". Gravity string.
    "placement": "Over",        // Optional. Default = "Over". Whether to place "image"
                               //   "Over" or "Under" the image coming in to
                               //   the transformation.
    "scale": 0.5,               // Optional. Default is unset. If set, the specified image
                                // is scaled to this fraction of the base image.
    "scaleDimension": "width"  // Optional. Default = "width". The dimension of the base
                                // image to scale to. "width" or "height".
}

Compound: An ordered combination of other transformations to perform. It is used for representing a sequence of transformations as a single transformation.

Compound Example:

{
    "transformation": "Compound",
    "transformations": [array, of, transformation, objects] // Optional.
}

Crop: Crops an image.

Crop Example:

{
    "transformation": "Crop",
    "width": 100,          // Required. The width of the area to crop.
    "height": 100,         // Required. The height of the area to crop.
    "xPosition": 0,        // Optional. Default = 0. The X offset of where to crop.
    "yPosition": 0,        // Optional. Default = 0. The Y offset of where to crop.
    "gravity": "NorthWest" // Optional. Default = "NorthWest". Gravity for placement.
}

HSL: Simultaneously alters the hue, saturation, and lightness of an image. Hue is the number of degrees that colors are rotated around the color wheel. Saturation is a multiplier to increase or decrease color saturation. Lightness is a multiplier to increase or decrease the lightness of an image.

HSL Example:

{
    "transformation": "HSL",
    "hue": 0.0,        // Optional. Default = 0.0. Float of the number of degrees to rotate
                       // colours around the colour wheel.
    "saturation": 1.0, // Optional. Default = 1.0. Multiplier to adjust colour saturation.
    "lightness": 1.0   // Optional. Default = 1.0. Multiplier to adjust image lightness.
}

Grayscale: Restricts image color to shades of gray only. The available options of grayscale include:

• Rec601Luma
• Rec601Luminance
• Rec709Luma
• Rec709Luminance
• Brightness
• Lightness

Grayscale Example:

{
    "transformation": "Grayscale",
    "type": "grayscaleAlgorithm" // Optional. Advanced. Default = "Rec709Luma".
                                 // The algorithm used to transform colours to grays.
}

MaxColors: Reduces the number of unique colors in an image to a specified amount.

MaxColors Example:

{
    "transformation": "MaxColors",
    "colors": 256 // Required. Integer of colors to which the input image should be reduced.
}

Opacity: Affects the opacity (transparency) of an image. Use Opacity to make an image more transparent.

Opacity Example:

{
    "transformation": "Opacity",
    "opacity": 0.5 // Required. Float used to multiply pixel alpha values.
}

Resize: Resizes an image to a particular, absolute dimension. The following options are available using the type string:

• normal
• upsize
• downsize

The following aspect preservation modes are available with the aspect member:

• ignore
• fit (default)
• fill

It is required that either width or height aspect members, or both be present. If the requirement is not met, the aspect is ignored and the default aspect preservation mode (fit) is assumed; the image is resized with the missing dimension chosen to preserve the input image aspect.

Resize Example:

{
    "transformation": "Resize",
    "width": 100,     // It is required that one or both of "width"
    "height": 100,    // and "height" be present.
    "aspect": "fit",  // Optional. Default is "fit".
    "type": "normal" // Optional. Default is "normal".
}

Rotate: The “Rotate” transformation will rotate an image clockwise some arbitrary number of degrees. The resulting image will be resized to fit the entire rotated image. Empty areas will be filled with transparent pixels so it’s often useful or necessary to follow this transformation with a “BackgroundColor” transformation.

Rotate Example:

{
    "transformation": "Rotate",
    "degrees": 45.3 // Required. Number of degrees to rotate the image.
}

Scale: Resizes an image to particular dimensions relative to the input image.

Scale Example:

{
    "transformation": "Scale",
    "width": 0.5,  // Required. Float multiple of input width.
    "height": 0.5 // Required. Float multiple of input height.
}

Shear: The “Shear” transformation will shear an image along its X and/or Y axis. The resulting image will be resized to fit the entire sheared image. Empty areas will be filled with transparent pixels so it’s often useful or necessary to follow this transformation with a “BackgroundColor” transformation.

Shear Example:

{
    "transformation": "Shear",
    "xShear": 0.2, // It is required that one or both of "xShear" and "yShear" be present.
    "yShear": 0.1  //   The amount to shear along a particular axis.
}

Errors

The following shows a typical response when an error condition (4xx return code) occurs:

{
    "type": "",
    "title": "Validation Exception",
    "detail": "The value 'abcdefghijklmnopqrstuvwxyz0123456789' of property 'name' is too long. Max length is 30 characters.",
    "instance": "PUT - https://imaging.api.akamai.com/imaging/v0/policies/abcdefghijklmnopqrstuvwxyz0123456789",
    "httpStatus": 400
}