Image Manager API Data

This section shows you the data model for the Image Manager API. The sections are organized based the standard workflow through this API.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Member is required to be present, regardless of whether its value is empty or null.
Member is optional, and may be omitted in some cases.
Member is out of scope, and irrelevant to the specified interaction context. If you include the member in that context, it’s either ignored, or causes an error.

Policy

Allows you to create and manage your Image Manager policies. You use policies to create transformations, variations in image size and formats, to deliver the best image for the requesting application.

Download schema: policy.json

Sample GET response:

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

Policy Members

Member Type Required Description
breakpoints Policy.breakpoints The breakpoint widths to use to create derivative images.
hosts Array Hosts that are allowed for Composite image URLs.
id String Unique identifier for a policy, up to 64 alphanumeric characters including underscores or dashes.
output Policy.output Dictates the output quality (either quality or perceptualQuality) and formats that are created for each resized image. If unspecified, image formats are created to support all browsers at the default quality level (85), which includes formats such as WEBP, JPEG2000 and JPEG-XR for specific browsers.
postBreakpointTransformations Transformation Array Transformations applied to the source image after the images for the carousel’s main image view are created.
transformations Transformation Array Transformations applied to the source image.
variables Policy.variables[n] 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.

Member Type Required Description
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.

Member Type Required Description
allowedFormats Array The values of the allowed graphics file formats.
forcedFormats Array The values of the forced extra formats.
perceptualQuality Enumeration, Variable 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.
quality Integer, Variable The chosen quality of the output images. Using a quality value from 1–100 resembles JPEG quality across output formats.

Policy.variables[n]  

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.

Member Type Required Description
defaultValue String The default value of the variable if no query parameter is provided. It must be one of the enumOptions if any are provided.
enumOptions Policy.variables[n].enumOptions[n] 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[n].enumOptions[n]  

Optionally limits the set of possible values for a variable. References to an enum id insert a corresponding value.

Member Type Required Description
id String The unique identifier for each enum value, up to 50 alphanumeric characters.
value String The value of the variable when the id is provided.

Image

Collects information that describes an image.

Download schema: image.json

Sample GET response:

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

Image Members

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

ImageCollection

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

Download schema: image-collection-definition.json

Sample GET response:

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

ImageCollection Members

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

Video

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

Download schema: video.json

Video Members

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

Spin360

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

Download schema: spin-360.json

Spin360 Members

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

History

Provides date, user, and version information for your Image Manager policies.

Download schema: get-policy-history.json

Sample GET response:

{
    "itemKind": "POLICIESLOG",
    "items": [
        {
            "id": "thumbnail_policy",
            "dateCreated": "2015-06-09 15:41:37+0000",
            "policy": "{\"id\":\"grayscale\",\"transformations\":[{\"transformation\":\"Grayscale\"}],\"resolutions\":{\"widths\":[500]},\"currentVersion\":1}",
            "action": "UPSERT",
            "user": "jsmith"
        }
    ],
    "totalItems": 1
}

History Members

Member Type Required Description
itemKind Enumeration The type of Image Manager policy, in this case the POLICIESLOG.
items History.items[n] An array showing a history of your Image Manager policy changes.
totalItems Integer The total number of policies returned.

History.items[n]  

An array showing a history of your Image Manager policy changes.

Member Type Required Description
action Enumeration The action logged, either UPSERT or DELETE.
dateCreated String Date of the log entry in ISO–8601 extended notation format.
id String The ID of the policy.
policy String The policy’s state as a result of the change, represented as a JSON string.
user String The user who made the modification.
version Integer The version of the policy.

Acknowledgement

The type of operation performed on an Image Manager resource.

Download schema: operation-performed.json

Sample DELETE response:

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

Acknowledgement Members

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

Transformation

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

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

  • Blur: Applies a Gaussian blur to the image.

  • Composite: Applies another image to the image you are transforming (called the source image), either as an overlay or an underlay. The image that is underneath is visible in areas that are beyond the edges of the top image or that are less than 100% opaque. A common use of an overlay composite is to add a watermark.

  • Compound: An ordered combination of transformations to perform. Use to represent a sequence of transformations as a single transformation.

  • Crop: Cuts the image down to an area you specify. Use this transformation to describe the size and position of a box indicating the portion of the image to preserve.

  • FitAndFill: Uses aspect fitting to resize an image to the exact dimensions specified. This transformation then uses aspect fill on any remaining areas of the image.

  • Grayscale: Renders the image in shades of black, white, and gray.

  • Hsl: Simultaneously alters the hue, saturation, and lightness (HSL) of an image. Hue is the number of degrees that colors are rotated around the color wheel. Saturation is a multiplier to increase or decrease color saturation. Lightness is a multiplier to increase or decrease the lightness of an image.

  • MaxColors: Sets the maximum number of color in the image’s palette. Reducing the number of colors in an image can help reduce file size.

  • Opacity: Changes the opacity (transparency) of an image. Use Opacity to make an image more transparent. Values below 1.0 increase transparency; 0.0 is invisible. For images that have some transparency, values above 1.0 increase the opacity of the transparent portions.

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

  • Rotate: Rotates the image around its center by indicating the degrees of rotation. Positive values rotate clockwise; negative values rotate counter-clockwise.

  • Scale: Changes the image size relative to the starting size, expressed as a percentage of the width and height. You can scale width and height independently.

  • Trim: Automatically crops uniform backgrounds from the edges of an image.

  • UnsharpMask: Generates a sharper resulting image by creating a negative image mask of the original image, then combining that mask with the original image.

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

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

  • IfOrientation: Chooses a transformation depending on the orientation of the source image.

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

BackgroundColor

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

Download schema: background-color.json

Sample that changes background color:

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

BackgroundColor Members

Member Type Required Description
color String, Variable The hexadecimal CSS color value for the background.
transformation Enumeration Identifies this type of transformation, BackgroundColor in this case.

Blur

Applies a Gaussian blur to the image.

Download schema: blur.json

Blur Members

Member Type Required Description
sigma Number, Variable 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.
transformation Enumeration Identifies this type of transformation, Blur in this case.

Composite

Applies another image to the image you are transforming (called the source image), either as an overlay or an underlay. The image that is underneath is visible in areas that are beyond the edges of the top image or that are less than 100% opaque. A common use of an overlay composite is to add a watermark.

Download schema: composite.json

Sample that places one image on top of another:

{
    "transformation": "Composite",
    "image": [
        {
            "id": "/house/image1.jpg",
            "url": "http://www.example.com/house/image1.jpg",
            "policies": {
                ".auto": {
                    "sizes": {
                        "50": {
                            "date": "2016-03-22 13:05:59+0000",
                            "policyVersion": 1,
                            "status": "PASSED"
                        }
                    }
                }
            }
        }
    ],
    "xPosition": 0,
    "yPosition": 0,
    "gravity": "NorthWest",
    "placement": "Over",
    "scale": 0.5,
    "scaleDimension": "width"
}

Composite Members

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

Composite.image  

The image you want to apply to the source image.

Member Type Required Description
transformation Transformation If desired, the transformation to perform on the incoming image before adding it to the source image.
url String, Variable The URL of the image to apply to the source image.

Compound

An ordered combination of transformations to perform. Use to represent a sequence of transformations as a single transformation.

Download schema: compound.json

Sample that combines a sequence of transformations into a single transformation:

{
    "transformation": "Compound",
    "transformations": [
        {
            "color": "#ff00ff",
            "transformation": "BackgroundColor"
        },
        {
            "colours": 256,
            "transformation": "MaxColors"
        }
    ]
}

Compound Members

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

Crop

Crops an image.

Download schema: crop.json

Sample that crops an image:

{
    "transformation": "Crop",
    "width": 100,
    "height": 100,
    "xPosition": 0,
    "yPosition": 0,
    "gravity": "NorthWest"
}

Crop Members

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

FitAndFill

Use aspect fitting to resize an image to the exact dimensions specified. This transformation then uses aspect fill on any remaining areas of the image.

Download schema: fit-and-fill.json

FitAndFill Members

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

Grayscale

Restricts image color to shades of gray only.

Download schema: grayscale.json

Sample that restricts image color to shades of gray only:

{
    "transformation": "Grayscale",
    "type": "Rec601Luma"
}

Grayscale Members

Member Type Required Description
transformation Enumeration Identifies this type of transformation, Grayscale in this case.
type Enumeration, Variable The algorithm used to transform colors to grays, either Brightness, Lightness, Rec601, or the default Rec709.

Hsl

Simultaneously alters the hue, saturation, and lightness (HSL) of an image. Hue is the number of degrees that colors are rotated around the color wheel. Saturation is a multiplier to increase or decrease color saturation. Lightness is a multiplier to increase or decrease the lightness of an image.

Download schema: hsl.json

Sample that alters the hue, saturation, and lightness of an image:

{
    "transformation": "HSL",
    "hue": 0.0,
    "saturation": 1.0,
    "lightness": 1.0
}

Hsl Members

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

MaxColors

Set the maximum number of colors in the image’s palette. Reducing the number of colors in an image can help to reduce file size.

Download schema: max-colors.json

Sample that reduces the number of unique colors in an image:

{
    "transformation": "MaxColors",
    "colors": 256
}

MaxColors Members

Member Type Required Description
colours Integer, Variable The value representing the maximum number of colors to use with the source image.
transformation Enumeration Identifies this type of transformation, MaxColors in this case.

Opacity

Change the opacity (transparency) of an image. Use Opacity to make an image more transparent.

Download schema: opacity.json

Sample that affects the transparency of an image:

{
    "transformation": "Opacity",
    "opacity": 0.5
}

Opacity Members

Member Type Required Description
opacity Number, Variable Float used to multiply pixel alpha values. Values below 1.0 increase transparency; 0.0 is invisible. For images that have some transparency, values above 1.0 increase the opacity of the transparent portions.
transformation Enumeration Identifies this type of transformation, Opacity in this case.

Resize

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

Download schema: resize.json

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

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

Resize Members

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

Rotate

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

Download schema: rotate.json

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

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

Rotate Members

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

Scale

Change the image’s size to different dimensions relative to its starting size.

Download schema: scale.json

Sample that resizes an image to particular dimensions relative to the input image:

{
    "transformation": "Scale",
    "width": 0.5,
    "height": 0.5
}

Scale Members

Member Type Required Description
height Number, Variable Float multiple of input height.
transformation Enumeration Identifies this type of transformation, Scale in this case.
width Number, Variable Float multiple of input width.

Shear

Slants an image into a parallelogram, as a percent of starting dimension as represented in decimal format. At least one axis property is required. Shearing results in an image that’s the same size as the original. Empty areas are filled with transparent pixels so it’s often useful or necessary to follow this transformation with a backgroundColor transformation.

Download schema: shear.json

Sample that slants an image into a parallelogram, as a portion of starting dimension:

{
    "transformation": "Shear",
    "xShear": 0.2,
    "yShear": 0.1
}

Shear Members

Member Type Required Description
transformation Enumeration Identifies this type of transformation, Shear in this case.
xShear Integer, Variable The amount to shear along the x-axis.
yShear Integer, Variable The amount to shear along the y-axis.

Trim

Automatically crops uniform backgrounds from the edges of an image.

Download schema: trim.json

Trim Members

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

UnsharpMask

Generates a sharper resulting image by creating a negative image mask of the original image, then combining that mask with the original image.

Download schema: unsharp-mask.json

UnsharpMask Members

Member Type Required Description
gain Number, Variable The strength of the unsharp mask.
sigma Number, Variable The size of the unsharp mask.
threshold Number, Variable The threshold of the unsharp mask.
transformation Enumeration Identifies this type of transformation, UnsharpMask in this case.

IfDimension

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

Download schema: if-dimension.json

IfDimension Members

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

IfOrientation

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

Download schema: if-orientation.json

IfOrientation Members

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

Variable

References the name of a variable defined by the policy. Use this object to substitute preset values within transformations, or to pass in values dynamically using image URL query parameters.

Download schema: variable.json

Variable Members

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

Last modified: 12/12/2017