
Image Manager API v0
The original version of the Image Manager API.
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.
Who should use this API
The Image Manager API allows developers and architects to automate their entire imaging workflow to create, store, manage and deliver a rich image experience to every user, on any device, anywhere. To use this API, you should be familiar with HTTP requests and responses, and should read all sections and complete all tasks included in this Overview.
Getting started
To get started with this API:
Review Get Started for available tools.
Get help from the Akamai developer community and provide feedback. You can also contact your account representative for support. We want to hear from you!
Image Manager API concepts
This section provides a road map of all the conceptual objects you deal with when interacting with this API, and provides pointers to where you can learn more.
Automatic Transformations: Image Manager automatically transformation a website’s images by creating derivative images of various sizes and formats, and dynamically selecting the appropriate image when requested by an end user. Policies can be created to modify how a website’s images are transformed (see Policies).
On-Demand Transformations: Image Manager also supports on-demand transformations, using query string parameters that allow web developers to: specify which of the derivative images should be selected; force a particular output format to be selected or specify a different policy. For detailed information on query string parameters and examples, see the Resources section.
Policies: Policies are used to create variations (size and formats) to deliver the best image for the application. For detailed information on Image Manager policies and examples, see the Resources section.
Resources
The Image Manager API allows you to create, list, and modify policies, and organize images.
API summary
Operation | Method | Endpoint |
---|---|---|
Policies | ||
Get a Policy | GET | /imaging/ |
Add or Modify a Policy | PUT | /imaging/ |
Remove a Policy | DELETE | /imaging/ |
List Policies | GET | /imaging/ |
Get Policy History | GET | /imaging/ |
Images | ||
List Images to a Limit | GET | /imaging/ |
List Images Matching a URL | GET | /imaging/ |
Get an Image | GET | /imaging/ |
List a Policy’s Images | GET | /imaging/ |
Get a policy
Retrieve the policy definition by ID.
GET /imaging/
Example: /imaging/
Headers:
Luna-Token: ${Luna-Token}
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
id |
String | small |
Unique policy identifier. |
Status 200 application/json
Response:
{
"id": "watermark",
"transformations": [
{
"transformation": "Composite",
"image": { "url": "www.customer.com/watermark.png" },
"xPosition": 0,
"yPosition": 0,
"gravity": "SouthWest"
}
]
"resolutions": {
"interpolation": "Lanczos",
"widths": [ 500, 300 ]
},
"outputs": {
"defaults": { "quality": 90 }
}
}
Add or modify a policy
Update the policy definition for a given ID.
If you want to activate a policy on the staging network, add
-staging
to the hostname used for the request. For example, you
would use
https://akab-xxxxx-xxxxxxxxxx.imaging-staging.akamaiapis.net/imaging/v0/policies/mobile-policy
to activate a policy with an ID of mobile-policy
on staging. To
activate the same policy on production, you would use the following
hostname:
https://akab-xxxxx-xxxxxxxxxx.imaging.akamaiapis.net/imaging/v0/policies/mobile-policy
.
PUT /imaging/
Example: /imaging/
Content-Type: application/json
Headers:
Luna-Token: ${Luna-Token}
Request:
{
"resolutions": {
"widths": [ 240, 120, 60 ]
}
}
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
id |
String | small |
Unique policy identifier. |
Status 200 application/json
Response:
{
"operationPerformed": "UPDATED",
"description": "Policy {id} updated.",
"id": "{id}"
}
Remove a policy
Remove a policy by ID.
DELETE /imaging/
Example: /imaging/
Headers:
Luna-Token: ${Luna-Token}
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
id |
String | small |
Unique policy identifier. |
Status 200 application/json
Response:
{
"operationPerformed": "DELETED",
"description": "Policy {id} deleted.",
"id": "{id}"
}
List policies
Retrieve a list of all policy IDs.
GET /imaging/
Headers:
Luna-Token: ${Luna-Token}
Status 200 application/json
Response:
{
"totalItems": 2,
"itemKind": "POLICY",
"items": [
{ "id": ".auto" },
{ "id": "watermark" }
]
}
Get policy history
Retrieve policy history by policy ID.
The returned object contains a list of log entries with the following members:
Member | Type | Description |
---|---|---|
Required | ||
id |
String | Policy ID |
dateCreated |
String | Date of log entry |
policy |
String | The policy, represented as a JSON string |
action |
Enumeration | The action that was logged, either UPSERT or DELETE |
user |
String | The user who did the modification |
GET /imaging/
Example: /imaging/
Headers:
Luna-Token: ${Luna-Token}
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
id |
String | testpolicy |
Unique policy identifier. |
Status 200 application/json
Response:
{
"itemKind": "POLICIESLOG",
"items": [
{
"id": "testpolicy",
"dateCreated": "2015-06-09 15:41:37+0000",
"policy": "{\"id\":\"grayscale\",\"transformations\":[{\"transformation\":\"Grayscale\"}],\"resolutions\":{\"widths\":[500]},\"currentVersion\":1}",
"action": "UPSERT",
"user": "Akamai_Internal"
}
],
"totalItems": 1
}
List images to a limit
GET /imaging/
Example: /imaging/
Headers:
Luna-Token: ${Luna-Token}
Parameter | Type | Sample | Description |
---|---|---|---|
Optional | |||
limit |
String | 2 |
Specifies maximum number images to retrieve. |
Status 200 application/json
Response:
{
"totalItems": 2,
"itemKind": "IMAGE",
"items": [
{
"id": "/images/image1.png",
"url": "http://www.customer.com/images/image1.png",
"policies": {
".auto": {
"sizes": {
"50": {
"date": "2016-03-22 13:05:59+0000",
"policyVersion": 1,
"status": "PASSED"
}
}
}
}
},
{
"id": "/images/image2.png",
"url": "http://www.customer.com/images/image2.png",
"policies": {
"watermark": {
"sizes": {
"200": {
"date": "2016-03-23 13:05:59+0000",
"policyVersion": 1,
"status": "PASSED"
}
}
}
}
}
]
}
List images matching a URL
GET /imaging/
Example: /imaging/
Headers:
Luna-Token: ${Luna-Token}
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
url |
String | http://www.customer.com/image2.png |
URL to search for. |
Status 200 application/json
Response:
{
"totalItems": 1,
"itemKind": "IMAGE",
"items": [
{
"id": "/images/image2.png",
"url": "http://www.customer.com/images/image2.png",
"policies": {
"watermark": {
"sizes": {
"200": {
"date": "2016-03-23 13:05:59+0000",
"policyVersion": 1,
"status": "PASSED"
}
}
}
}
}
]
}
Get an image
Return detailed information about a specific image.
GET /imaging/
Example: /imaging/
Headers:
Luna-Token: ${Luna-Token}
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
id |
String | house/image1.jpg |
Identifies the image for which to retrieve metadata. |
Status 200 application/json
Response:
{
"id": "/house/image1.jpg",
"url": "http://www.customer.com/house/image1.jpg",
"policies": {
".auto": {
"sizes": {
"50": {
"date": "2016-03-22 13:05:59+0000",
"policyVersion": 1,
"status": "PASSED"
}
}
}
}
}
The object returned contains the following members:
Member | Type | Description |
---|---|---|
Required | ||
id |
String | Image ID. |
url |
String | Original URL of the image. |
orderedImageCollectionIds |
Array | Associated image collection IDs. |
tags |
Array | Associated image tags |
policies |
Object | Information about the policies that have been run with this image. |
The policies
section lists the following members for each applied
policy:
Member | Type | Description |
---|---|---|
Required | ||
date |
String | The date of when the policy was applied. |
policyVersion |
Number | The version of the policy. |
status |
Enumeration | The current processing status of this image with the associated policy. |
errors |
Array | List of errors that happened during processing with the associated policy. |
List a policy’s images
GET /imaging/
Example: /imaging/
Headers:
Luna-Token: ${Luna-Token}
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
policyId |
String | watermark |
Identifies the policy for which to get associated images. |
Status 200 application/json
Response:
{
"totalItems": 1,
"itemKind": "IMAGE",
"items": [
{
"id": "/images/image2.png",
"url": "http://www.customer.com/images/image2.png",
"policies": {
"watermark": {
"sizes": {
"200": {
"date": "2016-03-23 13:05:59+0000",
"policyVersion": 1,
"status": "PASSED"
}
}
}
}
}
]
}
Usage
This section provides an end-to-end guide of Image Manager’s main capabilities, demonstrating how to interact with each API interface:
- Image Manager API Workflow Integration
- Image Manager Resources
- Policies
Image Manager workflow
The following is the basic workflow for Image Manager.
Upload or provide a link to an original (hi-res) image, along with the destination URL (target path).
The image is transformed and stored in NetStorage, and is available at the target path specified on any hosts named in the property associated with the
Luna-token
header.NOTE: A
Luna-Token
header is theImage Manager API token
provided in Luna Property Manager when the Image Manager rule is enabled on a site. TheLuna-Token
is required on all API calls.Example:
Luna-Token:
default-022335
A link to the target path is added to the customer’s website for end users to access.
As this new image is requested by end users, applied policies automatically create all the sizes and formats required.
See Image Manager for detailed information about acquiring a Luna-token.
Image Manager API resources
See Image Manager API Concepts to learn more about how these objects relate to each other. For information on specific use cases, the following table summarizes all of the basic actions the API enables, along with their corresponding combinations of methods and endpoints.
Policy endpoints
Action | Operation | API Endpoint |
---|---|---|
Get a policy | GET | /imaging/v0/policies/{id} |
Add or modify a policy | PUT | /imaging/v0/policies/{id} |
Remove a policy | DELETE | /imaging/v0/policies/{id} |
List policies | GET | /imaging/v0/policies |
Get policy history | GET | /imaging/v0/policies/history/{id} |
Images endpoints
Action | Operation | API Endpoint |
---|---|---|
List images | GET | /imaging/v0/images |
List images to a limit | GET | /imaging/v0/images{?limit} |
List images matching a URL | GET | /imaging/v0/images{?url} |
Get an image | GET | /imaging/v0/images/{id} |
List a policy’s images | GET | /imaging/v0/images{?policyId} |
Query string parameter
For on-demand transformations, the following query string parameters can be added to image URLs on the website that specify how an image is returned, including:
- Requests for a specific browser type
- Requests for a specific image width (pixels)
- Requests for a policy change
- Combining query string parameters
Member | Type | Description |
---|---|---|
Optional | ||
imformat |
String | Requests a specific browser type. Browser types include: chrome , ie , safari , generic . Note that by default, Image Manager detects the browser and returns the appropriate image. |
imwidth |
String | Requests an image with a specific width. |
impolicy |
String | Request a specific image policy to be applied. |
impolicy , imwidth , imformat |
String | Combine query parameters to perform multiple transformations with a single request. |
Query string parameter examples
The following examples are variations of URLs you can form, and are not valid link targets.
www.customer.com/assets/images/image001.jpg?imformat=safari
: Returns the best image, in all format types (JPG, PNG, GIF, WEBP, JXR, and JP2) for the Safari browser.www.customer.com/assets/images/image001.jpg?imwidth=300
: Returns the 320px image, which is the next size up from 300px specified in the policy.www.customer.com/assets/images/image001.jpg?impolicy=watermark
: Combines the two images and returns a composite image.www.customer.com/assets/images/image001.jpg?impolicy=watermark&imwidth=300&imformat=safari
: Returns a composite of the image in format best for Safari, with the company logo, at 320px (closest width based on policy).
Policies
An Image Manager policy is a set of specifications (see Policy Specifications) that is applied to a derivative image. Policies can contain information about an image’s size for varying screens, output formats (WebP, JPEG, and PNG), and image opacity manipulation such a watermark. After a policy is applied to a derivative image, Image Manager uses the policy to transform the image. For examples of Image Manager policies, see Policy Examples.
NOTE: It is very important to understand that the policy name and version are contained in the cache key for images. Be aware that any policy modification will result in an invalidation of any images using the policy. For the default policy, this can mean an invalidation of all images. It is recommended to test out any policy changes in Akamai Staging, then once finalized, modify the policy in Production.
Automatic image transformations (real-time) policy
A real-time policy works directly on a customer’s origin. The output of a real-touch policy produces many images. If a custom policy is not specified, the default policy (.auto) is applied to the image.
Real-time default policy
The real-time default policy, .auto is automatically created, and is the policy applied to all images unless a specific policy is selected. The default policy can be modified to select different image transformations.
The .auto policy specifications are as follows:
- Quality is 80
- Widths in pixels are 5000, 2048, 1024, 640, and 320
Definition: {} (use all defaults)
NOTE: The .auto policy cannot be deleted.
Policy specifications
The following policy specifications are used to compose Real-Time policies. For detailed information about using policy operations, see the Resources section.
Member | Type | Description |
---|---|---|
Optional | ||
transformations |
String | Set of base specifications (Image Transformations) to apply to the input image. If unspecified, no operations are performed. A complete set of base specifications can be found in the Image Transformations section of the IM API Reference. |
resolutions |
String | Object that dictates the set of resize operations that will be applied to the image, after the transformations have been applied. resolutions contain the following widths : [5000 , 2048 ,1024 ,640 ,320 ]. |
outputs |
String | Object that 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 (80), which includes formats such as WEBP, JPEG2000 and JPEG-XR for specific browsers. |
Quality vs. perceptual quality
The outputs
object offers two ways to specify output quality:
quality
and perceptualQuality
. The default is quality
80. When
specifying outputs, use the following guidelines:
Quality (default): Using a
quality
value from 1–100 resembles JPEG quality across output formats. The default is 80.Perceptual Quality: Perceptual quality tunes each image format’s quality parameter dynamically based on the human-perceived quality of the output image.
This can result in better byte savings (as compared to using regular quality) as many images can be encoded at a much lower quality without compromising perception of the image. In addition, certain images may need to be encoded at a slightly higher quality in order to maintain human-perceived quality.
If selected, the presets available for perceptual quality are as follows:
high
: Approximately 95 JPEG quality or higher. When perceived quality is the most important factor. This will result in minimal byte savings compared to other presets.mediumHigh
: (default) Recommended setting for most cases. A good balance of quality and byte savings appropriate for displaying on the web. Approximately 85–95 JPEG quality.medium
: Approximately 75–85 JPEG quality.mediumLow
: Approximately 65–75 JPEG quality. When byte savings is the most important actor.low
: Approximately 65 JPEG quality or lower. This setting is mainly for placeholders, image preloading, and so forth.
Policy examples
Example 1: Overrides the default widths to have only two sizes (120 and 60 pixels wide), default quality.
{
"resolutions": {
"widths": [ 120, 60 ]
}
}
Example 2: Overrides the default widths and sets a specific output quality of 85.
{
"resolutions": {
"widths": [ 640, 320 ]
},
"outputs": {
"defaults": { "quality": 85 }
}
}
Example 3: Overrides the default widths and sets a specific perceptual quality.
{
"resolutions": {
"widths": [ 640, 320 ]
},
"outputs": {
"defaults": {
"perceptualQuality": "mediumHigh"
}
}
}
Example 4: Adds a watermark to the source image in the lower left hand corner, and uses default resolutions and outputs.
{
"transformations": [
{
"transformation": "Composite",
"image": { "url": "www.customer.com/watermark.png" },
"xPosition": 0,
"yPosition": 0,
"gravity": "SouthWest"
}
]
}
Image transformations
The common constructs for image transformations are as follows:
Gravity: A string to represent eight cardinal directions and a center. Use Gravity when describing placement or regions of an image, including:
- North
- NorthEast
- NorthWest
- South
- SouthEast
- SouthWest
- Center
- East
- West
Gravity Example:
{
"transformation": "Crop",
"width": 60,
"height": 70,
"gravity": "NorthWest"
}
Image: A JSON object with a URL that points to an image resource and a transformation object that should be applied to that image.
Image Example:
{
"url": "imageUrl", // Required.
"transformation": transformationObject // Optional.
}
Transformations: A JSON object that specifies parameters for that type of transformation. All transformation object JSONs follow a similar pattern.
Transformation Example:
{
"transformation": "TransformationName",
// ... Specific parameters for that type of transformation
}
BackgroundColor: Place a transparent image on a set background color. Color is specified in the typical CSS hexadecimal format.
BackgroundColor Example:
{
"transformation": "BackgroundColor",
"color": "#ff00ff" // Required. The color of the background.
}
Composite: Places one image on top of another.
Composite Example:
{
"transformation": "Composite",
"image": imageObject, // Required. Image to compose.
"xPosition": 0, // Optional. Default = 0. Integer x position.
"yPosition": 0, // Optional. Default = 0. Integer y position.
"gravity": "gravityString", // Optional. Default = "NorthWest". Gravity string.
"placement": "Over", // Optional. Default = "Over". Whether to place "image"
// "Over" or "Under" the image coming in to
// the transformation.
"scale": 0.5, // Optional. Default is unset. If set, the specified image
// is scaled to this fraction of the base image.
"scaleDimension": "width" // Optional. Default = "width". The dimension of the base
// image to scale to. "width" or "height".
}
Compound: An ordered combination of other transformations to perform. It is used for representing a sequence of transformations as a single transformation.
Compound Example:
{
"transformation": "Compound",
"transformations": [array, of, transformation, objects] // Optional.
}
Crop: Crops an image.
Crop Example:
{
"transformation": "Crop",
"width": 100, // Required. The width of the area to crop.
"height": 100, // Required. The height of the area to crop.
"xPosition": 0, // Optional. Default = 0. The X offset of where to crop.
"yPosition": 0, // Optional. Default = 0. The Y offset of where to crop.
"gravity": "NorthWest" // Optional. Default = "NorthWest". Gravity for placement.
}
HSL: Simultaneously alters the hue, saturation, and lightness of an image. Hue is the number of degrees that colors are rotated around the color wheel. Saturation is a multiplier to increase or decrease color saturation. Lightness is a multiplier to increase or decrease the lightness of an image.
HSL Example:
{
"transformation": "HSL",
"hue": 0.0, // Optional. Default = 0.0. Float of the number of degrees to rotate
// colours around the colour wheel.
"saturation": 1.0, // Optional. Default = 1.0. Multiplier to adjust colour saturation.
"lightness": 1.0 // Optional. Default = 1.0. Multiplier to adjust image lightness.
}
Grayscale: Restricts image color to shades of gray only. The available options of grayscale include:
- Rec601Luma
- Rec601Luminance
- Rec709Luma
- Rec709Luminance
- Brightness
- Lightness
Grayscale Example:
{
"transformation": "Grayscale",
"type": "grayscaleAlgorithm" // Optional. Advanced. Default = "Rec709Luma".
// The algorithm used to transform colours to grays.
}
MaxColors: Reduces the number of unique colors in an image to a specified amount.
MaxColors Example:
{
"transformation": "MaxColors",
"colors": 256 // Required. Integer of colors to which the input image should be reduced.
}
Opacity: Affects the opacity (transparency) of an image. Use Opacity to make an image more transparent.
Opacity Example:
{
"transformation": "Opacity",
"opacity": 0.5 // Required. Float used to multiply pixel alpha values.
}
Resize: Resizes an image to a particular, absolute dimension. The following options are available using the type string:
- normal
- upsize
- downsize
The following aspect preservation modes are available with the aspect member:
- ignore
- fit (default)
- fill
It is required that either width or height aspect members, or both be present. If the requirement is not met, the aspect is ignored and the default aspect preservation mode (fit) is assumed; the image is resized with the missing dimension chosen to preserve the input image aspect.
Resize Example:
{
"transformation": "Resize",
"width": 100, // It is required that one or both of "width"
"height": 100, // and "height" be present.
"aspect": "fit", // Optional. Default is "fit".
"type": "normal" // Optional. Default is "normal".
}
Rotate: The “Rotate” transformation will rotate an image clockwise some arbitrary number of degrees. The resulting image will be resized to fit the entire rotated image. Empty areas will be filled with transparent pixels so it’s often useful or necessary to follow this transformation with a “BackgroundColor” transformation.
Rotate Example:
{
"transformation": "Rotate",
"degrees": 45.3 // Required. Number of degrees to rotate the image.
}
Scale: Resizes an image to particular dimensions relative to the input image.
Scale Example:
{
"transformation": "Scale",
"width": 0.5, // Required. Float multiple of input width.
"height": 0.5 // Required. Float multiple of input height.
}
Shear: The “Shear” transformation will shear an image along its X and/or Y axis. The resulting image will be resized to fit the entire sheared image. Empty areas will be filled with transparent pixels so it’s often useful or necessary to follow this transformation with a “BackgroundColor” transformation.
Shear Example:
{
"transformation": "Shear",
"xShear": 0.2, // It is required that one or both of "xShear" and "yShear" be present.
"yShear": 0.1 // The amount to shear along a particular axis.
}
Errors
The following shows a typical response when an error condition (4xx return code) occurs:
{
"type": "",
"title": "Validation Exception",
"detail": "The value 'abcdefghijklmnopqrstuvwxyz0123456789' of property 'name' is too long. Max length is 30 characters.",
"instance": "PUT - https://imaging.api.akamai.com/imaging/v0/policies/abcdefghijklmnopqrstuvwxyz0123456789",
"httpStatus": 400
}
Last modified: 12/14/2016