Image Manager API 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.

  1. Upload or provide a link to an original (hi-res) image, along with the destination URL (target path).

  2. 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 the Image Manager API token provided in Luna Property Manager when the Image Manager rule is enabled on a site. The Luna-Token is required on all API calls.

    Example:

    Luna-Token: default-022335

  3. A link to the target path is added to the customer’s website for end users to access.

  4. As this new image is requested by end users, applied policies automatically create all the sizes and formats required.

For detailed information about acquiring a Luna-token, see the Image Manager Getting Started document.

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

Last modified: 3/22/2017