loading

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.

Get started

To get started with this API:

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

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

  • Enable Image Manager on a property in Property Manager, then use the Policy Set Name (API key) in the behavior for the Luna-Token header. In this API you need to pass in an additional Luna-Token header with each request, which 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, 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.

Test images on-demand

For on-demand transformations and testing, you can add these 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 Requests to apply a specific image policy.

You can combine the impolicy, imwidth and imformat query parameters in a single request to perform several 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 these format types: JPEG, PNG, GIF, and JPEG 2000 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: Like other Akamai APIs, the Image Manager API uses hostname tokens to authenticate requests. However, in this API you need to pass in an additional Luna-Token header with each request. You get this key from the Image Manager behavior in your Property Manager configuration that applies to the set of images you’re working on.

  • 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 invalidates 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. For better byte savings without compromising perception of the image, use perceptualQuality instead of quality to encode many images at a much lower quality. For certain images that need to maintain human-perceived quality, encode them at a slightly higher quality.

Transformation types

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

Transformation Description
Append Specifies an image or text to affix beside the image you’re transforming, also referred to as the source image. The API places the appended image on a major dimension, then aligns the image on the minor dimension. When you append to a source image, there might be an area created that’s not covered by either image. Transparent pixels fill this area.
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 source image, either as an overlay or an underlay. The image that’s 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.
Contrast Adjusts both the contrast and brightness of an image.
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.
FaceCrop Detects faces in an image, then crops them to position the faces in the center of the image.
FeatureCrop Identifies prominent features of an image such as strong corners, then crops around those features.
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.
Goop Distorts an image. For example, think of your image printed on a rubber sheet of paper with a grid of pins, also referred to as control points, in the rubber. Goop shifts the pins a random distance in a random direction, distorting the image on the rubber. The results look like a goopy version of the image. You can use this to create non-deterministic watermarks for security purposes.
Grayscale Renders the image in shades of black, white, and gray.
HLS Adjusts the hue, saturation, and lightness (HSL) of an image. Hue is the number of degrees that colors rotate 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. Other transformations can also affect color, such as Grayscale and Max Colors. If you’re using more than one, consider the order to apply them for the desired results.
HSV Identical to HSL except it replaces lightness with value. For example, if you reduce the lightness of a light green, almost white, image, the color turns a vibrant green. Reducing the value, turns the image a darker color, close to gray. This is because the original image color is very close to white.
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.
Mirror Flips an image horizontally, vertically, or both.
Opacity Changes the opacity of an image. Use this transformation 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.
RegionOfInterestCrop Crops to a region around a specified area of interest.
RelativeCrop Shrinks or expands the four sides of an image relative to its current dimensions. Transparent pixels fill this expanded area.
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 and 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.
Shear Slants an image into a parallelogram, as a percent of starting dimension as represented in decimal format. You need to specify at least one axis property. Transparent pixels fill empty areas around the sheared image as needed. It’s useful to use backgroundColor transformation for these areas.
Trim Automatically crops uniform backgrounds from the edges of an image.
UnsharpMask Emphasizes edges and details in source images without distorting the colors. Although this effect is often referred to as sharpening an image, it actually creates a blurred, inverted copy of the image, or unsharp mask. Image Manager combines the unsharp mask with the source image to create a clearer image.

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

Transformation Description
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.

Several transformations may specify these types of images:

Transformation Description
BoxImageType A rectangular box, with a specified color and applied transformation.
TextImageType A snippet of text. Defines font family and size, fill color, and outline stroke width and color.
UrlImageType An image loaded from a URL.

Several transformations may specify these types of shapes:

Transformation Description
CircleShapeType Defines a circle with a specified radius from its center point.
PointShapeType Defines coordinates for a single point, to help define polygons and rectangles. Each point may be an object with x and y members, or a two-element array.
PolygonShapeType Defines a polygon from a series of connected points.
RectangleShapeType Defines a rectangle’s width and height relative to an anchor point.
UnionShapeType Identifies a combined shape based on a set of other shapes. You can use a full JSON object to represent a union or an array of shapes that describe it.

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

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. Get the Luna-Token header generated once Image Manager is enabled on a property. This header, or API key, is needed 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 get a list 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. 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’d 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

  9. Test the policy on the staging network, then activate the policy using 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}
Remove an image collection DELETE /imaging/v0/imagecollections/{imageCollectionId}
Get image collection history GET /imaging/v0/imagecollections/{imageCollectionId}/history{?limit}

List policies

Returns 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

Object type: Policy

Download schema: get-policies.json

Response body:

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

Get a policy

Returns a specific policy assigned to 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 path parameters
policyId String thumbnail_policy Unique identifier for a policy.

Status 200 application/json

Object type: Policy

Download schema: policy.json

Response body:

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

Object type: Policy

Download schema: policy.json

Request body:

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

Status 200 application/json

Object type: Acknowledgement

Download schema: operation-performed.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 path parameters
policyId String thumbnail_policy Unique identifier for a policy.

Status 200 application/json

Object type: Acknowledgement

Download schema: operation-performed.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

Returns the 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 path parameters
policyId String thumbnail_policy Unique identifier for a policy.

Status 200 application/json

Object type: History

Download schema: get-policy-history.json

Response body:

{
    "itemKind": "POLICIESLOG",
    "totalItems": 1,
    "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"
        }
    ]
}
  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 of images to get.
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

Object type: Image

Download schema: get-images.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. Optionally, to specify the number of results to return, use the limit query parameter. If you want 10 results, add ?limit=10 to the URL.

  3. Optionally, to return images contained within a specific URL path, 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

Returns 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 path 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

Object type: Image

Download schema: image.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 get.

Status 200 application/json

Object type: ImageCollection

Download schema: image-collection-definition-array-response.json

Response body:

{
    "itemKind": "IMAGECOLLECTION",
    "totalItems": 2,
    "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"
                    }
                ]
            }
        }
    ]
}
  1. Optionally, to specify the number of results to return, use the limit query parameter. If you want 10 results, add ?limit=10 to the URL.

  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

Object type: ImageCollection

Download schema: image-collection.json

Request body:

{
    "id": "api_sample_collection",
    "definition": {
        "items": [
            {
                "type": "image",
                "url": "http://productdemo.akaimaging.com/samples/sample01.png"
            },
            {
                "type": "image",
                "url": "http://productdemo.akaimaging.com/samples/sample02.png"
            },
            {
                "type": "spin360",
                "urls": [
                    "http://productdemo.akaimaging.com/samples/sample03.png",
                    "http://productdemo.akaimaging.com/samples/sample04.png",
                    "http://productdemo.akaimaging.com/samples/sample05.png"
                ]
            }
        ]
    }
}

Status 200 application/json

Object type: Acknowledgement

Download schema: operation-performed.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 path parameters
imageCollectionId String MyId123 Unique identifier for each image collection.

Status 200 application/json

Object type: ImageCollection

Download schema: image-collection-definition.json

Response body:

{
    "id": "api_sample_collection",
    "definition": {
        "items": [
            {
                "type": "image",
                "url": "http://productdemo.akaimaging.com/samples/sample01.png"
            },
            {
                "type": "image",
                "url": "http://productdemo.akaimaging.com/samples/sample02.png"
            },
            {
                "type": "spin360",
                "urls": [
                    "http://productdemo.akaimaging.com/samples/sample03.png",
                    "http://productdemo.akaimaging.com/samples/sample04.png",
                    "http://productdemo.akaimaging.com/samples/sample05.png"
                ]
            }
        ]
    }
}
  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

Object type: ImageCollection

Download schema: image-collection.json

Request body:

{
    "id": "api_sample_collection",
    "definition": {
        "items": [
            {
                "type": "image",
                "url": "http://productdemo.akaimaging.com/samples/sample01.png"
            },
            {
                "type": "image",
                "url": "http://productdemo.akaimaging.com/samples/sample02.png"
            },
            {
                "type": "spin360",
                "urls": [
                    "http://productdemo.akaimaging.com/samples/sample03.png",
                    "http://productdemo.akaimaging.com/samples/sample04.png",
                    "http://productdemo.akaimaging.com/samples/sample05.png"
                ]
            }
        ]
    }
}
Parameter Type Sample Description
URL path parameters
imageCollectionId String MyId123 Unique identifier for each image collection.

Status 200 application/json

Object type: Acknowledgement

Download schema: operation-performed.json

Response body:

{
    "operationPerformed": "UPDATED",
    "description": "Image Collection api_sample_collection was updated",
    "id": "api_sample_collection"
}
  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.

Remove an image collection

Delete a specific image collection.

DELETE /imaging/v0/imagecollections/{imageCollectionId}

Sample: /imaging/v0/imagecollections/MyId123

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

Status 200 application/json

Object type: Acknowledgement

Download schema: operation-performed.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 path parameters
imageCollectionId String MyId123 Unique identifier for each image collection.
Optional query parameters
limit Integer 2 Specifies maximum number of image collections to get.

Status 200 application/json

Object type: ImageCollection

Download schema: image-collection-definition-array-response.json

Response body:

{
    "itemKind": "IMAGECOLLECTIONHISTORY",
    "totalItems": 2,
    "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"
                    }
                ]
            }
        }
    ]
}
  1. Run the List image collections operation and store the imageCollectionId.

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

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

The response includes the ImageCollection object.

Data

This section provides details for each type of data object the API exchanges.

Data values follow these general conventions:

  • Any radial degree value outside the range of 0 to 360 has the expected rotational equivalence.

  • For any color, CSS hex values follow #RGB, #RGBA, #RRGGBB, or #RRGGBBAA syntax.

Download the JSON schemas for this API.

This section’s data schema tables list membership requirements as follows:

Member is required in requests, or always present in responses, even if 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",
    "breakpoints": {
        "widths": [
            500,
            300
        ]
    },
    "output": {
        "quality": 90
    },
    "transformations": [
        {
            "transformation": "Composite",
            "xPosition": 0,
            "yPosition": 0,
            "gravity": "SouthWest",
            "image": {
                "url": "www.customer.com/watermark.png"
            }
        }
    ]
}

Policy members

Member Type Required Description
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.
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 Object, 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. Allows Variable substitution.
quality Object, Integer The chosen quality of the output images. Using a quality value from 1–100 resembles JPEG quality across output formats. Allows Variable substitution.
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 needs to 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
Image: Collects information that describes an image.
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
ImageCollection: Provides data about the types of items included in an image collection.
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
Video: Information about a video that’s included in the collection.
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
Spin360: Information about a 360 degree image spin that’s included in the collection.
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",
    "totalItems": 1,
    "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"
        }
    ]
}

History members

Member Type Required Description
History: Provides date, user, and version information for your Image Manager policies.
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
Acknowledgement: The type of operation performed on an Image Manager resource.
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 that let you change images. For example, you can rotate an image, adjust its color, and add a watermark to it. Depending on the image’s size or orientation, you can apply different transformations. For example, if the image is either portrait, landscape, or square, you can crop it to an exact width and height. You can include many transformations within a policy. See Transformation types for available object types.

Append

Places a specified image beside the source image. The API places the image on a major dimension, then aligns it on the minor dimension. Transparent pixels fill any area not covered by either image.

Download schema: append.json

Sample that places an image horizontally at the top-right of the source image:

{
    "transformation": "Append",
    "gravity": "NorthEast",
    "gravityPriority": "horizontal",
    "preserveMinorDimension": false,
    "image": {
        "url": "https://www.example.com/someImage.jpg"
    }
}

Append members

Member Type Required Description
Append: Places a specified image beside the source image. The API places the image on a major dimension, then aligns it on the minor dimension. Transparent pixels fill any area not covered by either image.
gravity Object, Enumeration Specifies where to place the image relative to the source image. The available values represent the eight cardinal directions (North, South, East, West, NorthEast, NorthWest, SouthEast, SouthWest) and a Center by default. Allows Variable substitution.
gravityPriority Object, Enumeration Determines the exact placement of the image when gravity is Center or a diagonal. The value is either horizontal or vertical. Use horizontal to append an image east or west of the source image. This aligns the image on the vertical gravity component, placing Center gravity east. Use vertical to append an image north or south of the source image. This aligns the image on the horizontal gravity component, placing Center gravity south. Allows Variable substitution.
image Object The image type, either a BoxImageType, TextImageType, or UrlImageType.
preserveMinorDimension Object, Boolean Whether to preserve the source image’s minor dimension, false by default. The minor dimension is the dimension opposite the dimension that the appending image is placed. For example, the dimensions of the source image are 100 × 100 pixels. The dimensions of the appending image are 50 × 150 pixels. The gravity is set to East. This makes the major dimension horizontal and the source image’s minor dimension vertical. To preserve the source image’s minor dimension at 100 pixels, the preserveMinorDimension is set to true. As a result of the append, the major dimension expanded with the appended image to 150 pixels. The source image’s minor dimension was maintained at 100 pixels. The total combined dimension of the image is 150 × 100 pixels. Allows Variable substitution.
transformation Enumeration Identifies this type of transformation, Append in this case.

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
BackgroundColor: Places a transparent image on a set background color. Color is specified in the typical CSS hexadecimal format.
color Object, String The hexadecimal CSS color value for the background. Allows Variable substitution.
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
Blur: Applies a Gaussian blur to the image.
sigma Object, 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. Allows Variable substitution.
transformation Enumeration Identifies this type of transformation, Blur in this case.

Composite

Applies another image to the source image, either as an overlay or an underlay. The image that’s 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",
    "xPosition": 0,
    "yPosition": 0,
    "gravity": "NorthWest",
    "placement": "Over",
    "scale": 0.5,
    "scaleDimension": "width",
    "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"
                        }
                    }
                }
            }
        }
    ]
}

Composite members

Member Type Required Description
Composite: Applies another image to the source image, either as an overlay or an underlay. The image that’s 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.
gravity Object, Enumeration The placement or region within an image. The available values represent the eight cardinal directions (North, South, East, West, NorthEast, NorthWest, SouthEast, SouthWest) and a Center by default. Allows Variable substitution.
image Composite.image The image you want to apply to the source image.
placement Object, Enumeration Where to place the specified image, either Over or Under the existing image. The default is Over. Allows Variable substitution.
scale Object, Number A multiplier to resize the applied image relative to the source image and preserve aspect ratio, 1 by default. Set the scaleDimension to calculate the scale from the source image’s width or height. Allows Variable substitution.
scaleDimension Object, Enumeration The dimension, either width or height, of the source image to scale. Allows Variable substitution.
transformation Enumeration Identifies this type of transformation, Composite in this case.
xPosition Object, Integer The x-axis position of the image to apply. Allows Variable substitution.
yPosition Object, Integer The y-axis position of the image to apply. Allows Variable substitution.
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 Object, String The URL of the image to apply to the source image. Allows Variable substitution.

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
Compound: An ordered combination of transformations to perform. Use to represent a sequence of transformations as a single transformation.
transformation Enumeration Identifies this type of transformation, Compound in this case.
transformations Transformation array Lists transformations to perform. Valid transformation types are BackgroundColor, Composite, Crop, MaxColors, Resize, Rotate, and Scale.

Contrast

Adjusts both the contrast and brightness of an image.

Download schema: contrast.json

Sample that adjusts both the contrast and brightness of an image:

{
    "transformation": "Contrast",
    "contrast": 0.2,
    "brightness": -0.3
}

Contrast members

Member Type Required Description
Contrast: Adjusts both the contrast and brightness of an image.
brightness Object, Number Adjusts the brightness of the image. Positive values increase brightness and negative values decrease brightness. A value of 1 produces a white image. A value of -1 produces a black image. The default value is 0, which leaves the image unchanged. The acceptable value range is -1.0 to 1.0. Values outside of the acceptable range clamp to this range. Allows Variable substitution.
contrast Object, Number Adjusts the contrast of the image. Expressed as a range from -1 to 1, positive values increase contrast, negative values decrease it, while 0 leaves the image unchanged. Values outside of the -1 to 1 range clamp to this range. Allows Variable substitution.
sloppy Object, Boolean Whether to sacrifice image fidelity for faster performance, true by default. Allows Variable substitution.
transformation Enumeration Identifies this type of transformation, Contrast in this case.

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
Crop: Crops an image.
allowExpansion Object, Boolean If cropping an area outside of the existing canvas, expands the image canvas. Allows Variable substitution.
gravity Object, Enumeration The placement or region within an image. The available values represent the eight cardinal directions (North, South, East, West, NorthEast, NorthWest, SouthEast, SouthWest) and a Center by default. Allows Variable substitution.
height Object, Integer The number of pixels to crop along the y-axis. Allows Variable substitution.
transformation Enumeration Identifies this type of transformation, Crop in this case.
width Object, Integer The number of pixels to crop along the x-axis. Allows Variable substitution.
xPosition Object, Integer The x-axis position of the image to crop from. Allows Variable substitution.
yPosition Object, Integer The y-axis position of the image to crop from. Allows Variable substitution.

FaceCrop

Applies a method to detect faces in the source image and applies the rectangular crop on either the biggest face or all of the faces detected. Image Manager tries to preserve faces in the image instead of using specified crop coordinates.

Download schema: face-crop.json

Sample that detects a face in an image, then crops the image to position the face in the center of the image:

{
    "transformation": "FaceCrop",
    "focus": "allFaces",
    "style": "zoom",
    "width": 400,
    "height": 400,
    "padding": 0.2,
    "gravity": "North",
    "failGravity": "Center"
}

FaceCrop members

Member Type Required Description
FaceCrop: Applies a method to detect faces in the source image and applies the rectangular crop on either the biggest face or all of the faces detected. Image Manager tries to preserve faces in the image instead of using specified crop coordinates.
algorithm Object, Enumeration Specifies the type of algorithm used to detect faces in the image, either cascade for the cascade classifier algorithm or dnn for the deep neural network algorithm, cascade by default. Allows Variable substitution.
confidence Object, Number With algorithm set to dnn, specifies the minimum confidence needed to detect faces in the image. Values range from 0 to 1 for increased confidence, and possibly fewer faces detected. Allows Variable substitution.
debug Object, Boolean Outlines the faces detected, the specified point of interest, and crop area of the source image, false by default. Use this as an alternative to cropping faces in the image. Allows Variable substitution.
failGravity Object, Enumeration If no faces are detected, this specifies the placement and size of the crop area relative to the source image and the specified style value. The available values represent the eight cardinal directions (North, South, East, West, NorthEast, NorthWest, SouthEast, SouthWest) and a Center by default. Allows Variable substitution.
focus Object, Enumeration Distinguishes the faces detected, either biggest or all to place the crop rectangle around the full set of faces, all by default. Allows Variable substitution.
gravity Object, Enumeration The placement of the crop area relative to the faces detected plus the padding value. The available values represent the eight cardinal directions (North, South, East, West, NorthEast, NorthWest, SouthEast, SouthWest) and a Center by default. Allows Variable substitution.
height Object, Integer The height of the output image in pixels relative to the specified style value. Allows Variable substitution.
padding Object, Number The padding ratio based on the dimensions of the biggest face detected, 0.5 by default. Larger values increase padding. Allows Variable substitution.
sloppy Object, Boolean Whether to sacrifice image fidelity for faster performance, false by default. Allows Variable substitution.
style Object, Enumeration Specifies how to crop or scale a crop area for the faces detected in the source image, zoom by default. The output image resizes to the specified width and height values. A value of crop places a raw crop around the faces, relative to the specified gravity value. A value of fill scales the crop area to include as much of the image and faces as possible, relative to the specified width and height values. A value of zoom scales the crop area as small as possible to fit the faces, relative to the specified width and height values. Allows Variable substitution.
transformation Enumeration Identifies this type of transformation, FaceCrop in this case.
width Object, Integer The width of the output image in pixels relative to the specified style value. Allows Variable substitution.

FeatureCrop

Identifies prominent features of the source image, then crops around as many of these features as possible relative to the specified width and height values.

Download schema: feature-crop.json

Sample that identifies the main features of an image, then crops around those features:

{
    "transformation": "FeatureCrop",
    "width": 400,
    "height": 300,
    "featureRadius": 10,
    "maxFeatures": 50,
    "minFeatureQuality": 0.3,
    "style": "zoom",
    "padding": 0.1,
    "gravity": "Center",
    "failGravity": "Center"
}

FeatureCrop members

Member Type Required Description
FeatureCrop: Identifies prominent features of the source image, then crops around as many of these features as possible relative to the specified width and height values.
debug Object, Boolean Outlines the features identified, the specified point of interest, and crop area of the source image, false by default. Use this as an alternative to cropping features in the image. Allows Variable substitution.
failGravity Object, Enumeration If no features are identified, this specifies the placement of the crop area relative to the source image and the specified style value. The available values represent the eight cardinal directions (North, South, East, West, NorthEast, NorthWest, SouthEast, SouthWest) and a Center by default. Allows Variable substitution.
featureRadius Object, Number The size in pixels of the important features to search for. If identified, two features never appear closer together than this value, 8.0 by default. Allows Variable substitution.
gravity Object, Enumeration The placement of the crop area relative to the features identified plus the specified padding value. The available values represent the eight cardinal directions (North, South, East, West, NorthEast, NorthWest, SouthEast, SouthWest) and a Center by default. Allows Variable substitution.
height Object, Integer The height in pixels of the output image relative to the specified style value. Allows Variable substitution.
maxFeatures Object, Integer The maximum number of features to identify as important features, 32 by default. The strongest features are always chosen. Allows Variable substitution.
minFeatureQuality Object, Number Determines the minimum quality level of the feature identified. To consider a feature important, the feature needs to surpass this value. Image Manager measures quality on a scale from 0 for the lowest quality to 1 for the highest quality, .1 by default. Allows Variable substitution.
padding Object, Number Adds space around the region of interest. The amount of padding added is directly related to the size of the bounding box of the selected features. Specifically, the region of interest is expanded in all directions by the largest dimension of the bounding box of the selected features multiplied by this value. Allows Variable substitution.
sloppy Object, Boolean Whether to sacrifice image fidelity for faster performance, false by default. Allows Variable substitution.
style Object, Enumeration Specifies how to crop or scale a crop area for the features identified in the source image, fill by default. The output image resizes to the specified width and height values. A value of crop performs a raw crop around the features, relative to the specified gravity value. A value of fill scales the crop area to include as much of the image and features as possible, relative to the specified width and height values. A value of zoom scales the crop area as small as possible to fit the features, relative to the specified width and height values. Allows Variable substitution.
transformation Enumeration Identifies this type of transformation, FeatureCrop in this case.
width Object, Integer The width in pixels of the output image relative to the specified style value. Allows Variable substitution.

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
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.
fillTransformation Transformation The fill settings to use on the image.
height Object, Integer The height value of the resized image. Allows Variable substitution.
transformation Enumeration Identifies this type of transformation, FitAndFill in this case.
width Object, Integer The width value of the resized image. Allows Variable substitution.

Goop

Distorts an image by randomly repositioning a set of control points along a specified grid. The transformed image appears goopy. Adjust the density of the grid and the degree of randomity. You can use this transformation to create watermarks for use in security.

Download schema: goop.json

Sample that distorts an image.:

{
    "transformation": "Goop",
    "chaos": 0.4,
    "density": 3,
    "seed": 31415926
}

Goop members

Member Type Required Description
Goop: Distorts an image by randomly repositioning a set of control points along a specified grid. The transformed image appears goopy. Adjust the density of the grid and the degree of randomity. You can use this transformation to create watermarks for use in security.
chaos Object, Number Specifies the greatest distance control points may move from their original position. A value of 1.0 shifts control points over as far as the next one in the original grid. A value of 0.0 leaves the image unchanged. Values under 0.5 work better for subtle distortions, otherwise control points may pass each other and cause a twisting effect. Allows Variable substitution.
density Object, Integer Controls the density of control points used to distort the image. The largest dimension of the input image is divided up to fit this number of control points. A grid of points is extended on the smaller dimension such that each row and column of control points is equidistant from each adjacent row or column. This parameter strongly affects transformation performance. Be careful choosing values above the default if you expect to transform medium to large size images.
power Object, Number By default, the distortion algorithm relies on inverse squares to calculate distance but this allows you to change the exponent. You shouldn’t need to vary the default value of 2.0.
seed Object, Integer Specifies your own seed value as an alternative to the default, which is subject to variability. This allows for reproducible and deterministic distortions. If all parameters are kept equal and a constant seed is used, Goop distorts an input image consistently over many transformations. By default, this value is set to the current Epoch Time measured in milliseconds, which provides inconsistent transformation output. Allows Variable substitution.
sloppy Object, Boolean Whether to sacrifice image fidelity for faster performance, false by default. Allows Variable substitution.
transformation Enumeration Identifies this type of transformation, Goop in this case.

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
Grayscale: Restricts image color to shades of gray only.
transformation Enumeration Identifies this type of transformation, Grayscale in this case.
type Object, Enumeration The algorithm used to transform colors to grays, either Brightness, Lightness, Rec601, or the default Rec709. Allows Variable substitution.

HLS

Adjusts the hue, saturation, and lightness (HSL) of an image. Hue is the number of degrees that colors rotate 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. Other transformations can also affect color, such as Grayscale and MaxColors. If you’re using more than one, consider the order to apply them for the desired results.

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
}

HLS members

Member Type Required Description
HLS: Adjusts the hue, saturation, and lightness (HSL) of an image. Hue is the number of degrees that colors rotate 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. Other transformations can also affect color, such as Grayscale and MaxColors. If you’re using more than one, consider the order to apply them for the desired results.
hue Object, Number The number of degrees to rotate colors around the color wheel, 0 by default. Allows Variable substitution.
lightness Object, Number A multiplier to adjust the lightness of colors in the image. Note that lightness is distinct from brightness. For example, reducing the lightness of a light green might give you a lime green whereas reducing the brightness of a light green might give you a darker shade of the same green. Values less than 1.0 decrease the lightness of colors in the image. Values greater than 1.0 increase the lightness of colors in the image. Allows Variable substitution.
saturation Object, Number A multiplier to adjust the saturation of colors in the image. Values less than 1.0 decrease saturation and values greater than 1.0 increase the saturation. A value of 0.0 removes all color from the image. Allows Variable substitution.
transformation Enumeration Identifies this type of transformation, HSL in this case.

HSV

Identical to HSL except it replaces lightness with value. For example, if you reduce the lightness of a light green, almost white, image, the color turns a vibrant green. Reducing the value turns the image a darker color, close to grey. This happens because the original image color is very close to white.

Download schema: hsv.json

HSV members

Member Type Required Description
HSV: Identical to HSL except it replaces lightness with value. For example, if you reduce the lightness of a light green, almost white, image, the color turns a vibrant green. Reducing the value turns the image a darker color, close to grey. This happens because the original image color is very close to white.
hue Object, Number The number of degrees to rotate colors around the color wheel, 0.0 by default. Allows Variable substitution.
saturation Object, Number A multiplier to adjust the saturation of colors in the image. Values less than 1.0 decrease saturation and values greater than 1.0 increase the saturation. A value of 0.0 removes all color from the image. Allows Variable substitution.
transformation Enumeration Identifies this type of transformation, HSV in this case.
value Object, Number A multiplier to adjust the lightness or darkness of the image’s base color. Values less than 1.0 decrease the base colors in the image, making them appear darker. Values greater than 1.0 increase the base colors in the image, making them appear lighter. Allows Variable substitution.

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
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.
colours Object, Integer The value representing the maximum number of colors to use with the source image. Allows Variable substitution.
transformation Enumeration Identifies this type of transformation, MaxColors in this case.

Mirror

Flips an image horizontally, vertically, or both.

Download schema: mirror.json

Sample that flips an image horizontally and vertically:

{
    "transformation": "Mirror",
    "horizontal": true,
    "vertical": true
}

Mirror members

Member Type Required Description
Mirror: Flips an image horizontally, vertically, or both.
horizontal Object, Boolean Flips the image horizontally. Allows Variable substitution.
transformation Enumeration Identifies this type of transformation, Mirror in this case.
vertical Object, Boolean Flips the image vertically. Allows Variable substitution.

Opacity

Adjusts the level of transparency of an image. Use this transformation to make an image more or less 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: Adjusts the level of transparency of an image. Use this transformation to make an image more or less transparent.
opacity Object, Number Represents alpha values on a scale of 0 to 1. Values below 1 increase transparency, and 0 is invisible. For images that have some transparency, values above 1 increase the opacity of the transparent portions. Allows Variable substitution.
transformation Enumeration Identifies this type of transformation, Opacity in this case.

RegionOfInterestCrop

Crops to a region around a specified area of interest relative to the specified width and height values.

Download schema: region-of-interest-crop.json

Sample that captures a specific area of the image:

{
    "transformation": "RegionOfInterestCrop",
    "width": 500,
    "height": 500,
    "style": "zoom",
    "gravity": "North",
    "regionOfInterest": {
        "radius": 20,
        "center": [
            100,
            175
        ]
    }
}

RegionOfInterestCrop members

Member Type Required Description
RegionOfInterestCrop: Crops to a region around a specified area of interest relative to the specified width and height values.
gravity Object, Enumeration The placement of the crop area relative to a specified area of interest. The available values represent the eight cardinal directions (North, South, East, West, NorthEast, NorthWest, SouthEast, SouthWest) and a Center by default. Allows Variable substitution.
height Object, Integer The height in pixels of the output image relative to the specified style value. Allows Variable substitution.
regionOfInterest CircleShapeType, PolygonShapeType, RectangleShapeType, UnionShapeType The shape that determines how to crop the source image.
sloppy Object, Boolean Whether to sacrifice image fidelity for faster performance, false by default. Allows Variable substitution.
style Object, Enumeration Specifies how to crop or scale a crop area for the specified area of interest in the source image, zoom by default. The output image resizes to the specified width and height values. A value of crop places raw crop around the point of interest, relative to the specified gravity value. A value of fill scales the crop area to include as much of the image and point of interest as possible, relative to the specified width and height values. A value of zoom scales the crop area as small as possible to fit the point of interest, relative to the specified width and height values. Allows Variable substitution.
transformation Enumeration Identifies this type of transformation, RegionOfInterestCrop in this case.
width Object, Integer The width in pixels of the output image relative to the specified style value. Allows Variable substitution.

RelativeCrop

Shrinks or expands an image relative to the image’s specified dimensions. Image Manager fills the expanded areas with transparency. Positive values shrink the side, while negative values expand it.

Download schema: relative-crop.json

Sample that expands the four sides of an image:

{
    "transformation": "RelativeCrop",
    "north": 10,
    "east": 15,
    "south": 10,
    "west": 15
}

RelativeCrop members

Member Type Required Description
RelativeCrop: Shrinks or expands an image relative to the image’s specified dimensions. Image Manager fills the expanded areas with transparency. Positive values shrink the side, while negative values expand it.
east Object, Integer The number of pixels to shrink or expand the right side of the image. Allows Variable substitution.
north Object, Integer The number of pixels to shrink or expand the top side of the image. Allows Variable substitution.
south Object, Integer The number of pixels to shrink or expand the bottom side of the image. Allows Variable substitution.
transformation Enumeration Identifies this type of transformation, RelativeCrop in this case.
west Object, Integer The number of pixels to shrink or expand the left side of the image. Allows Variable substitution.

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
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.
aspect Object, 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. Allows Variable substitution.
height Object, Integer The height to resize the source image to. Allows Variable substitution.
transformation Enumeration Identifies this type of transformation, Resize in this case.
type Object, 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. Allows Variable substitution.
width Object, Integer The width to resize the source image to. Allows Variable substitution.

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
Rotate: Rotate the image around its center by indicating the degrees of rotation.
degrees Object, Number The value to rotate the image by. Positive values rotate clockwise, while negative values rotate counter-clockwise. Allows Variable substitution.
transformation Enumeration Identifies this type of transformation, Rotate in this case.

Scale

Changes 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
Scale: Changes the image’s size to different dimensions relative to its starting size.
height Object, Number Scaling factor for the input height to determine the output height of the image, where values between 0 and 1 decrease size. Image dimensions need to be non-zero positive numbers. Allows Variable substitution.
transformation Enumeration Identifies this type of transformation, Scale in this case.
width Object, Number Scaling factor for the input width to determine the output width of the image, where 1 leaves the width unchanged. Values greater than 1 increase the image size. Image dimensions need to be non-zero positive numbers. Allows Variable substitution.

Shear

Slants an image into a parallelogram, as a percent of the starting dimension as represented in decimal format. You need to specify at least one axis property. Transparent pixels fill empty areas around the sheared image as needed, so it’s often useful to use a backgroundColor transformation for these areas.

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
Shear: Slants an image into a parallelogram, as a percent of the starting dimension as represented in decimal format. You need to specify at least one axis property. Transparent pixels fill empty areas around the sheared image as needed, so it’s often useful to use a backgroundColor transformation for these areas.
transformation Enumeration Identifies this type of transformation, Shear in this case.
xShear Object, Integer The amount to shear along the x-axis, measured in multiples of the image’s width. Use a decimal value from –5 to 5. The transformation fails if the range is exceeded. Allows Variable substitution.
yShear Object, Integer The amount to shear along the y-axis, measured in multiples of the image’s height. Use a decimal value from –5 to 5. Allows Variable substitution.

Trim

Automatically crops uniform backgrounds from the edges of an image.

Download schema: trim.json

Trim members

Member Type Required Description
Trim: Automatically crops uniform backgrounds from the edges of an image.
fuzz Object, Number The fuzz tolerance of the trim, a value between 0 and 1 that determines the acceptable amount of background variation before trimming stops. Allows Variable substitution.
padding Object, Integer The amount of padding in pixels to add to the trimmed image. Allows Variable substitution.
transformation Enumeration Identifies this type of transformation, Trim in this case.

UnsharpMask

Emphasizes edges and details in source images without distorting the colors. Although this effect is often referred to as sharpening an image, it actually creates a blurred, inverted copy of the image known as an unsharp mask. Image Manager combines the unsharp mask with the source image to create an image perceived as clearer.

Download schema: unsharp-mask.json

UnsharpMask members

Member Type Required Description
UnsharpMask: Emphasizes edges and details in source images without distorting the colors. Although this effect is often referred to as sharpening an image, it actually creates a blurred, inverted copy of the image known as an unsharp mask. Image Manager combines the unsharp mask with the source image to create an image perceived as clearer.
gain Object, Number The amount of emphasis to add to edges and details. A value of 0 adds no emphasis. A value of 1.0 adds a common, clearly visible amount of emphasis. Values greater than 1.0 are allowed but may be considered more extreme or artistic.
sigma Object, Number The standard deviation of the Gaussian distribution used in the in unsharp mask, measured in pixels, 1.0 by default. High values emphasize large details and low values emphasize small details. Allows Variable substitution.
threshold Object, Number Adjusts how strong a detail needs to be to have any emphasis applied. A minimum value of 0 means the entire image gets some emphasis applied. A maximum value of 1 means none of the image will have emphasis applied no matter how strong its details are. You’ll probably never need to change this from the default value of 0.05. Allows Variable substitution.
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
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.
default Transformation A no-op transformation, by default.
dimension Object, Enumeration The dimension to use to select the transformation, either height, width, or both. Allows Variable substitution.
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 Object, Integer The value to compare against the source image dimension. Allows Variable substitution.

IfOrientation

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

Download schema: if-orientation.json

IfOrientation members

Member Type Required Description
IfOrientation: Chooses a transformation depending on the orientation of the source image.
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.

BoxImageType

A rectangular box, with a specified color and applied transformation.

Download schema: box-image-type.json

Sample that represents a box image:

{
    "type": "Box",
    "color": "#81c119",
    "width": 200,
    "height": 150
}

BoxImageType members

Member Type Required Description
BoxImageType: A rectangular box, with a specified color and applied transformation.
color Object, String The fill color of the box, not the edge of the box. The API supports hexadecimal representation and CSS hexadecimal color values. Allows Variable substitution.
height Object, Integer The height of the box in pixels. Allows Variable substitution.
transformation Transformation The Transformation type applied to the box. For example, you can Rotate the box.
type Enumeration Identifies the type of image, Box in this case.
width Object, Integer The width of the box in pixels. Allows Variable substitution.

TextImageType

A snippet of text. Defines font family and size, fill color, and outline stroke width and color.

Download schema: text-image-type.json

Sample that renders a string of text to an image:

{
    "type": "Text",
    "text": "Sample text to make an image from!",
    "typeface": "https://www.example.com/fonts/someFont.woff",
    "size": 50,
    "fill": "#000",
    "stroke": "#fff",
    "strokeSize": 1.5
}

TextImageType members

Member Type Required Description
TextImageType: A snippet of text. Defines font family and size, fill color, and outline stroke width and color.
fill Object, String The main fill color of the text. Allows Variable substitution.
size Object, Number The size in pixels to render the text. Allows Variable substitution.
stroke Object, String The color for the outline of the text. Allows Variable substitution.
strokeSize Object, Number The thickness in points for the outline of the text. Allows Variable substitution.
text Object, String The line of text to render. To format center-justifying text blocks, include \n sequences where you want lines to break. To search for these newlines in query parameter values, specify the URL-encoded %0A sequence. Allows Variable substitution.
transformation Transformation The Transformation type applied to the text. For example, you can Rotate the text.
type Enumeration Identifies the type of image, Text in this case.
typeface Object, String The font family to apply to the text image. This may be a URL to a TrueType or WOFF (v1) typeface, or a string that refers to one of the standard built-in browser fonts. Allows Variable substitution.

UrlImageType

An image loaded from a URL.

Download schema: url-image-type.json

Sample that specifies an image from a URL:

{
    "type": "URL",
    "url": "https://www.example.com/someImage.jpg"
}

UrlImageType members

Member Type Required Description
UrlImageType: An image loaded from a URL.
type Enumeration Identifies the type of image, URL in this case.
url Object, String The URL of the image. For details on supported image format types and several transformations, see Test images on-demand. Allows Variable substitution.

CircleShapeType

Defines a circle with a specified radius from its center point.

Download schema: circle-shape-type.json

Sample that represents a circle shape:

{
    "radius": 5,
    "center": [
        10,
        20
    ]
}

CircleShapeType members

Member Type Required Description
CircleShapeType: Defines a circle with a specified radius from its center point.
center Object, String The point of the center of the circle. Allows Variable substitution.
radius Object, String The radius of the circle measured in pixels. Allows Variable substitution.

PointShapeType

Defines coordinates for a single point, to help define polygons and rectangles. Each point may be an object with xand y members, or a two-element array.

Download schema: point-shape-type.json

Sample that represents a single point shape:

{
    "x": 10,
    "y": 20
}

Sample that represents the same data as a two-element array:

[
    10,
    20
]

PointShapeType members

Member Type Required Description
PointShapeType: Defines coordinates for a single point, to help define polygons and rectangles. Each point may be an object with xand y members, or a two-element array.
x Object, Number The horizontal position of the point, measured in pixels. Allows Variable substitution.
y Object, Number The vertical position of the point, measured in pixels. Allows Variable substitution.

PolygonShapeType

Defines a polygon from a series of connected points.

Download schema: polygon-shape-type.json

Sample that represents a polygon shape:

{
    "points": [
        [
            0,
            0
        ],
        [
            10,
            10
        ],
        [
            20,
            0
        ]
    ]
}

PolygonShapeType members

Member Type Required Description
PolygonShapeType: Defines a polygon from a series of connected points.
points PolygonShapeType.points[] Series of PointShapeType objects. The last and first points connect to close the shape automatically.
PolygonShapeType.points[]: Series of PointShapeType objects. The last and first points connect to close the shape automatically.
x Object, Number The horizontal position of the point, measured in pixels. Allows Variable substitution.
y Object, Number The vertical position of the point, measured in pixels. Allows Variable substitution.

RectangleShapeType

Defines a rectangle’s width and height relative to an anchor point.

Download schema: rectangle-shape-type.json

Sample that represents a rectangle shape:

{
    "width": 100,
    "height": 50,
    "anchor": [
        10,
        20
    ]
}

RectangleShapeType members

Member Type Required Description
RectangleShapeType: Defines a rectangle’s width and height relative to an anchor point.
anchor RectangleShapeType.anchor PointShapeType that specifies where the rectangle’s top left corner appears relative to that of the image in which it appears.
height Object, Number Extends the rectangle down from the anchor point. Allows Variable substitution.
width Object, Number Extends the rectangle right from the anchor point. Allows Variable substitution.
RectangleShapeType.anchor: PointShapeType that specifies where the rectangle’s top left corner appears relative to that of the image in which it appears.
x Object, Number The horizontal position of the point, measured in pixels. Allows Variable substitution.
y Object, Number The vertical position of the point, measured in pixels. Allows Variable substitution.

UnionShapeType

Identifies a combined shape based on a set of other shapes. You can use a full JSON object to represent a union or an array of shapes that describe it.

Download schema: union-shape-type.json

Sample that represents a shape composed of a RectangleShapeType and a CircleShapeType:

{
    "shapes": [
        {
            "width": 200,
            "height": 150,
            "anchor": [
                10,
                20
            ]
        },
        {
            "radius": 50,
            "center": [
                50,
                175
            ]
        }
    ]
}

Sample that represents the same data as an array:

[
    {
        "width": 200,
        "height": 150,
        "anchor": [
            10,
            20
        ]
    },
    {
        "radius": 50,
        "center": [
            50,
            175
        ]
    }
]

UnionShapeType members

Member Type Required Description
UnionShapeType: Identifies a combined shape based on a set of other shapes. You can use a full JSON object to represent a union or an array of shapes that describe it.
shapes Array The full set of component shapes to combine into the unified shape, either CircleShapeType, PolygonShapeType, or RectangleShapeType.

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

Error responses

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

This 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 this 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: 12/2/2019