Dynamic Media API reference

Using the Dynamic Media API

Dynamic Media allows you to manipulate images on the fly, rendering any variant from a single master image. It uses a simple URL based API that allows you to transform images, including resizing, rotating and color correction.

You can dynamically manipulate any image using the parameters available, just by appending these parameters to the end of the URL. In the following example the image width is set to 300 pixels:

 https://i1.adis.ws/i/ampproduct/twofriends?w=300

You'll often want to combine multiple parameters. For example, to set the image width and flip the image vertically:

 https://i1.adis.ws/i/ampproduct/twofriends?w=300&flipv=true

The reference below shows the parameters that are available to you for manipulating images and sets. You can try out most of these features on the Dynamic Media playground interactive documentation area. For more information about manipulating video with Dynamic Media, see the playground video section.

Image Transformation Features

Feature Parameter Description
width
w Sets the width of the image. If you only provide the width, the height will be calculated to maintain the aspect ratio.

Parameter example: exampleimage?w = 200
height
h Sets the height of the image. If you only provide the height, the width will be calculated to maintain the aspect ratio.

Parameter example: exampleimage?h=400
quality
qlt Sets the compression quality of the image, this is a percentage 0-100. JPEGs are lossy, PNGs are lossless but are compressed with zlib.
Parameter example: exampleimage?qlt=80
scale mode
sm Indicates how to position the image if it does not fit exactly to the width and height specified.
  • c Crop to Fit
  • s Stretch
  • tl Top left
  • tc Top center
  • tr Top right
  • ml Middle left
  • mc (Default) Middle center
  • mr Middle right
  • bl Bottom left
  • bc Bottom center
  • br Bottom right
  • aspect Aspect ratio.

Parameter example: exampleimage?w=256&sm=aspect&aspect=16:9
scale mode- resize edge
sm=edge Resizes the image to a specified width or height, or to the smallest or largest edge of the image.
resize.edge and resize.edge.length must be specified.
resize.edge = w, h, largest or smallest
rezize.edge.length= {value in pixels}

Parameter examples:
exampleimage?sm=edge&resize.edge=w&resize.edge.length=250
Sets the width to the value of resize.edge.length and adjusts the height to maintain the aspect ratio.

exampleimage?sm=edge&resize.edge=h&resize.edge.length=250
Sets the height to resize.edge.length and adjusts the width to maintain the aspect ratio.

exampleimage?sm=edge&resize.edge=largest&resize.edge.length=375
Resize the image so that the largest side is set to the value of resize.edge.length and maintain the aspect ratio.

exampleimage?sm=edge&resize.edge=smallest&resize.edge.length=375
Resize the image so that the smallest side is set to the value of resize.edge.length and maintain the aspect ratio.
scale fit scaleFit Specifies how to position the area to be cropped when using sm.
  • center (default)
  • poi  Crop using the specified point of interest focal point
point of interest
poi The focal point of an image to use when it is resized and cropped.
Takes 4 parameters: x, y, w and h. x and y represent the top left of the focal point as a percentage of the image width and height. Width and height are the width and height of the focal point as a percentage of the image width and height.
Example:
https://i1.adis.ws/i/ampproduct/Hero-Banner-720-model2?w=320&h=480&sm=c&poi= 0.743636237250434,0.,0.32362459546925565, 0.1388888888888889 0&scaleFit=poi
resize algorithm filter The algorithm to use when the image is resized.
  • q Quadratic
  • s Sinc
  • l (Default) Lanczos
  • p  Point
  • c Cubic
  • h Hermite
upscale upscale true/ false/ padd
Indicates if the system can scale the image to be bigger than the original input. If set to padd the image will be drawn on top of a canvas with the size given. The alignment of the image is set using sm. The background colour of the canvas is set using bg.
max width maxw Sets the maximum width for the image returned. Can be specified at the account level
max height maxh Sets the maximum height for the image returned. Can be specified at the account level

Cropping and rotating

Feature Parameter Description
crop
crop Cuts out a section of the image, the coordinates are specified as x,y,w,h.
x is the offset from the top left of the image. y is the offset from the top of the image. w is the width of the selection. h is the height of the selection.
Example: myimage?crop=0,0,500,500 will get the first 500x500 pixels from the image.
This command is applied after any resize so the coordinates are relative to the resized image.
edge Crop ecrop Takes 4 parameters: left, top, right, bottom to crop from each edge of the image.
Example: myimage?ecrop=250,250,250,250 will crop 250 pixels from each edge of the image
pre-crop pcrop Same as crop except it does the crop before any resize event. Therefore the coordinates are relative to the original image size.
pre- edge crop pecrop Same as ecrop but crops from the edge of the image before any resize event.
Example:
pecrop=0,0,0,100 will take 100px from the bottom edge of the original image
rotate
rotate Rotate an image by a specified number of degrees. The rotate is applied after the effect of any resize parameters.
Example: https://i1.adis.ws/i/ampproduct/twofriends?rotate=90

Optional parameter: rgb color. Rotating by an angle that is not a multiple of 90 degrees will expose some pixels underneath the image. You can specify a color for the exposed pixels:
Example:
https://i1.adis.ws/i/ampproduct/twofriends?rotate=80,rgb(30,50,90)
flip
fliph
flipv
Flips the image horizontally, vertically or both.
Example:
https://i1.adis.ws/i/ampproduct/twofriends?fliph=true


File manipulation

Feature Parameter Description
format
fmt = jpg
fmt = png
Sets the format of the image, if this is not specified the format will be the same as the original. Setting the image extension will also change the format.
Supported formats include:jpg,png, gif, bmp, webp. Note that webp is not supported on certain browsers.

Parameter example
myimage?fmt=png
myimage.png
dots per inch
dpi Changes the image resolution. If this param is not specified the image will be returned in the DPI it was originally created in.
dpi algorithm dpifilter Specifies the resampling algorithm to use when changing the DPI.
  • q  Quadratic
  • s  Sinc
  • l  (Default) Lanczos
  • p  Point
  • c  Cubic
strip strip Removes commands and meta data from the image. true or false. This is true by default.


Image adjustments

Feature Parameter Description
chroma subsampling fmt.jpeg.chroma Chroma subsampling is a process which bases image sampling on brightness rather than colour to take advantage of how the human eye works. Generally this affects colours and contrasts such as red and black.

Dynamic Media has Chroma Subsampling turned on by default to enhance performance and lower file size media. On is: fmt.jpeg.chroma=2,1,1. This can be turned off with the following setting: fmt.jpeg.chroma=1,1,1.

Note that turning this off will result in your media being served at a larger file size, so you may wish to adjust the quality setting to compensate
color space cs Changes the colorspace used for the image. Supported values:
  • rgb RGB
  • rgba RGBA
  • srgb SRGB
  • gray Gray
  • cmyk CMYK
  • ohta OHTA
  • lab LAB
  • xyz  XYZ
  • hsb Hue, saturation, brightness
  • hsl Hue, saturation, lightness
sharpen
unsharp Sharpens the image with an unsharp mask.
Structure: unsharp={radius},{sigma},{amount},{threshold}

Parameters:
Radius: Gaussian filter radius.(0 – 5), if 0 the system will select an appropriate value.
Sigma: Gaussian standard deviation. (0.01 – 5)
Amount: The percentage difference. Can be greater than 100%.(1-300)
Threshold: The threshold used to changed the brightness levels (0 to 255)
Parameter example: myImage?unsharp=2,1,160,0
composite mode cm When an image is applied on top of a background colour this defines the composite operator.
  • over  (default)
  • colo 
  • dark 
  • diff 
  • light 
  • multi 
  • cout 
  • cover 
image background
bg This will set the background colour of the image. It only has an effect when the image is padded or the original image is transparent. Example: https://i1.adis.ws/i/ampproduct/shoe-image?bg=rgb(0,0,255)
palette size fmt.png.palettesize Sets the colour palette size for a png image. Requires fmt.png.indexed=true
The default palette size is 256. Note the image has to be served in png format. Should notably reduce filesize of asset.
dither fmt.png.dither fmt.png.dither=false (set to true by default) disables dithering. Dithering helps smooth out the colour banding when dealing with a reduced colour palette. Dithering may increase filesize due to increased difficulty when compressing.
blur
blur Applies a Gaussian blur to the image. The format of blur is as follows image?blur{radius},{sigma}
  • radius- the accuracy of the blur. Should generally be 2 to 3 times sigma
  • sigma- the strength of the blur. Both radius and sigma are between 0 to 100
    Example:
    https://i1.adis.ws/i/ampproduct/shoe-image?blur=30,60
  • reduce noise
    noiser Removes noise from an image. The value is between 0 and 5. The higher the value the more noise is removed.
    Example:
    https://i1.adis.ws/i/ampproduct/twofriends?noiser=5
    gamma gamma Adjusts the gamma correction of an image. gamma is specified as a floating point value. A value of less than 1 will make the image darker and greater than 1 will make the image lighter.
    Example:
    https://i1.adis.ws/i/ampproduct/twofriends?gamma=0.5
    hue, saturation, brightness hue, sat, bri Each of these parameters can be specified separately. Each value is between -100 to 100.
  • hue  - adjust the color of the image. The color change is based on the hue scale.
  • sat - adjust the amount of gray in the image.
  • bri  - adjust the brightness of the image.

  • Example:
    https://i1.adis.ws/i/ampproduct/shoe-image?hue=40&sat=10&bri=55
    Progressive JPEG fmt.jpeg.interlaced=true Requesting a progressive JPEG asset downloads a lower quality version initially, and then increases the quality the more data that is downloaded. Example:
    https://i1.adis.ws/i/support/Tiger1?fmt.jpeg.interlaced=true.

    Further information can be found on the Progressive Images page.

    Layers

    Layering allows you to composite multiple images one on top of the other. When using layers, the base layer will always be layer 0. You can specify additional layers on top: layer 1, layer2 and so on.

    Parameters for each layer are enclosed in "[]" and include the image manipulation parameters shown on this page. Parameters specific to managing images in layers are shown below.

    To try out examples of using layers see the layers and roundels section of the Dynamic Media playground.

    In the example below the blue dress image is layer0 and the exampleRoundel image is layer1.

    https://i1.adis.ws/i/ampproduct/blue-dress-outside?layer1=[src=/i//exampleRoundel]
    

    If you wanted to specify parameters for layer0, as well as other layers, you would use the following format:

    https://i1.adis.ws/i/ampproduct/blue-dress-outside?layer0=[w=800]&layer1=[src=/i//exampleRoundel&w=150]
    

    You can also specify an empty template and add the URL for each layer:

    https://i1.adis.ws/i/ampproduct/?layer0=[src=/i//blue-dress-outside]&layer1=[src=/i//exampleRoundel]
    

    Layering parameters

    Feature Parameter Description
    image src src The URL for the image in the specified layer. If you start the image URL with "/i//" then it will use the same partial domain as layer0 or the template you specified at the start of the URL
    Example:https://i1.adis.ws/i/ampproduct/blue-dress-outside?layer1=[src=/i//exampleRoundel].
    In this example the URL for the layer1 image is https://i1.adis.ws/i/ampproduct/exampleRoundel
    positioning top, left, bottom, right A layer can be positioned relative to the previous layer (for example layer1 is positioned relative to layer0). By default a layer is positioned in the top left of the previous layer. The top, left, bottom and right position of a layer are specified in pixels or as a percentage of the distance from the specified edge.
    The example below will position layer1 50% from the top and left of layer0: https://i1.adis.ws/i/ampproduct/blue-dress-outside?layer1=[src=/i//exampleRoundel&top=50%&left=50%]
    To further refine layer positioning you can use anchors.
    anchor anchor Anchors are used to select which edge of the image that you want to align against. Combine anchors with positioning to further control the position of a layer within the previous layer. Anchor positions are as follows:
    • TL  Top Left
    • TC  Top Center
    • TR  Top Right
    • ML  Middle Left
    • MC  Middle Center
    • MR  Middle Right
    • BL  Bottom Left
    • BC  Bottom Center
    • BR  Bottom Right
    The example below will position the middle centre of layer one 50% from the top left of layer0:
    https://i1.adis.ws/i/ampproduct/blue-dress-outside?layer1=[src=/i//exampleRoundel&anchor=MC&top=50%&left=50%]
    opacity opacity A value between 0 and 100 that specifies the transparency of an image. 0 is fully transparent, 100 is solid.
    Example: https://i1.adis.ws/i/ampproduct/blue-dress-outside?layer1=[src=/i//exampleRoundel&opacity=50]
    visibility visible Specifies the visibility of a layer. 0 is invisible, 1 is visible. Layers are visible by default.
    Example: https://i1.adis.ws/i/ampproduct/blue-dress-outside?layer1=[src=/i//exampleRoundel&visible=0]
    canvas canvas Provides the ability to draw a quadrilateral shape on a layer that other layers can draw onto. You can optionally specify a bg color. The default background color is white.

    Example:
    https://i1.adis.ws/i/ampproduct/?layer0=[canvas=700,400&bg=rgb(0,0,255)]&layer1=[src=/i//exampleRoundel]

    Text layers

    Text can be layered on top of an image by adding it in a layer as shown in the following example:

    https://i1.adis.ws/i/ampproduct/girlwithballoons?layer1=[text=Time%20to%20celebrate&fontSize=48&textColor=white]
    
    Parameter Description
    text The text to show in the layer. You can add a new line character by including by including \n in the string.
    fontSize The font size to use for the text. If no font size is specified it will default to 10.
    fontFamily The font family to use for the text. If you don't specify a font family, or specify a font that is not installed on your account, then it will default to Helevetica.
    fontStyle Which style of font to use: normal, italic or oblique. Font style selection follows CSS rules.
    fontWeight Sets the thickness of the text. Valid values are from 100 to 900 in multiples of 100. You can also specify normal (400) or bold (700).
    fontStretch Makes text wider or narrower if the font family has appropriate variants. Font selection will follow the CSS rules.
    Supported values are:
    • ultra-condensed 
    • extra-condensed 
    • condensed 
    • semi-condensed 
    • normal 
    • semi-expanded 
    • expanded 
    • extra-expanded 
    • ultra-expanded 
    textColor The color of the text. If no color is specified the text will be black. Values can be hex, rgb or colour names.
    Example: ?layer1=[text=Time%20to%20celebrate&textColor=rgb(255,255,255)]
    textDecoration The decoration added to the text. Supported values are:
    • underline 
    • overline 
    • linethrough 
    textAlign How the text is aligned within its layer. If no alignment is specified the text will be default to left aligned. Alignment will be used when text is divided over more than one line by using the newline "\n" character.
    Example:https://i1.adis.ws/i/ampproduct/girlwithballoons?layer1=[text=Time%20for\ncelebration&fontSize=48&textColor=white&textAlign=center]

    Metadata

    This section shows how to retrieve metadata associated with images. For sets see the Sets API section.

    Feature Parameter Description
    Retrieve all metadata metadata=true Returns all the metadata associated with an image. Supported types:
    • js Returns the data in JSON format wrapped in a JSONP wrapper
    • json Returns the data in JSON format
    • xml Returns the data in XML format

    Parameter Example:
    https://i1.adis.ws/i/ampproduct/Hero-Banner-720-model2.json?metadata=true
    Return specified metadata metadata=true&metaFilter={name} Returns the specified of the specified type. metaFilter=* will return metadata for all types.

    Example:
    https://i1.adis.ws/i/ampproduct/Hero-Banner-720-model2.json?metadata=true&metaFilter=pointOfInterest
    This retrieves the POI focal point metadata associated with the image. Note that the "image" metadata is always included

    Referencing metadata in a query

    You can reference metadata within a query. To reference metadata in the same layer, use {$this.metadata}.

    For example, to crop an image using the POI metadata associated with an image, you can use the following query:

    https://i1.adis.ws/i/ampproduct/Hero-Banner-720-model2?w=320&h=480&sm=c&poi={$this.metadata.pointOfInterest.x}, {$this.metadata.pointOfInterest.y}, {$this.metadata.pointOfInterest.w}, {$this.metadata.pointOfInterest.h}&scaleFit=poi
    

    When working with images with multiple layers, you can use $root to refer to the root layer and $parent to refer to the parent layer. See the metadata playground page for more details.

    Other features

    Feature Parameter Description
    missing image img404 The filename of the fallback image to display if an image cannot be found. The specified fallback image must be a published image on the same account. You can specify img404 as a parameter in a query string or transformation template or Amplience can apply this at the account level.
    Parameter example: ?img404=yourcompanyimagenotfound
    variables
    ${variable}= Variables, prefixed with "$", can be included in a query string, set to hold specified values and used throughout the query.

    Example:
    exampleimage?imageheight=300&h=$imageheight
    Sets the variable imageheight to 300 and then uses this variable to set the height of the image to 300 px.
    conditionals
    ==,>,<, >=, <=,!= Conditional statements are supported of the format: {($variable==value)?true:false}.
    Supported types are number, string and boolean. Strings must be assigned to variables before being used in comparisons.

    Example:
    https://i1.adis.ws/i/ampproduct/Hero-Banner-720-model2?w={($value1==$value2)?200:400}&value1=1&value2=5

    If $value1 and $value2 are equal, this will set the width of the image to 200 px, otherwise the image will be set to 400 px. Because the values are different, the image will be set to 400 px.
    expressions
    +, -, /, * Expressions can be included in queries and must be wrapped in {}. The expressions engine supports addition, subtraction, division and multiplication. Variables can also be used.

    Example:
    myimage?w={$firstValue+$secondValue}&firstValue=100&secondValue=200
    Sets the width of the image to 300.

    myimage?w={25%}
    You can also use percentages. This sets the image to 25% of its size.

    Set API

    Sets are named groupings of assets that can be manipulated using Dynamic Media.

    The available parameters for manipulating sets are shown below. You can try out the Set API with real examples on the playground.

    Metadata

    The Set Metadata API returns the elements of a set in the requested format. For each format you can specify additional parameters to manipulate the result.

    Example: https://i1.adis.ws/s/ampproduct/mytestset.json

    Feature Structure Description
    JSONP format /s/{account}/{setName}.js Returns the data in JSON format wrapped in a JSONP wrapper. This allows data to be loaded without cross site scripting problems. You can use the following parameters to manipulate the response.
    • qual Specifies if the image URL returned is fully qualified. The default is true
    • qry The query string appended to all set elements. You can also specify a transformation template. Example
      https://i1.adis.ws/s/ampproduct/mytestset.js?qry=$exampletemplate$ 
    • deep true if the structured of nested sets will be returned. The default is false
    • func The name of the JSONP callback function
    • arg Optional argument sent to the callback function
    JSON format /s/{account}/{setName}.json Returns the data in JSON format. You can use the following parameters to manipulate the response.
    • qual Specifies if the image URL returned is fully qualified. The default is true
    • qry The query string appended to all set elements. You can also specify a transformation template.
    • deep true if the structured of nested sets will be returned. The default is false
    XML format /s/{account}/{setName}.xml Returns the set elements in XML format. You can use the following arguments to manipulate the response.
    • qual Specifies if the image URL returned is fully qualified. The default is true
    • qry The query string appended to all set elements. You can also specify a transformation template.
    • deep true if the structured of nested sets will be returned. The default is false
    Text format /s/{account}/{setName}.txt Returns the set elements in plain text format. You can use the following arguments to manipulate the response.
    • qual Specifies if the image URL returned is fully qualified. The default is true
    • qry The query string appended to all set elements. You can also specify a transformation template.
    • deep true if the structured of nested sets will be returned. The default is false
    HTML format /s/{account}/{setName}.html Returns the set elements in HTML format within a ul tag. Each element is returned within li tags. You can use the following parameters to manipulate the response.
    • qual Specifies if the image URL returned is fully qualified. The default is true
    • qry  The query string appended to all set elements. You can also specify a transformation template.
    • deep true if the structured of nested sets will be returned. The default is false
    • ulCls A CSS class that will be added to all ul  tags in the response
    • liCls A CSS class that will be added to all li  tags in the response
    • size If true the original width and height of the image will be added to the img  tag.

    Images

    You can also return the specified element of a set as an image.

    Example: https://i1.adis.ws/s/ampproduct/mytestset/2

    Feature Structure Description
    Return image /s/{account}/{setName}
    /s/{account}/{setName}?{param}
    /s/{account}/{setName}/seoFilename
    Returns the first element of the set as an image. For a video the thumbnail will be returned.
    Example: https://i1.adis.ws/s/ampproduct/mytestset
    Image manipulation parameters may also be applied to the image:
    https://i1.adis.ws/s/ampproduct/mytestset?w=300
    Return nth image /s/{account}/{set}/{n}
    /s/{account}/{set}/{n}?w=300
    Returns the nth element of the set. Note that 1 is the first element.
    Example: https://i1.adis.ws/s/ampproduct/mytestset/3
    Return nested nth image /s/{account}/{set}/{n}/{n} Returns the nested nth image

    Media cache settings

    Dynamic Media playground

    results matching ""

      No results matching ""