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.

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.
widths Array Specifies each integer breakpoint width value.
Policy.output: Dictates the output quality (either quality or perceptualQuality) and formats that are created for each resized image. If unspecified, image formats are created to support all browsers at the default quality level (85), which includes formats such as WEBP, JPEG2000 and JPEG-XR for specific browsers.
allowedFormats Array The values of the allowed graphics file formats.
forcedFormats Array The values of the forced extra formats.
perceptualQuality Enumeration The perceptual quality to use when comparing resulting images, which overrides the quality setting. Perceptual quality tunes each image format’s quality parameter dynamically based on the human-perceived quality of the output image. This can result in better byte savings (as compared to using regular quality) as many images can be encoded at a much lower quality without compromising perception of the image. In addition, certain images may need to be encoded at a slightly higher quality in order to maintain human-perceived quality. Values are tiered high, mediumHigh, medium, mediumLow, or low.
perceptualQuality Variable As an alternative to a static value, specify a predefined Variable object.
quality Integer The chosen quality of the output images. Using a quality value from 1–100 resembles JPEG quality across output formats.
quality Variable As an alternative to a static value, specify a predefined Variable object.
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.
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.
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 map The policies applied to this image.
url String The URL of the image.

ImageCollection

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

Download schema: image-collection-definition.json

Sample GET response:

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

ImageCollection Members

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

Video

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

Download schema: video.json

Video Members

Member Type Required Description
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.
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 The hexadecimal CSS color value for the background.
color Variable As an alternative to a static value, specify a predefined Variable object.
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 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.
sigma Variable As an alternative to a static value, specify a predefined Variable object.
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 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.
gravity Variable As an alternative to a static value, specify a predefined Variable object.
image Composite.image The image you want to apply to the source image.
placement Enumeration Where to place the specified image, either Over or Under the existing image. The default is Over.
placement Variable As an alternative to a static value, specify a predefined Variable object.
scaleDimension Enumeration The dimension, either width or height, of the source image to scale.
scaleDimension Variable As an alternative to a static value, specify a predefined Variable object.
scale Number 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.
scale Variable As an alternative to a static value, specify a predefined Variable object.
transformation Enumeration Identifies this type of transformation, Composite in this case.
xPosition Integer The x-axis position of the image to apply.
xPosition Variable As an alternative to a static value, specify a predefined Variable object.
yPosition Integer The y-axis position of the image to apply.
yPosition Variable As an alternative to a static value, specify a predefined Variable object.
Composite.image: The image you want to apply to the source image.
transformation Transformation If desired, the transformation to perform on the incoming image before adding it to the source image.
url String The URL of the image to apply to the source image.
url Variable As an alternative to a static value, specify a predefined Variable object.

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 If cropping an area outside of the existing canvas, expands the image canvas.
allowExpansion Variable As an alternative to a static value, specify a predefined Variable object.
gravity Enumeration 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.
gravity Variable As an alternative to a static value, specify a predefined Variable object.
height Integer The number of pixels to crop along the y axis.
height Variable As an alternative to a static value, specify a predefined Variable object.
transformation Enumeration Identifies this type of transformation, Crop in this case.
width Integer The number of pixels to crop along the x axis.
width Variable As an alternative to a static value, specify a predefined Variable object.
xPosition Integer The x-axis position of the image to crop from.
xPosition Variable As an alternative to a static value, specify a predefined Variable object.
yPosition Integer The y-axis position of the image to crop from.
yPosition Variable As an alternative to a static value, specify a predefined Variable object.

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 The height value for the resized image.
height Variable As an alternative to a static value, specify a predefined Variable object.
transformation Enumeration Identifies this type of transformation, FitAndFill in this case.
width Integer The width value for the resized image.
width Variable As an alternative to a static value, specify a predefined Variable object.

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 The algorithm used to transform colors to grays, either Brightness, Lightness, Rec601, or the default Rec709.
type Variable As an alternative to a static value, specify a predefined Variable object.

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 Float of the number of degrees to rotate colors around the color wheel.
hue Variable As an alternative to a static value, specify a predefined Variable object.
lightness Number The amount of lightness, between 0 and 1.
lightness Variable As an alternative to a static value, specify a predefined Variable object.
saturation Number The amount of saturation, between 0 and 1.
saturation Variable As an alternative to a static value, specify a predefined Variable object.
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 The value representing the maximum number of colors to use with the source image.
colours Variable As an alternative to a static value, specify a predefined Variable object.
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 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.
opacity Variable As an alternative to a static value, specify a predefined Variable object.
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 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.
aspect Variable As an alternative to a static value, specify a predefined Variable object.
height Integer The height to resize the source image to.
height Variable As an alternative to a static value, specify a predefined Variable object.
transformation Enumeration Identifies this type of transformation, Resize in this case.
type Enumeration Sets constraints for the image resize. Select normal to resize in all cases, either increasing or decreasing the dimensions. Select downsize to ignore this transformation if the result would be larger than the original. Select upsize to ignore this transformation if the result would be smaller.
type Variable As an alternative to a static value, specify a predefined Variable object.
width Integer The width to resize the source image to.
width Variable As an alternative to a static value, specify a predefined Variable object.

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 The value to rotate the image by. Positive values rotate clockwise; negative values rotate counter-clockwise.
degrees Variable As an alternative to a static value, specify a predefined Variable object.
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 Float multiple of input height.
height Variable As an alternative to a static value, specify a predefined Variable object.
transformation Enumeration Identifies this type of transformation, Scale in this case.
width Number Float multiple of input width.
width Variable As an alternative to a static value, specify a predefined Variable object.

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 The amount to shear along the x-axis.
xShear Variable As an alternative to a static value, specify a predefined Variable object.
yShear Integer The amount to shear along the y-axis.
yShear Variable As an alternative to a static value, specify a predefined Variable object.

Trim

Automatically crops uniform backgrounds from the edges of an image.

Download schema: trim.json

Trim Members

Member Type Required Description
fuzz Number The fuzz tolerance of the trim, a value between 0 and 1 that determines the acceptable amount of background variation before trimming is stopped.
fuzz Variable As an alternative to a static value, specify a predefined Variable object.
padding Integer The amount of padding in pixels to add to the trimmed image.
padding Variable As an alternative to a static value, specify a predefined Variable object.
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 The strength of the unsharp mask.
gain Variable As an alternative to a static value, specify a predefined Variable object.
sigma Number The size of the unsharp mask.
sigma Variable As an alternative to a static value, specify a predefined Variable object.
threshold Number The threshold of the unsharp mask.
threshold Variable As an alternative to a static value, specify a predefined Variable object.
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 A no-op transformation, by default.
dimension Enumeration The dimension to use to select the transformation, either height, width, or both.
dimension Variable As an alternative to a static value, specify a predefined Variable object.
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 The value to compare against the source image dimension.
value Variable As an alternative to a static value, specify a predefined Variable object.

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: 7/2/2018