Image Manager API v2

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

Learn more:


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:

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.

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.

Operation Method Endpoint
Policies  
List policies GET /imaging/v2/policies
Get a policy GET /imaging/v2/policies/{policyId}
Create or modify a policy PUT /imaging/v2/policies/{policyId}
Remove a policy DELETE /imaging/v2/policies/{policyId}
Get policy history GET /imaging/v2/policies/history/{policyId}
Images  
List images GET /imaging/v0/images/{?limit,url,policyId}
Get an image GET /imaging/v0/images/{imageId}
Image Collections  
List image collections GET /imaging/v0/imagecollections/{?limit}
Create a new image collection PUT /imaging/v0/imagecollections/
Get an image collection GET /imaging/v0/imagecollections/{imageCollectionId}
Update an image collection POST /imaging/v0/imagecollections/{imageCollectionId}
Delete an image collection DELETE /imaging/v0/imagecollections/{imageCollectionId}
Get image collection history GET /imaging/v0/imagecollections/{imageCollectionId}/history{?limit}

List policies

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

GET /imaging/v2/policies

Headers:

Luna-Token: default-022335

Status 200 application/json

Response Body:

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

Get a policy

Retrieve a specific policy associated with the selected API key.

GET /imaging/v2/policies/{policyId}

Sample: /imaging/v2/policies/thumbnail_policy

Headers:

Luna-Token: default-022335
Parameter Type Sample Description
URL parameters
policyId String thumbnail_policy Unique identifier for a policy.

Status 200 application/json

Response Body:

{
    "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
    }
}
  1. Run the List Policies operation and store the policy ID (id).

  2. Make a GET request to /imaging/v2/policies/{policyId}.

The response includes the Policy object.

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.

PUT /imaging/v2/policies/{policyId}

Sample: /imaging/v2/policies/thumbnail_policy

Headers:

Luna-Token: default-022335

Content-Type: application/json

Request Body:

{
    "breakpoints": {
        "widths": [
            240,
            120,
            60
        ]
    }
}
Parameter Type Sample Description
URL parameters
policyId String thumbnail_policy Unique identifier for a policy.

Status 200 application/json

Response Body:

{
    "operationPerformed": "UPDATED",
    "description": "Policy thumbnail_policy updated.",
    "id": "thumbnail_policy"
}
  1. Run the List Policies operation and store the policyId.

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

  3. Create a Policy object.

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

The response includes the Policy object.

Remove a policy

Delete a specific policy ID.

DELETE /imaging/v2/policies/{policyId}

Sample: /imaging/v2/policies/thumbnail_policy

Headers:

Luna-Token: default-022335
Parameter Type Sample Description
URL parameters
policyId String thumbnail_policy Unique identifier for a policy.

Status 200 application/json

Response Body:

{
    "operationPerformed": "DELETED",
    "description": "Policy thumbnail_policy deleted.",
    "id": "thumbnail_policy"
}
  1. Run the List Policies operation and store the policy ID (id).

  2. Make a DELETE request to /imaging/v2/policies/{policyId}.

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.

GET /imaging/v2/policies/history/{policyId}

Sample: /imaging/v2/policies/history/thumbnail_policy

Headers:

Luna-Token: default-022335
Parameter Type Sample Description
URL parameters
policyId String thumbnail_policy Unique identifier for a policy.

Status 200 application/json

Response Body:

{
    "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
}
  1. Run the List Policies operation and store the policy ID (id).

  2. Make a GET request to /imaging/v2/policies/history/{policyId}.

The response includes the History object.

List images

List a policy’s images.

GET /imaging/v0/images/{?limit,url,policyId}

Sample: /imaging/v0/images/?limit=2&url=http%3A//www.example.com/image2.png&policyId=thumbnail_policy

Headers:

Luna-Token: default-022335
Parameter Type Sample Description
Optional query parameters
limit Integer 2 Specifies maximum number images to retrieve.
policyId String thumbnail_policy The policy to list images for.
url String http://www.example.com/image2.png URL to search for.

Status 200 application/json

Response Body:

{
    "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"
                        }
                    }
                }
            }
        }
    ]
}
  1. Run the List Policies operation and store the policyId.

  2. If you want to specify the number of results to return, use the limit query parameter. If you want 10 results, add ?limit=10 to the endpoint.

  3. If you want to return images associated with a specific URL, use the url query parameter.

  4. Make a GET request to /imaging/v0/images/{?limit,url,policyId}.

The response includes the Image object.

Get an image

Retrieve a specific image.

GET /imaging/v0/images/{imageId}

Sample: /imaging/v0/images//images/image.jpg%3FimageId%3Dformat/jpg

Headers:

Luna-Token: default-022335
Parameter Type Sample Description
URL parameters
imageId String /images/image.jpg?imageId=format/jpg The ID of the image. This ID usually represents the part of the URL after the scheme, host, and port.

Status 200 application/json

Response Body:

{
    "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"
                }
            }
        }
    }
}
  1. Run the List Images operation and store the imageId.

  2. Make a GET request to /imaging/v0/images/{imageId}.

The response includes the Image object.

List image collections

Lists all image collections, unless you set a limit.

GET /imaging/v0/imagecollections/{?limit}

Sample: /imaging/v0/imagecollections/?limit=2

Parameter Type Sample Description
Optional query parameters
limit Integer 2 Specifies maximum number image collections to retrieve.

Status 200 application/json

Response Body:

{
    "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
}
  1. If you want to specify the number of results to return, use the limit query parameter. If you want 10 results, add ?limit=10 to the endpoint.

  2. Make a GET request to /imaging/v0/imagecollections/{?limit}.

The response includes the ImageCollection object.

Create a new image collection

Create a new image collection.

PUT /imaging/v0/imagecollections/

Content-Type: application/json

Request Body:

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

Status 200 application/json

Response Body:

{
    "operationPerformed": "CREATED",
    "description": "Image Collection SKU-26684355 was created",
    "id": "SKU-26684355"
}
  1. Run the List Image Collections operation.

  2. Review the list of IDs (imageCollectionId) returned.

  3. Create a unique imageCollectionId for the new collection.

  4. Create an ImageCollection object.

  5. Make a PUT request to /imaging/v0/imagecollections/.

The response includes the ImageCollection object.

Get an image collection

Returns the values for the image collection you specify.

GET /imaging/v0/imagecollections/{imageCollectionId}

Sample: /imaging/v0/imagecollections/MyId123

Parameter Type Sample Description
URL parameters
imageCollectionId String MyId123 Unique identifier for each image collection.

Status 200 application/json

Response Body:

{
    "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"
            }
        ]
    }
}
  1. Run the List Image Collections operation and store the imageCollectionId.

  2. Make a GET request to /imaging/v0/imagecollections/{imageCollectionId}.

The response includes the ImageCollection object.

Update an image collection

Update an image collection.

POST /imaging/v0/imagecollections/{imageCollectionId}

Sample: /imaging/v0/imagecollections/MyId123

Content-Type: application/json

Request Body:

{
    "operationPerformed": "UPDATED",
    "description": "Image Collection MyId123 was updated",
    "id": "MyId123"
}
Parameter Type Sample Description
URL parameters
imageCollectionId String MyId123 Unique identifier for each image collection.

Status 200 application/json

Response Body:

{
    "operationPerformed": "UPDATED",
    "description": "Image Collection MyId123 was updated",
    "id": "MyId123"
}
  1. Run the List Image Collections operation and store the imageCollectionId you want to update.

  2. Create an ImageCollection object.

  3. Make a POST request to /imaging/v0/imagecollections/{imageCollectionId}.

The response includes the ImageCollection object.

Delete an image collection

Delete an image collection.

DELETE /imaging/v0/imagecollections/{imageCollectionId}

Sample: /imaging/v0/imagecollections/MyId123

Parameter Type Sample Description
URL parameters
imageCollectionId String MyId123 Unique identifier for each image collection.

Status 200 application/json

Response Body:

{
    "operationPerformed": "DELETED",
    "description": "Item was deleted",
    "id": "MyId123"
}
  1. Run the List Image Collections operation and store the imageCollectionId.

  2. Make a DELETE request to /imaging/v0/imagecollections/{imageCollectionId}.

Get image collection history

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

GET /imaging/v0/imagecollections/{imageCollectionId}/history{?limit}

Sample: /imaging/v0/imagecollections/MyId123/history?limit=2

Parameter Type Sample Description
URL parameters
imageCollectionId String MyId123 Unique identifier for each image collection.
Optional query parameters
limit String 2 Specifies maximum number image collections to retrieve.

Status 200 application/json

Response Body:

{
    "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
}
  1. Run the List Image Collections operation and store the imageCollectionId.

  2. If you want to specify the number of results to return, use the limit query parameter. If you want 10 results, add ?limit=10 to the endpoint.

  3. Make a GET request to /imaging/v0/imagecollections/{imageCollectionId}/history{?limit}.

The response includes the ImageCollection object.

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:

Member is required to be present, regardless of whether its value is empty or null.
Member is optional, and may be omitted in some cases.

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

Member Type Required Description
breakpoints Policy.breakpoints The breakpoint widths to use to create derivative images.
hosts Array Hosts that are allowed for Composite image URLs.
id String Unique identifier for a policy, up to 64 alphanumeric characters including underscores or dashes.
output Policy.output Dictates the output quality (either quality or perceptualQuality) and formats that are created for each resized image. If unspecified, image formats are created to support all browsers at the default quality level (85), which includes formats such as WEBP, JPEG2000 and JPEG-XR for specific browsers.
postBreakpointTransformations Transformation array Transformations applied to the source image after the images for the carousel’s main image view are created.
transformations Transformation array Transformations applied to the source image.
variables Policy.variables[] Declares variables for use within the policy. Any variable declared here can be invoked throughout transformations as a Variable object, so that you don’t have to specify values separately. You can also pass in these variable names and values dynamically as query parameters in the image’s request URL.
Policy.breakpoints: The breakpoint widths to use to create derivative images.
widths Array Specifies each integer breakpoint width value.
Policy.output: Dictates the output quality (either quality or perceptualQuality) and formats that are created for each resized image. If unspecified, image formats are created to support all browsers at the default quality level (85), which includes formats such as WEBP, JPEG2000 and JPEG-XR for specific browsers.
allowedFormats Array The values of the allowed graphics file formats.
forcedFormats Array The values of the forced extra formats.
perceptualQuality Enumeration The perceptual quality to use when comparing resulting images, which overrides the quality setting. 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. Values are tiered high, mediumHigh, medium, mediumLow, or low.
perceptualQuality Variable As an alternative to a static value, specify a predefined Variable object.
quality Integer The chosen quality of the output images. Using a quality value from 1–100 resembles JPEG quality across output formats.
quality Variable As an alternative to a static value, specify a predefined Variable object.
Policy.variables[]: Declares variables for use within the policy. Any variable declared here can be invoked throughout transformations as a Variable object, so that you don’t have to specify values separately. You can also pass in these variable names and values dynamically as query parameters in the image’s request URL.
defaultValue String The default value of the variable if no query parameter is provided. It must be one of the enumOptions if any are provided.
enumOptions Policy.variables[].enumOptions[] Optionally limits the set of possible values for a variable. References to an enum id insert a corresponding value.
name String The name of the variable, also available as the query parameter name to set the variable’s value dynamically. Use up to 50 alphanumeric characters.
postfix String A postfix added to the value provided for the variable, or to the default value.
prefix String A prefix added to the value provided for the variable, or to the default value.
type Enumeration The type of variable, either bool, number, url, color, gravity, placement, scaleDimension, grayscaleType, aspect, resizeType, dimension, or perceptualQuality.
Policy.variables[].enumOptions[]: Optionally limits the set of possible values for a variable. References to an enum id insert a corresponding value.
id String The unique identifier for each enum value, up to 50 alphanumeric characters.
value String The value of the variable when the id is provided.

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

Member Type Required Description
description String A description of the action performed on the image.
id String The ID of the image.
ordinal Integer The ordinal of the image.
policies Policy map The policies applied to this image.
url String The URL of the image.

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

Member Type Required Description
items Object Array of Image, Video, and Spin360 objects.
version Number The version of the collection.

Video

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

Download schema: video.json

Video members

Member Type Required Description
mime String The MIME type of the video.
poster String The URL of the image to display while the video is downloading.
tags Array Additional keywords to describe the object.
type Enumeration The type of item in the collection, video in this case.
url String The URL of the video.

Spin360

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

Download schema: spin-360.json

Spin360 members

Member Type Required Description
tags Array Additional keywords to describe the object.
type Enumeration The type of item in the collection, spin360 in this case.
urls Array The URL of the 360 spin file.

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

Member Type Required Description
itemKind Enumeration The type of Image Manager policy, in this case the POLICIESLOG.
items History.items[] An array showing a history of your Image Manager policy changes.
totalItems Integer The total number of policies returned.
History.items[]: An array showing a history of your Image Manager policy changes.
action Enumeration The action logged, either UPSERT or DELETE.
dateCreated String Date of the log entry in ISO–8601 extended notation format.
id String The ID of the policy.
policy String The policy’s state as a result of the change, represented as a JSON string.
user String The user who made the modification.
version Integer The version of the policy.

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

Member Type Required Description
description String The description of the resource.
id String Unique identifier for a resource.
operationPerformed Enumeration The action performed on the resource, either CREATED, UPDATED, DELETED, or CANCELLED.

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

Member Type Required Description
color String The hexadecimal CSS color value for the background.
color Variable As an alternative to a static value, specify a predefined Variable object.
transformation Enumeration Identifies this type of transformation, BackgroundColor in this case.

Blur

Applies a Gaussian blur to the image.

Download schema: blur.json

Blur members

Member Type Required Description
sigma Number The number of pixels to scatter the original pixel by to create the blur effect. Resulting images may be larger than the original as pixels at the edge of the image might scatter outside the image’s original dimensions.
sigma Variable As an alternative to a static value, specify a predefined Variable object.
transformation Enumeration Identifies this type of transformation, Blur in this case.

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

Member Type Required Description
gravity Enumeration The placement or region within an image. The available values represent the eight cardinal directions, East, West, North, NorthEast, NorthWest, South, SouthEast, SouthWest, and a Center.
gravity Variable As an alternative to a static value, specify a predefined Variable object.
image Composite.image The image you want to apply to the source image.
placement Enumeration Where to place the specified image, either Over or Under the existing image. The default is Over.
placement Variable As an alternative to a static value, specify a predefined Variable object.
scaleDimension Enumeration The dimension, either width or height, of the source image to scale.
scaleDimension Variable As an alternative to a static value, specify a predefined Variable object.
scale Number Change the image size relative to the starting width or height, expressed as a multiple of 1. By default, the source image is not scaled.
scale Variable As an alternative to a static value, specify a predefined Variable object.
transformation Enumeration Identifies this type of transformation, Composite in this case.
xPosition Integer The x-axis position of the image to apply.
xPosition Variable As an alternative to a static value, specify a predefined Variable object.
yPosition Integer The y-axis position of the image to apply.
yPosition Variable As an alternative to a static value, specify a predefined Variable object.
Composite.image: The image you want to apply to the source image.
transformation Transformation If desired, the transformation to perform on the incoming image before adding it to the source image.
url String The URL of the image to apply to the source image.
url Variable As an alternative to a static value, specify a predefined Variable object.

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

Member Type Required Description
transformation Enumeration Identifies this type of transformation, Compound in this case.
transformations Object Lists transformations to perform. Valid transformation types are BackgroundColor, Composite, Crop, MaxColors, Resize, Rotate, and Scale.

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

Member Type Required Description
allowExpansion Boolean If cropping an area outside of the existing canvas, expands the image canvas.
allowExpansion Variable As an alternative to a static value, specify a predefined Variable object.
gravity Enumeration The placement or region within an image. The available values represent the eight cardinal directions, East, West, North, NorthEast, NorthWest, South, SouthEast, SouthWest, and a Center.
gravity Variable As an alternative to a static value, specify a predefined Variable object.
height Integer The number of pixels to crop along the y axis.
height Variable As an alternative to a static value, specify a predefined Variable object.
transformation Enumeration Identifies this type of transformation, Crop in this case.
width Integer The number of pixels to crop along the x axis.
width Variable As an alternative to a static value, specify a predefined Variable object.
xPosition Integer The x-axis position of the image to crop from.
xPosition Variable As an alternative to a static value, specify a predefined Variable object.
yPosition Integer The y-axis position of the image to crop from.
yPosition Variable As an alternative to a static value, specify a predefined Variable object.

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

Member Type Required Description
fillTransformation Transformation The fill settings to use on the image.
height Integer The height value for the resized image.
height Variable As an alternative to a static value, specify a predefined Variable object.
transformation Enumeration Identifies this type of transformation, FitAndFill in this case.
width Integer The width value for the resized image.
width Variable As an alternative to a static value, specify a predefined Variable object.

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

Member Type Required Description
transformation Enumeration Identifies this type of transformation, Grayscale in this case.
type Enumeration The algorithm used to transform colors to grays, either Brightness, Lightness, Rec601, or the default Rec709.
type Variable As an alternative to a static value, specify a predefined Variable object.

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

Member Type Required Description
hue Number Float of the number of degrees to rotate colors around the color wheel.
hue Variable As an alternative to a static value, specify a predefined Variable object.
lightness Number The amount of lightness, between 0 and 1.
lightness Variable As an alternative to a static value, specify a predefined Variable object.
saturation Number The amount of saturation, between 0 and 1.
saturation Variable As an alternative to a static value, specify a predefined Variable object.
transformation Enumeration Identifies this type of transformation, HSL in this case.

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

Member Type Required Description
colours Integer The value representing the maximum number of colors to use with the source image.
colours Variable As an alternative to a static value, specify a predefined Variable object.
transformation Enumeration Identifies this type of transformation, MaxColors in this case.

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

Member Type Required Description
opacity Number Float used to multiply pixel alpha values. 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.
opacity Variable As an alternative to a static value, specify a predefined Variable object.
transformation Enumeration Identifies this type of transformation, Opacity in this case.

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

Member Type Required Description
aspect Enumeration Preserves the aspect ratio. Select fit to make the image fit entirely within the selected width and height. When using fit, the resulting image has the largest possible size for the specified dimensions. Select fill to size the image so it both completely fills the dimensions and has the smallest possible file size. Otherwise ignore changes the original aspect ratio to fit within an arbitrarily shaped rectangle.
aspect Variable As an alternative to a static value, specify a predefined Variable object.
height Integer The height to resize the source image to.
height Variable As an alternative to a static value, specify a predefined Variable object.
transformation Enumeration Identifies this type of transformation, Resize in this case.
type Enumeration Sets constraints for the image resize. Select normal to resize in all cases, either increasing or decreasing the dimensions. Select downsize to ignore this transformation if the result would be larger than the original. Select upsize to ignore this transformation if the result would be smaller.
type Variable As an alternative to a static value, specify a predefined Variable object.
width Integer The width to resize the source image to.
width Variable As an alternative to a static value, specify a predefined Variable object.

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

Member Type Required Description
degrees Number The value to rotate the image by. Positive values rotate clockwise; negative values rotate counter-clockwise.
degrees Variable As an alternative to a static value, specify a predefined Variable object.
transformation Enumeration Identifies this type of transformation, Rotate in this case.

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

Member Type Required Description
height Number Float multiple of input height.
height Variable As an alternative to a static value, specify a predefined Variable object.
transformation Enumeration Identifies this type of transformation, Scale in this case.
width Number Float multiple of input width.
width Variable As an alternative to a static value, specify a predefined Variable object.

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

Member Type Required Description
transformation Enumeration Identifies this type of transformation, Shear in this case.
xShear Integer The amount to shear along the x-axis.
xShear Variable As an alternative to a static value, specify a predefined Variable object.
yShear Integer The amount to shear along the y-axis.
yShear Variable As an alternative to a static value, specify a predefined Variable object.

Trim

Automatically crops uniform backgrounds from the edges of an image.

Download schema: trim.json

Trim members

Member Type Required Description
fuzz Number The fuzz tolerance of the trim, a value between 0 and 1 that determines the acceptable amount of background variation before trimming is stopped.
fuzz Variable As an alternative to a static value, specify a predefined Variable object.
padding Integer The amount of padding in pixels to add to the trimmed image.
padding Variable As an alternative to a static value, specify a predefined Variable object.
transformation Enumeration Identifies this type of transformation, Trim in this case.

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

Member Type Required Description
gain Number The strength of the unsharp mask.
gain Variable As an alternative to a static value, specify a predefined Variable object.
sigma Number The size of the unsharp mask.
sigma Variable As an alternative to a static value, specify a predefined Variable object.
threshold Number The threshold of the unsharp mask.
threshold Variable As an alternative to a static value, specify a predefined Variable object.
transformation Enumeration Identifies this type of transformation, UnsharpMask in this case.

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

Member Type Required Description
default Transformation A no-op transformation, by default.
dimension Enumeration The dimension to use to select the transformation, either height, width, or both.
dimension Variable As an alternative to a static value, specify a predefined Variable object.
equal Transformation The transformation performed only if the source image’s dimension is equal to the value listed.
greaterThan Transformation The transformation performed if the source image’s dimension is greater than the value listed.
lessThan Transformation The transformation performed if the source image’s dimension is less than the value listed.
transformation Enumeration Identifies this type of transformation, IfDimension in this case.
value Integer The value to compare against the source image dimension.
value Variable As an alternative to a static value, specify a predefined Variable object.

IfOrientation

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

Download schema: if-orientation.json

IfOrientation members

Member Type Required Description
default Transformation A no-op transformation, by default.
landscape Transformation The transformation performed if the source image uses landscape orientation.
portrait Transformation The transformation performed if the source image uses portrait orientation.
square Transformation The transformation performed if the source image uses a square orientation.
transformation Enumeration Identifies this type of transformation, IfOrientation in this case.

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

Member Type Required Description
var String Corresponds to the name of the variable declared by the policy, to insert the corresponding value.

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.

Code Description
200 The operation was successful.
201 Created.
400 Bad Request.
404 Not Found.

Last modified: 7/2/2018