---
canonical: https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/
title: Reference
description: Complete reference for the Amplience Media Delivery API parameters, including image transformations, video delivery, sets, templates and format options.
audience: Developer
date_published: 2022-06-23
date_modified: 2025-05-20
---
# Media delivery API reference
This page lists the parameters available to you for manipulating images on the fly using the features of Dynamic Media.
You can dynamically manipulate any image just by appending the parameters to the end of the URL. In the following example the image is rotated by 90 degrees.
```
https://cdn.media.amplience.net/i/ampproduct/twofriends?rotate=90
```
## Image Transformation Features
### Width
Parameter: `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
Parameter: `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
Parameter: `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`
### Default format quality settings
Parameter: `qlt=default`
Specifies that the default quality should be used for the following formats: `avif`, `webp`,`jp2`,`jpeg` or `png`. Can be used with `fmt=auto` or on its own. See [auto format](#auto-format) for more details.
The default settings for each format are:
| Format | Default quality setting |
| ------ | ----------------------- |
| `jp2` | 40 |
| `avif` | 55 |
| `webp` | 80 |
| `jpeg` | 75 |
| `png` | 90 |
You can add your own quality settings in the root template for your account or transformation templates.
Note that to retrieve images in `avif` format requires Accelerated Media.
#### Parameter example
```
https://cdn.media.amplience.net/i/ampproduct/women-bright-colors.jpg?fmt=auto&qlt=default
```
### Format quality settings
Parameters:
`fmt.avif.qlt`
`fmt.webp.qlt`
`fmt.jp2.qlt`
`fmt.png.qlt`
`fmt.jpeg.qlt`
Sets the compression quality used for the specified image format: `avif`, `webp`, `jp2`, `jpeg` or `png`.
Can be used with `fmt=auto`.
See [auto format](#auto-format) for more details.
#### Parameter example:
```
https://cdn.media.amplience.net/i/ampproduct/women-bright-colors.jpg?fmt=auto&fmt.webp.qlt=50
```
### Scale mode
Parameter: `sm`
Indicates how to position the image if it does not fit exactly to the width and height specified.
| Scale mode | Description |
| ---------- | ------------- |
| `c` | Crop to Fit |
| `s` | Stretch |
| `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 |
| `aspect` | Aspect ratio |
#### Parameter example
`exampleimage?w=256&sm=aspect&aspect=16:9`
### Scale mode- resize edge
Parameter: `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 mode- clamp
Given a width and height, will fit the image into the specified area and maintain the aspect ratio while ensuring that there is no padding.
Parameter: `sm=clamp`
#### Parameter example
```
https://cdn.media.amplience.net/i/ampproduct/blur-brass-bronze-timepiece?w=400&h=1000&sm=clamp
```
### Scale fit
Parameter: `scaleFit`
Specifies how to position the area to be cropped when using `sm`.
| Scale fit mode | Description |
| -------------- | -------------------------------------------------------------------------------------------- |
| center | (default) |
| poi | Crop using the specified point of interest focal point. See point of interest for an example |
### Point of interest
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
#### Parameter example
```
https://cdn.media.amplience.net/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
Parameter: `filter`
The algorithm to use when the image is resized.
| Resize value | Description |
| ------------ | ----------------- |
| `q` | Quadratic |
| `s` | Sinc |
| `l` | Lanczos (default) |
| `p` | Point |
| `c` | Cubic |
| `h` | Hermite |
### Upscale
Parameter: `upscale`
Possible values: `true`, `false` or `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
Parameter: `maxW`
Sets the maximum width for the image returned. Can be specified at the account level.
### Max height
Parameter: `maxH`
Sets the maximum height for the image returned. Can be specified at the account level.
## Cropping and rotating
> **Tip: Cropping images within Workforce flows**
> To crop, trim, or perform other transformations on an image within a Workforce flow, use the [Image actions](https://amplience.com/developers/docs/workforce/flows/action-reference/image-actions).
### Crop
Parameter: `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.
#### Parameter example
`https://cdn.media.amplience.net/i/ampproduct/man-with-bag-city-skyline?crop=2000,1000,2000,2500`
This will crop the image 2000 pixels from the top left and 1000 pixels from the top of the image, with a selection 2000 pixels wide and a height of 2500 pixels. The crop is applied **after** any resize so the coordinates are relative to the resized image.
Each of the cropping parameters can also take percentages as parameters. For example:
`https://cdn.media.amplience.net/i/ampproduct/man-with-bag-city-skyline?crop=33%,25%,33%,62%`
### Edge crop
Parameter: `ecrop`
Takes 4 parameters: left, top, right, bottom to crop from each edge of the image. `ecrop` is applied **after** any resize so the coordinates are relative to the resized image.
#### Parameter example
`https://cdn.media.amplience.net/i/ampproduct/man-with-bag-city-skyline?ecrop=1000,250,1000,250`
The example above will crop 1000 pixels from the left and right of the image and 250 pixels from the top and bottom.
You can also specify the parameters as percentages. The following example will crop 25% from the left and top edges of the image and 5% from the top and bottom:
`https://cdn.media.amplience.net/i/ampproduct/man-with-bag-city-skyline?ecrop=25%,5%,25%,5%`
### Pre crop
Parameter: `pcrop`
This is the same as [crop](#crop) except it does the crop before any resize event and therefore the coordinates are relative to the **original** image size. As with `crop`, you can also provide the parameters as percentages.
#### Parameter example
This example combines the `prop` with a resize of the image:
`https://cdn.media.amplience.net/i/ampproduct/man-with-bag-city-skyline?pcrop=2000,1000,2000,2500&w=200`
### Pre edge crop
Parameter: `pecrop`
Same as `ecrop` but crops from the edge of the image before any resize event and therefore the coordinates are relative to the **original** image size. As with `ecrop`, you can also provide the parameters as percentages.
#### Parameter example
This example combines the `pecrop` with a resize of the image:
`https://cdn.media.amplience.net/i/ampproduct/man-with-bag-city-skyline?pecrop=25%,5%,25%,5%`
### Rotate
Parameter: `rotate`
Rotate an image by a specified number of degrees. The rotate is applied after the effect of any resize parameters.
Optional parameter: `rgb`
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.
#### Parameter examples
```
https://cdn.media.amplience.net/i/ampproduct/twofriends?rotate=90
```
```
https://cdn.media.amplience.net/i/ampproduct/twofriends?rotate=80,rgb(30,50,90)
```
### Pre rotate
Parameter: `protate`
The same as [rotate](#rotate), except that the rotation is applied before any resize parameters.
#### Parameter example
```
https://cdn.media.amplience.net/i/ampproduct/twofriends?protate=270&w=500
```
### Flip
Parameter: `flip`
Flips the image horizontally, vertically or both.
#### Parameter examples
```
https://cdn.media.amplience.net/i/ampproduct/twofriends?fliph=true
```
```
https://cdn.media.amplience.net/i/ampproduct/twofriends?fliph=true&flipv=true
```
## File manipulation
### Format
Parameter: `fmt`
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`, `avif` and `jp2`. Note that `webp` is not supported on [certain browsers](https://caniuse.com/#feat=webp).
- `jp2` is currently only supported in Safari for iOS and macOS.
- `avif` requires [Accelerated Media](#accelerated-media) to be enabled on your account. Images greater than 2.5 megapixels will be returned in `jpeg` format or `png` (if the image contains transparency).
#### Parameter example
`myimage?fmt=png`
`myimage.png`
### Auto format
Parameter: `fmt = auto`
Specifies that the image should be returned in the most efficient format for the browser. Note that this feature and support for the AVIF format requires [Accelerated Media](#accelerated-media).
The image format will be chosen according to the following rules:
- `avif` if it is enabled on your account and the [browser supports it](https://caniuse.com/?search=avif).
- `webp` for Safari, Chrome, Firefox and other browsers that support it and don't support `avif`.
- `jp2` for versions of Safari that don't support `webp` but do support `jp2`
- For other browsers, or earlier versions of Chrome, Firefox or Safari, the image is returned in `jpg` format.
- If the original image contains transparency, then the image will be returned in PNG format in Safari.
For more information see the [Amplience Smart Images](https://amplience.com/developers/docs/dev-tools/guides-tutorials/media-delivery/smart-image) page.
Note that it is possible to remove images from use by Amplience Smart Image. For example, you could ensure that images are never returned in `jp2` format by removing that format from the list.
### Dots per inch
Parameter: `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
Parameter: `dpiFilter`
Specifies the resampling algorithm to use when changing the DPI.
| Parameter | Description |
| --------- | ----------------- |
| q | Quadratic |
| s | Sinc |
| l | Lanczos (Default) |
| p | Point |
| c | Cubic |
#### Parameter example
```
https://cdn.media.amplience.net/i/ampproduct/signature-hat-german?dpi=120&dpiFilter=q&w=200
```
### Strip
Parameter: `strip`
Removes commands and meta data from the image. `true` or `false`.
This is `false` by default.
## Image adjustments
### Chroma subsampling
Parameter: `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
Parameter: `cs`
Changes the colorspace used for the image.
Supported values:
| Color space value | Description |
| ----------------- | --------------------------- |
| `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
Parameter: `unsharp`
`unsharp={radius},{sigma},{amount},{threshold}`
Sharpens the image with an unsharp mask.
| Parameter | Description |
| --------- | --------------------------------------------------------------------------------- |
| 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
Parameter: `cm`
When an image is applied on top of a background colour this defines the composite operator.
Supported parameters:
- `over` (default)
- `colo`
- `dark`
- `diff`
- `light`
- `multi`
- `cout`
- `cover`
### Image background
Parameter: `bg`
This will set the background color of the image. It only has an effect when the image is padded or the original image is transparent.
#### Parameter example
```
https://cdn.media.amplience.net/i/ampproduct/shoe-image?bg=rgb(0,0,255)
```
### Indexed png
Parameter: `fmt.png.indexed`
`true` or `false`. The default is `false`.
Specify if the PNG image should be indexed. Indexed PNGs have a color palette rather than storing color information with the pixel data.
### Palette size
Parameter: `fmt.png.palettesize`
Sets the color palette size for a png image. The value must be between 1 and 256. Requires `fmt.png.indexed=true`
The default palette size is 256. Note the image has to be served in png format. Should notably reduce the file size of an asset.
### Dither
Parameter: `fmt.png.dither`. `fmt.png.dither=false` (set to true by default).
Disables dithering. Dithering helps smooth out the color banding when dealing with a reduced colour palette. Dithering may increase file size due to increased difficulty when compressing.
### Blur
Parameter: `blur`
Applies a Gaussian blur to the image. The format of blur is as follows:
`image?blur={radius},{sigma}`
| Parameter (value) | Description |
| ----------------- | --------------------------------------------------------------------- |
| 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. |
#### Parameter example
```
https://cdn.media.amplience.net/i/ampproduct/shoe-image?blur=30,60
```
### Reduce noise
Parameter: `noiser`
Removes noise from an image. The value is between 0 and 5. The higher the value the more noise is removed.
#### Parameter example
```
https://cdn.media.amplience.net/i/ampproduct/twofriends?noiser=5
```
### Gamma
Parameter: `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.
#### Parameter example
```
https://cdn.media.amplience.net/i/ampproduct/twofriends?gamma=0.5
```
### Hue, saturation, brightness
Parameters: `hue`, `sat`, `bri`
Each of these parameters can be specified separately. Each value is between -100 to 100.
| Parameter | Description |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | --- |
| `hue` | Adjust the color of the image. The color change is based on the [hue scale](https://upload.wikimedia.org/wikipedia/commons/a/ad/HueScale.svg). |
| `sat` | Adjust the amount of gray in the image |
| `bri` | Adjust the brightness of the image. | ] |
#### Parameter example
```
https://cdn.media.amplience.net/i/ampproduct/shoe-image?hue=40&sat=10&bri=55
```
### Progressive JPEG
Parameter: `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.
Further information can be found on the [progressive Images](https://amplience.com/developers/docs/dev-tools/guides-tutorials/media-delivery/progressive-images) page.
#### Parameter example
```
https://cdn.media.amplience.net/i/support/Tiger1?fmt.jpeg.interlaced=true
```
## 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](https://playground.amplience.com/di/app/#/layers) section of the Dynamic Media playground.
In the example below the blue dress image is layer0 and the exampleRoundel image is layer1.
```
https://cdn.media.amplience.net/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://cdn.media.amplience.net/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://cdn.media.amplience.net/i/ampproduct/?layer0=[src=/i//blue-dress-outside]&layer1=[src=/i//exampleRoundel]
```
## Layering parameters
### Image src
Parameter: `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.
#### Parameter examples
```
https://cdn.media.amplience.net/i/ampproduct/blue-dress-outside?layer1=[src=/i//exampleRoundel]
```
In this example the URL for the layer1 image is `https://cdn.media.amplience.net/i/ampproduct/exampleRoundel`
### Positioning
Parameters: `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.
To further refine layer positioning you can use [anchors](#anchor).
#### Parameter example
The example below positions layer1 50% from the top and left of layer0:
```
https://cdn.media.amplience.net/i/ampproduct/blue-dress-outside?layer1=[src=/i//exampleRoundel&top=50%&left=50%]
```
### Anchor
Parameter: `anchor`
Anchors are used to select which edge of the image that you want to align against. Combine anchors with [positioning](#positioning) to further control the position of a layer within the previous layer.
Anchor positions are as follows:
| Anchor parameter | Description |
| ---------------- | ------------- |
| `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 |
#### Parameter example
The example below positions the middle centre of layer one 50% from the top left of layer0:
```
https://cdn.media.amplience.net/i/ampproduct/blue-dress-outside?layer1=[src=/i//exampleRoundel&anchor=MC&top=50%&left=50%]
```
### Opacity
Parameter: `opacity`
A value between 0 and 100 that specifies the transparency of an image. 0 is fully transparent, 100 is solid.
#### Parameter example
```
https://cdn.media.amplience.net/i/ampproduct/blue-dress-outside?layer1=[src=/i//exampleRoundel&opacity=50]
```
### Visibility
Parameter: `visible`
Specifies the visibility of a layer. 0 is invisible, 1 is visible. Layers are visible by default.
#### Parameter example
```
https://cdn.media.amplience.net/i/ampproduct/blue-dress-outside?layer1=[src=/i//exampleRoundel&visible=0]
```
### Canvas
Parameter: `canvas`
Provides the ability to draw a quadrilateral shape on a layer that other layers can draw onto. You can optionally specify a [background color](#image-background). The default background color is white.
#### Parameter example
```
https://cdn.media.amplience.net/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://cdn.media.amplience.net/i/ampproduct/girlwithballoons?layer1=[text=Time%20to%20celebrate&fontSize=48&textColor=white]
```
### Text
Parameter: `text`
The text to show in the layer. You can add a new line character by including by including \n in the string.
### Font size
Parameter: `fontSize`
The font size to use for the text. If no font size is specified it will default to 10.
### Font family
Parameter: `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.
### Font style
Parameter: `fontStyle`
Which style of font to use: `normal`, `italic` or `oblique`.
Font style selection follows [CSS rules](https://www.w3.org/TR/css3-fonts/#propdef-font-style).
### Font weight
Parameter: `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).
### Font stretch
Parameter: `fontStretch`
Makes text wider or narrower if the font family has appropriate variants. Font selection will follow the [CSS rules](https://www.w3.org/TR/css3-fonts/#propdef-font-stretch).
Supported values:
- `ultra-condensed`
- `extra-condensed`
- `condensed `
- `semi-condensed`
- `normal `
- `semi-expanded`
- `expanded `
- `extra-expanded`
- `ultra-expanded`
### Text color
Parameter: `textColor`
The color of the text. If no color is specified the text will be black. Values can be hex, rgb or colour names.
#### Parameter example
```
https://cdn.media.amplience.net/i/ampproduct/girlwithballoons?layer1=[text=Time%20to%20celebrate&textColor=rgb(255,255,255)]
```
### Text decoration
Parameter: `textDecoration`
The decoration added to the text.
Supported values are:
- `underline`
- `overline `
- `linethrough `
### Text alignment
Parameter: `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.
#### Parameter example
```
https://cdn.media.amplience.net/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](#sets) section.
### Retrieve all metadata
Parameter: `metadata=true`
Returns all the metadata associated with an image.
Supported types:
| Type | Description |
| ------- | ---------------------------------------------------------- |
| `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://cdn.media.amplience.net/i/ampproduct/Hero-Banner-720-model2.json?metadata=true
```
### Return specified metadata
Parameter: `metadata=true&metaFilter={name}`
Returns the specified of the specified type.
`metaFilter=*` will return metadata for all types.
#### Parameter example
This example retrieves the POI focal point metadata associated with the image. Note that the "image" metadata is always included:
```
https://cdn.media.amplience.net/i/ampproduct/Hero-Banner-720-model2.json?metadata=true&metaFilter=pointOfInterest
```
### Referencing metadata in a query
You can reference metadata within a query. To reference metadata in the same layer, use `{$this.metadata}`.
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](https://playground.amplience.com/di/app/#/advanced) playground page for more details.
#### Parameter examples
To crop an image using the POI metadata associated with an image, you can use the following query:
```
https://cdn.media.amplience.net/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
```
## Other features
### Missing image
Parameter: `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
Parameter: `${variable}=`
Variables, prefixed with "$", can be included in a query string, set to hold specified values and used throughout the query.
#### Parameter example
The following example sets the variable imageheight to 300 and then uses this variable to set the height of the image to 300 px.
`exampleimage?imageheight=300&h=$imageheight`
The following scales the image by the inverse of the scalefactor.
`https://cdn.media.amplience.net/i/ampproduct/party-fashion?w={(1/$scalefactor)*100%}&scalefactor=2`
### Conditionals
Parameters: `==`,`>`,`<`, `>=`, `<=`,`!=`
Format: `{($variable==value)?true:false}`
Supported types are number, string and boolean. Strings must be assigned to variables before being used in comparisons.
#### Parameter example
In the following example 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 in this case the values are different, the image will be set to 400 px.
```
https://cdn.media.amplience.net/i/ampproduct/Hero-Banner-720-model2?w={($value1==$value2)?200:400}&value1=1&value2=5
```
### Expressions
Parameters: `+`, `-`, `/`, `*`
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.
#### Parameter example
In this example the width of the image is set to 300.
`myimage?w={$firstValue+$secondValue}&firstValue=100&secondValue=200`
You can also use percentages. This following sets the image to 25% of its size.
`myimage?w={25%}`
## Sets
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](https://playground.amplience.com/di/app/#/sets).
### Set images
You can return the specified element of a set as an image:
- The first element of a set
- The nth element of a set
- The nested nth element of a set
The following example shows how to return the second element of a set:
`https://cdn.media.amplience.net/s/ampproduct/mytestset/2`
#### Return image
Supported parameters:
`/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.
The following example will return the first element of the set "mytestset" as an image.
`https://cdn.media.amplience.net/s/ampproduct/mytestset?w=400`
Image manipulation parameters may also be applied to the image:
`https://cdn.media.amplience.net/s/ampproduct/mytestset?w=300`
#### Return nth image
Supported parameters:
`/s/{account}/{set}/{n}`
`/s/{account}/{set}/{n}?{param}`
Returns the nth element of the set. Note that 1 is the first element.
The following example shows how to return element 3 of the set "mytestset":
`https://cdn.media.amplience.net/s/ampproduct/mytestset/3`
#### Return nested nth image
Parameter: `/s/{account}/{set}/{n}/{n}`
Returns the nested nth image.
### Set 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.
You can retrieve metadata in JSONP, JSON, XML, text and HTML format.
The following example shows how to retrieve metadata in JSON format:
`https://cdn.media.amplience.net/s/ampproduct/mytestset.json`
Additional information for each format is shown below.
#### JSONP format
Parameter: `/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 additional parameters to manipulate the response:
| Parameter | Description |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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://cdn.media.amplience.net/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
Parameter: `/s/{account}/{setName}.json`
Returns the data in JSON format.
You can use the following additional parameters to manipulate the response.
| Parameter | Description |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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://cdn.media.amplience.net/s/ampproduct/mytestset.js?qry=$exampletemplate$` |
| `deep` | true if the structured of nested sets will be returned. The default is false |
#### XML format
Parameter: `/s/{account}/{setName}.xml`
Returns the set elements in XML format. You can use the following additional parameters to manipulate the response:
| Parameter | Description |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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://cdn.media.amplience.net/s/ampproduct/mytestset.js?qry=$exampletemplate$` |
| `deep` | true if the structured of nested sets will be returned. The default is false |
#### Text format
Parameter: `/s/{account}/{setName}.txt`
Returns the set elements in plain text format.
You can use the following additional parameters to manipulate the response:
| Parameter | Description |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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://cdn.media.amplience.net/s/ampproduct/mytestset.js?qry=$exampletemplate$` |
| `deep` | true if the structured of nested sets will be returned. The default is false |
#### HTML format
Parameter: `/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:
| Parameter | Description |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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://cdn.media.amplience.net/s/ampproduct/mytestset.js?qry=$exampletemplate$` |
| `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 |
## SEO
You can add SEO text to a URL so that it is included in image requests and search engine results. This is designed to help improve the page score and drive search engine traffic. Adding SEO text to the URL is particularly useful in the cases where you use a naming convention using product codes and you want to provide a friendly name to be searched for.
For example if an image of a red dress is named:
```
https://cdn.media.amplience.net/i/ampproduct/1377455-collection-spring
```
You can add the SEO text `womens/spring/red-dress` as follows:
```
https://cdn.media.amplience.net/i/ampproduct/1377455-collection-spring/womens/spring/red-dress
```
The SEO text would then be included in the search engine results when someone is searching for a red dress for spring.
### Sets and SEO
You need to be careful when adding SEO text to a set and the SEO text starts with a number. For example the following will return a "file not found" error because Dynamic Media is looking for the 3rd item in the set. In this case the set contains 2 items, so the 3rd item cannot be found.
```
https://cdn.media.amplience.net/s/ampproduct/spring-collection-set/3-red-dress/womens/spring
```
To get around this problem you can just add a non numeric character to the start of the SEO name. In the example below first item in the set will be returned.
```
https://cdn.media.amplience.net/s/ampproduct/spring-collection-set/_3-red-dress/womens/spring
```
## Video
You can access video encoded using a particular [profile](https://amplience.com/developers/docs/user-guides/assets/video/#video-transcode-profiles) by including the profile in the URL. For example, using the following URL will return the winter-coat video encoded using the mp4_720p profile.
```
https://cdn.media.amplience.net/v/ampproduct/winter-coat/mp4_720p
```
The HTML `