Maintain a catalog of source images, organize and transform the images, and make them available for delivery by the Akamai Intelligent Platform.

Learn more:

• Image Manager

• Reporting API

• Download this API’s RAML and JSON schema descriptors.

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.

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 Akamai 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:

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.

Resources

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

Follow this basic workflow to create a custom Image Manager policy:

1. Enable Image Manager on a property in Property Manager.

2. 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.

3. Determine which image transformations you want to include in the policy.

4. Run the List Policies operation to to retrieve a listing of all current Image Manager policies.

5. Review the list of policy IDs (policyId) returned.

6. Create a Policy object.

7. Run the Create or Modify a Policy operation, making sure to provide a new, unique policyId value. Otherwise you may overwrite an existing policy.

8. Activate the policy on the staging network, as described below.

9. Test the policy on the staging network.

10. Activate the policy on the production network.

Before going live with an Image Manager policy, activate the policy on the staging network. To activate a policy, add -staging to the hostname used for the request. For example, to activate a custom policy with an ID of mobile-policy on staging, you would use this URL:

https://akab-xxxxx-xxxxxxxxxx.imaging-staging.akamaiapis.net/imaging/v2/policies/mobile-policy

To activate the default policy on staging, use this hostname:

https://akab-xxxxx-xxxxxxxxxx.imaging-staging.akamaiapis.net/imaging/v2/policies/.auto

To activate the same policy on production once you’ve completed testing, you would use the regular hostname. For example:

https://akab-xxxxx-xxxxxxxxxx.imaging.akamaiapis.net/imaging/v2/policies/mobile-policy.

API Summary

Download the RAML descriptors for this API.

List policies

Retrieve a list of all policies using a specific instance of the Image Manager behavior.

Luna-Token: default-022335

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

Get a policy

Retrieve a specific policy associated with the selected API key.

Luna-Token: default-022335

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

Create or modify a policy

Create a policy or update the policy definition for a given ID. When creating a new policy, make sure the policyId doesn’t already exist.

Luna-Token: default-022335

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

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

Remove a policy

Delete a specific policy ID.

Luna-Token: default-022335

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

Get policy history

Retrieve policy history by policy ID. This operation returns the full state of the policy at various points in time. Time stamps are in ISO–8601 extended notation format.

Luna-Token: default-022335

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

List images

List a policy’s images.

Luna-Token: default-022335

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

Get an image

Retrieve a specific image.

Luna-Token: default-022335

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

List image collections

Lists all image collections, unless you set a limit.

{
    "itemKind": "IMAGECOLLECTION",
    "items": [
        {
            "id": "product-1",
            "user": "johndoe",
            "lastModifiedTimestamp": 1509418397284,
            "definition": {
                "version": 1,
                "items": [
                    {
                        "type": "image",
                        "url": "http://example.com/img1.jpg",
                        "mime": "image/jpeg"
                    },
                    {
                        "type": "image",
                        "url": "http://example.com/img2.jpg",
                        "mime": "image/jpeg"
                    }
                ]
            }
        },
        {
            "id": "product-2",
            "user": "janedoe",
            "lastModifiedTimestamp": 1509418397284,
            "definition": {
                "version": 1,
                "items": [
                    {
                        "type": "video",
                        "url": "http://example.com/vid1.mp4",
                        "mime": "video/mp4"
                    },
                    {
                        "type": "video",
                        "url": "http://example.com/vid2.webm",
                        "mime": "video/webm"
                    }
                ]
            }
        }
    ],
    "totalItems": 2
}

Create a new image collection

Create a new image collection.

{
    "operationPerformed": "CREATED",
    "description": "Image Collection SKU-26684355 was created",
    "id": "SKU-26684355"
}

{
    "operationPerformed": "CREATED",
    "description": "Image Collection SKU-26684355 was created",
    "id": "SKU-26684355"
}

Get an image collection

Returns the values for the image collection you specify.

{
    "id": "MyId123",
    "tags": [
        "red",
        "shoe"
    ],
    "definition": {
        "type": "Gallery",
        "items": [
            {
                "type": "AkaImage",
                "imageId": "/images/bag.front.jpg"
            },
            {
                "type": "AkaImage",
                "imageId": "/images/bag.side.jpg"
            },
            {
                "type": "AkaImage",
                "imageId": "/images/bag.back.jpg"
            }
        ]
    }
}

Update an image collection

Update an image collection.

{
    "operationPerformed": "UPDATED",
    "description": "Image Collection MyId123 was updated",
    "id": "MyId123"
}

{
    "operationPerformed": "UPDATED",
    "description": "Image Collection MyId123 was updated",
    "id": "MyId123"
}

Delete an image collection

Delete an image collection.

{
    "operationPerformed": "DELETED",
    "description": "Item was deleted",
    "id": "MyId123"
}

Get image collection history

Get a history of a specific image collection and all updates to it over the last three months.

{
    "itemKind": "IMAGECOLLECTIONHISTORY",
    "items": [
        {
            "id": "product-1",
            "user": "janedoe",
            "lastModifiedTimestamp": 1509418397300,
            "definition": {
                "version": 1,
                "items": [
                    {
                        "type": "image",
                        "url": "http://url.com/img1.jpg",
                        "mime": "image/jpeg"
                    },
                    {
                        "type": "image",
                        "url": "http://url.com/img2.jpg",
                        "mime": "image/jpeg"
                    }
                ]
            }
        },
        {
            "id": "product-1",
            "user": "johndoe",
            "lastModifiedTimestamp": 1509418397284,
            "definition": {
                "version": 1,
                "items": [
                    {
                        "type": "image",
                        "url": "http://url-bad.com/img1.jpg",
                        "mime": "image/jpeg"
                    },
                    {
                        "type": "image",
                        "url": "http://url-bad.com/img2.jpg",
                        "mime": "image/jpeg"
                    }
                ]
            }
        }
    ],
    "totalItems": 2
}

Data

This section shows you the data model for the Image Manager API. The sections are organized based the standard workflow through this API.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Policy

Allows you to create and manage your Image Manager policies. You use policies to create transformations, variations in image size and formats, to deliver the best image for the requesting application.

Download schema: policy.json

Sample GET response:

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

Policy members

Image

Collects information that describes an image.

Download schema: image.json

Sample GET response:

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

Image members

ImageCollection

Provides data about the types of items included in an image collection.

Download schema: image-collection-definition.json

Sample GET response:

{
    "totalItems": 2,
    "itemKind": "IMAGE",
    "items": [
        {
            "id": "/images/image1.png",
            "url": "http://www.example.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.example.comimages/image2.png",
            "policies": {
                "watermark": {
                    "sizes": {
                        "200": {
                            "date": "2016-03-23 13:05:59+0000",
                            "policyVersion": 1,
                            "status": "PASSED"
                        }
                    }
                }
            }
        }
    ]
}

ImageCollection members

Video

Information about a video that’s included in the collection.

Download schema: video.json

Video members

Spin360

Information about a 360 degree image spin that’s included in the collection.

Download schema: spin-360.json

Spin360 members

History

Provides date, user, and version information for your Image Manager policies.

Download schema: get-policy-history.json

Sample GET response:

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

History members

Acknowledgement

The type of operation performed on an Image Manager resource.

Download schema: operation-performed.json

Sample DELETE response:

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

Acknowledgement members

Transformation

Transformations are tools for modifying images. You can include many transformations in a policy. Transformations can be any of the following specialized object types:

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

• Blur: Applies a Gaussian blur to the image.

• Composite: Applies another image to the image you are transforming (called the source image), either as an overlay or an underlay. The image that is underneath is visible in areas that are beyond the edges of the top image or that are less than 100% opaque. A common use of an overlay composite is to add a watermark.

• Compound: An ordered combination of transformations to perform. Use to represent a sequence of transformations as a single transformation.

• Crop: Cuts the image down to an area you specify. Use this transformation to describe the size and position of a box indicating the portion of the image to preserve.

• FitAndFill: Uses aspect fitting to resize an image to the exact dimensions specified. This transformation then uses aspect fill on any remaining areas of the image.

• Grayscale: Renders the image in shades of black, white, and gray.

• Hsl: Simultaneously alters the hue, saturation, and lightness (HSL) 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.

• MaxColors: Sets the maximum number of color in the image’s palette. Reducing the number of colors in an image can help reduce file size.

• Opacity: Changes the opacity (transparency) of an image. Use Opacity to make an image more transparent. Values below 1.0 increase transparency; 0.0 is invisible. For images that have some transparency, values above 1.0 increase the opacity of the transparent portions.

• Resize: Resizes an image to a particular, absolute dimension. If you don’t enter a width or a height, the image is resized with the fit aspect preservation mode, which selects a value for the missing dimension that preserves the image’s aspect.

• Rotate: Rotates the image around its center by indicating the degrees of rotation. Positive values rotate clockwise; negative values rotate counter-clockwise.

• Scale: Changes the image size relative to the starting size, expressed as a percentage of the width and height. You can scale width and height independently.

• Trim: Automatically crops uniform backgrounds from the edges of an image.

• UnsharpMask: Generates a sharper resulting image by creating a negative image mask of the original image, then combining that mask with the original image.

These transformations operate conditionally based on qualities of the source image:

• IfDimension: Chooses a transformation depending on the dimensions of the source image. You need to select a dimension for comparison, which is either width and height or both.

• IfOrientation: Chooses a transformation depending on the orientation of the source image.

Many of these object types allow you to specify a Variable object as an alternative to a string or number value. These correspond to the name of any variable defined within the policy, and optionally passed in as image URL query parameters.

BackgroundColor

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

Download schema: background-color.json

Sample that changes background color:

{
    "transformation": "BackgroundColor",
    "color": "#ff00ff"
}

BackgroundColor members

Blur

Applies a Gaussian blur to the image.

Download schema: blur.json

Blur members

Composite

Applies another image to the image you are transforming (called the source image), either as an overlay or an underlay. The image that is underneath is visible in areas that are beyond the edges of the top image or that are less than 100% opaque. A common use of an overlay composite is to add a watermark.

Download schema: composite.json

Sample that places one image on top of another:

{
    "transformation": "Composite",
    "image": [
        {
            "id": "/house/image1.jpg",
            "url": "http://www.example.com/house/image1.jpg",
            "policies": {
                ".auto": {
                    "sizes": {
                        "50": {
                            "date": "2016-03-22 13:05:59+0000",
                            "policyVersion": 1,
                            "status": "PASSED"
                        }
                    }
                }
            }
        }
    ],
    "xPosition": 0,
    "yPosition": 0,
    "gravity": "NorthWest",
    "placement": "Over",
    "scale": 0.5,
    "scaleDimension": "width"
}

Composite members

Compound

An ordered combination of transformations to perform. Use to represent a sequence of transformations as a single transformation.

Download schema: compound.json

Sample that combines a sequence of transformations into a single transformation:

{
    "transformation": "Compound",
    "transformations": [
        {
            "color": "#ff00ff",
            "transformation": "BackgroundColor"
        },
        {
            "colours": 256,
            "transformation": "MaxColors"
        }
    ]
}

Compound members

Crop

Crops an image.

Download schema: crop.json

Sample that crops an image:

{
    "transformation": "Crop",
    "width": 100,
    "height": 100,
    "xPosition": 0,
    "yPosition": 0,
    "gravity": "NorthWest"
}

Crop members

FitAndFill

Use aspect fitting to resize an image to the exact dimensions specified. This transformation then uses aspect fill on any remaining areas of the image.

Download schema: fit-and-fill.json

FitAndFill members

Grayscale

Restricts image color to shades of gray only.

Download schema: grayscale.json

Sample that restricts image color to shades of gray only:

{
    "transformation": "Grayscale",
    "type": "Rec601Luma"
}

Grayscale members

Hsl

Simultaneously alters the hue, saturation, and lightness (HSL) 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.

Download schema: hsl.json

Sample that alters the hue, saturation, and lightness of an image:

{
    "transformation": "HSL",
    "hue": 0.0,
    "saturation": 1.0,
    "lightness": 1.0
}

Hsl members

MaxColors

Set the maximum number of colors in the image’s palette. Reducing the number of colors in an image can help to reduce file size.

Download schema: max-colors.json

Sample that reduces the number of unique colors in an image:

{
    "transformation": "MaxColors",
    "colors": 256
}

MaxColors members

Opacity

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

Download schema: opacity.json

Sample that affects the transparency of an image:

{
    "transformation": "Opacity",
    "opacity": 0.5
}

Opacity members

Resize

Resizes an image to a particular, absolute dimension. If you don’t enter a width or a height, the image is resized with the fit aspect preservation mode, which selects a value for the missing dimension that preserves the image’s aspect.

Download schema: resize.json

Sample that resizes an image to a particular, absolute dimension:

{
    "transformation": "Resize",
    "width": 100,
    "height": 100,
    "aspect": "fit",
    "type": "normal"
}

Resize members

Rotate

Rotate the image around its center by indicating the degrees of rotation.

Download schema: rotate.json

Sample that rotates an image clockwise some arbitrary number of degrees:

{
    "transformation": "Rotate",
    "degrees": 45.3
}

Rotate members

Scale

Change the image’s size to different dimensions relative to its starting size.

Download schema: scale.json

Sample that resizes an image to particular dimensions relative to the input image:

{
    "transformation": "Scale",
    "width": 0.5,
    "height": 0.5
}

Scale members

Shear

Slants an image into a parallelogram, as a percent of starting dimension as represented in decimal format. At least one axis property is required. Shearing results in an image that’s the same size as the original. Empty areas are filled with transparent pixels so it’s often useful or necessary to follow this transformation with a backgroundColor transformation.

Download schema: shear.json

Sample that slants an image into a parallelogram, as a portion of starting dimension:

{
    "transformation": "Shear",
    "xShear": 0.2,
    "yShear": 0.1
}

Shear members

Trim

Automatically crops uniform backgrounds from the edges of an image.

Download schema: trim.json

Trim members

UnsharpMask

Generates a sharper resulting image by creating a negative image mask of the original image, then combining that mask with the original image.

Download schema: unsharp-mask.json

UnsharpMask members

IfDimension

Chooses a transformation depending on the dimensions of the source image. You need to select a dimension for comparison, which is either width and height or both.

Download schema: if-dimension.json

IfDimension members

IfOrientation

Chooses a transformation depending on the orientation of the source image.

Download schema: if-orientation.json

IfOrientation members

Variable

References the name of a variable defined by the policy. Use this object to substitute preset values within transformations, or to pass in values dynamically using image URL query parameters.

Download schema: variable.json

Variable members

Errors

This section shows you how to handle various kinds of errors the Image Manager API generates, and lists the range of HTTP status codes along with their likely causes.

The format of error response objects follows the JSON Problem Details standard, and use the application/api-problem+json content type.

The following example shows an error response for a request processed by Image Manager:

{
    "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/v2/policies/abcdefghijklmnopqrstuvwxyz0123456789",
    "httpStatus": 400
}

HTTP status codes

The API responds with the following set of HTTP status codes for both success and failure scenarios.

Last modified: 7/2/2018