Learn more:

• Image Manager

• Reporting API

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

Overview

Image and Video 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 API offers 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 and Video 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 and Video Manager, and set the access level to read-write.

• Enable Image and Video 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 API token to apply a corresponding policy, use the imageManager behavior in PAPI.

• Disable any behaviors that are incompatible with Image and Video 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:

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 and Video Manager concepts

This section provides information about common concepts.

• Preset Transformations: Image and Video 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 and Video 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 policy.

• API Key: Like other Akamai APIs, this 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 and Video Manager behavior in your Property Manager configuration that applies to the set of images you’re working on.

• Policy: A 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 and Video Manager transforms the image based on the information in that policy.

• Default Policy: Image and Video 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 the policy 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 and Video 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:

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

Several transformations may specify these types of images:

Several transformations may specify these types of shapes:

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 and Video Manager API allows you to create, list, and modify policies, and organize images.

Follow this basic workflow to create a custom policy:

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

2. Get the Luna-Token header generated once Image and Video 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 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 a 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.

List policies

Returns a list of all policies using a specific instance of the Image and Video Manager behavior.

Luna-Token: default-022335

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

Get a policy

Returns a specific policy assigned to the selected API key.

Luna-Token: default-022335

{
    "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"
            }
        }
    ]
}

Create or modify a policy

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

Luna-Token: default-022335

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

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

Remove a policy

Delete a specific policy ID.

Luna-Token: default-022335

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

Get policy history

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.

Luna-Token: default-022335

{
    "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"
        }
    ]
}

List images

List a policy’s images.

Luna-Token: default-022335

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

Get an image

Returns a specific image.

Luna-Token: default-022335

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

List image collections

Lists all image collections, unless you set a limit.

{
    "itemKind": "IMAGECOLLECTION",
    "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"
                    }
                ]
            }
        }
    ]
}

Create a new image collection

Create a new image collection.

{
    "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"
                ]
            }
        ]
    }
}

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

Get an image collection

Returns the values for the image collection you specify.

{
    "id": "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"
                ]
            }
        ]
    }
}

Update an image collection

Update an image collection.

{
    "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"
                ]
            }
        ]
    }
}

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

Remove an image collection

Delete a specific image collection.

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

Get image collection history

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

{
    "itemKind": "IMAGECOLLECTIONHISTORY",
    "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"
                    }
                ]
            }
        }
    ]
}

List log details

Returns a list of image or video logs for the transformations requested in the past three days.

Luna-Token: default-022335

{
    "itemKind": "LOGDETAILS",
    "totalItems": 2,
    "items": [
        {
            "url": "http://www.customer.com/video.mp4",
            "policyId": "videoPolicy",
            "size": 854,
            "transformationType": "REALTIME",
            "status": "PASSED",
            "startTime": "2020-01-29 02:45:34",
            "completeTime": "2020-01-29 02:45:36"
        },
        {
            "url": "http://www.customer.com/video.mp4",
            "policyId": "videoPolicy",
            "size": 854,
            "transformationType": "OFFLINE",
            "status": "PASSED",
            "startTime": "2020-01-29 02:45:37",
            "completeTime": "2020-01-29 02:45:39",
            "pendingTime": "2020-01-29 02:45:36"
        }
    ]
}

List error details

Returns a list of image or video errors for the transformations requested in the past three days.

Luna-Token: default-022335

{
    "itemKind": "LOGDETAILS",
    "totalItems": 1,
    "items": [
        {
            "url": "http://www.customer.com/video.mp4",
            "policyId": "videoPolicy",
            "size": 854,
            "transformationType": "REALTIME",
            "reason": "BYTES",
            "threshold": 268435456,
            "actual": 276134947,
            "status": "FAILED",
            "startTime": "2020-04-13 06:20:06",
            "completeTime": "2020-04-13 06:20:07"
        }
    ]
}

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:

Policy

Specifies details for each policy, such as transformations to apply and variations in image size and formats.

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

Image

Collects information that describes an image.

Download schema: image.json

Sample GET response:

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

Image members

ImageCollection

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

Download schema: image-collection-definition.json

Sample GET response:

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

ImageCollection members

Video

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

Download schema: video.json

Video members

Spin360

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

Download schema: spin-360.json

Spin360 members

History

Provides date, user, and version information for your 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

Acknowledgement

The type of operation performed on an Image and Video Manager resource.

Download schema: operation-performed.json

Sample DELETE response:

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

Acknowledgement members

Transformation

Transformations are tools 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

BackgroundColor

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

Download schema: background-color.json

Sample that changes background color:

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

BackgroundColor members

Blur

Applies a Gaussian blur to the image.

Download schema: blur.json

Blur members

Composite

Applies another image to the 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

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

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

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

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 and Video 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

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

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

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

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

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

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

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

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

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

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

RelativeCrop

Shrinks or expands an image relative to the image’s specified dimensions. Image and Video 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

Resize

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

Download schema: resize.json

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

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

Resize members

Rotate

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

Download schema: rotate.json

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

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

Rotate members

Scale

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

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

Trim

Automatically crops uniform backgrounds from the edges of an image.

Download schema: trim.json

Trim members

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 and Video Manager combines the unsharp mask with the source image to create an image perceived as clearer.

Download schema: unsharp-mask.json

UnsharpMask members

IfDimension

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

Download schema: if-dimension.json

IfDimension members

IfOrientation

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

Download schema: if-orientation.json

IfOrientation members

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

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

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

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

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

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

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

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

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

Log

Lists the image or video logs pertaining to transformation tasks in the last 3 days.

Download schema: get-image-video-logs.json

Sample GET response:

{
    "itemKind": "LOGDETAILS",
    "totalItems": 2,
    "items": [
        {
            "url": "http://www.customer.com/video.mp4",
            "policyId": "videoPolicy",
            "size": 854,
            "transformationType": "REALTIME",
            "status": "PASSED",
            "startTime": "2020-01-29 02:45:34",
            "completeTime": "2020-01-29 02:45:36"
        },
        {
            "url": "http://www.customer.com/video.mp4",
            "policyId": "videoPolicy",
            "size": 854,
            "transformationType": "OFFLINE",
            "status": "PASSED",
            "startTime": "2020-01-29 02:45:37",
            "completeTime": "2020-01-29 02:45:39",
            "pendingTime": "2020-01-29 02:45:36"
        }
    ]
}

Log members

Errors

This section shows you how to handle various kinds of errors the Image and Video 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 uses the application/api-problem+json content type.

This example shows an error response when the property name exceeds the maximum length of 30 characters. The type value may be empty in some cases.

{
    "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

This section lists the full range of response codes the API may generate.