--- canonical: https://amplience.com/developers/docs/apis/media-delivery/media-delivery-quick-reference/ title: Media Delivery API — Quick reference description: A concise reference of all query parameters for the Amplience Media Delivery API. keywords: - Dynamic Media - Media Delivery API - Amplience Dynamic Media - Dynamic Media parameters - image transformation API - image URL parameters audience: Developer date_published: 2026-07-12 date_modified: 2026-08-04 --- # Media Delivery API — Quick reference A concise reference of all query parameters for images, sets, and video. Every parameter can be appended to an asset's URL as a query string: **Base URL pattern** ```text https://cdn.media.amplience.net/{type}/{account}/{assetName}?{parameters} ``` `type` identifies the asset kind (`i` for images, `s` for sets, `v` for video). See [URL structure](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-overview/#url-structure) in the overview for more detail. > **Info:** For full documentation including interactive examples, see the [Media Delivery API guide](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/). ## Images ### Sizing Resize with `w`, `h`, `maxW`, and `maxH`, then control what happens when the image does not fit the requested dimensions with scale modes, point of interest, and upscaling. | Parameter | Description | |---|---| | `w` | Output width in pixels. Height is auto-calculated to preserve aspect ratio if omitted. | | `h` | Output height in pixels. Width is auto-calculated to preserve aspect ratio if omitted. | | `maxW` | Maximum output width; larger requests are clamped and the height follows the aspect ratio. Can also be configured at the account level. | | `maxH` | Maximum output height; larger requests are clamped and the width follows the aspect ratio. Can also be configured at the account level. | > **Tip: Full reference and interactive examples** > See [Sizing](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/sizing-and-scaling/#sizing) · [`w`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/sizing-and-scaling/#w) · [`h`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/sizing-and-scaling/#h) · [`maxW`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/sizing-and-scaling/#maxw) · [`maxH`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/sizing-and-scaling/#maxh) ### Scale mode #### `sm` - Scale mode Controls how the image is positioned or cropped when it does not fit exactly to the requested dimensions. | Value | 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` | Maintain aspect ratio | | `edge` | Resize to a specified edge - requires `resize.edge` and `resize.edge.length` | | `clamp` | Fit within bounds without padding, maintaining aspect ratio | > **Tip: Full reference and interactive examples** > See [Scale mode](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/sizing-and-scaling/#scale-mode) · [`sm`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/sizing-and-scaling/#sm) · [`sm=edge`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/sizing-and-scaling/#sm-edge) · [`sm=clamp`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/sizing-and-scaling/#sm-clamp) #### `sm=edge` sub-parameters | Parameter | Values | Description | |---|---|---| | `resize.edge` | `w`, `h`, `largest`, `smallest` | Which edge to target | | `resize.edge.length` | integer (pixels) | Target length in pixels | #### `scaleFit` - Scale fit mode Specifies how to position the crop area when using `sm`. | Value | Description | |---|---| | `center` | Default | | `poi` | Crop using the point of interest focal point | > **Tip: Full reference and interactive examples** > See `scaleFit=poi` in the [`poi` example](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/sizing-and-scaling/#poi). #### `poi` - Point of interest Defines a focal point for cropping. Format: `poi={x},{y},{w},{h}` - all values are percentages of the image dimensions. | Component | Description | |---|---| | `x` | Left edge of the focal point as a percentage of image width | | `y` | Top edge of the focal point as a percentage of image height | | `w` | Width of the focal point as a percentage of image width | | `h` | Height of the focal point as a percentage of image height | > **Tip: Full reference and interactive examples** > See [`poi`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/sizing-and-scaling/#poi) #### `filter` - Resize algorithm The resampling algorithm used when resizing. | Value | Description | |---|---| | `q` | Quadratic | | `s` | Sinc | | `l` | Lanczos (default) | | `p` | Point | | `c` | Cubic | | `h` | Hermite | > **Tip: Full reference and interactive examples** > See [`filter`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/sizing-and-scaling/#filter) #### `upscale` - Upscale behaviour Controls whether the image can be scaled larger than the original. | Value | Description | |---|---| | `true` | Allow upscaling | | `false` | Do not upscale | | `padd` | Draw the image, unscaled, on a canvas of the requested size - specify both `w` and `h` to define the canvas. Align via `sm`; set background colour via `bg`. | > **Tip: Full reference and interactive examples** > See [`upscale`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/sizing-and-scaling/#upscale) ### Cropping and rotation Crop a region or trim from the edges, before or after resizing, then rotate or flip. | Parameter | Format | Description | |---|---|---| | `crop` | `{x},{y},{w},{h}` | Cuts a region from the image. Applied **after** any resize. Accepts px or %. | | `ecrop` | `{left},{top},{right},{bottom}` | Crops a specified amount from each edge. Applied **after** any resize. Accepts px or %. | | `pcrop` | `{x},{y},{w},{h}` | Same as `crop`, but applied **before** any resize. Coordinates are relative to the original image size. | | `pecrop` | `{left},{top},{right},{bottom}` | Same as `ecrop`, but applied **before** any resize. Coordinates are relative to the original image size. | | `rotate` | `{degrees}` or `{degrees},rgb({r},{g},{b})` | Rotates the image. Applied **after** any resize. For angles that aren't a multiple of 90°, the optional `rgb` value (comma-appended to the angle) colours the exposed corners. | | `protate` | degrees | Same as `rotate`, but applied **before** any resize. | | `fliph` | `true` | Flip the image horizontally. | | `flipv` | `true` | Flip the image vertically. | > **Tip: Full reference and interactive examples** > See [`crop`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/cropping-and-rotation/#crop) · [`ecrop`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/cropping-and-rotation/#ecrop) · [`pcrop`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/cropping-and-rotation/#pcrop) · [`pecrop`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/cropping-and-rotation/#pecrop) · [`rotate`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/cropping-and-rotation/#rotate) · [`protate`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/cropping-and-rotation/#protate) · [`flip`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/cropping-and-rotation/#flip) ### Format and quality Choose the output format, including automatic format selection, and tune compression globally, per format, or from platform defaults. #### `fmt` - Output format Sets the output format. Defaults to the original format if not specified. Setting the file extension also changes the format. | Value | Notes | |---|---| | `jpg` | JPEG | | `png` | PNG | | `gif` | GIF | | `bmp` | BMP | | `webp` | Not supported in all browsers. | | `avif` | Requires [Accelerated Media](https://amplience.com/developers/docs/dev-tools/guides-tutorials/media-delivery/accelerated-media/). Images larger than 2.5MP fall back to `jpeg` (or `png` if transparency is present). Not supported in all browsers. | | `jp2` | Safari for iOS and macOS only | | `auto` | Returns the most efficient format supported by the requesting browser. Requires [Accelerated Media](https://amplience.com/developers/docs/dev-tools/guides-tutorials/media-delivery/accelerated-media/). | > **Tip: Full reference and examples** > See [`fmt`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/format-and-quality/#fmt) · [`fmt=auto`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/format-and-quality/#fmt-auto) #### `qlt` - Quality Sets compression quality as a percentage (0–100). JPEG is lossy; PNG is lossless but zlib-compressed. `qlt=default` applies the platform default for the output format. | Format | Default quality | |---|---| | `jp2` | 40 | | `avif` | 55 | | `webp` | 80 | | `jpeg` | 75 | | `png` | 90 | Custom defaults can be set in your account root template or transformation templates. > **Tip: Full reference and interactive examples** > See [`qlt`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/format-and-quality/#qlt) · [`qlt=default`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/format-and-quality/#qlt-default) #### Per-format quality parameters Sets the compression quality for a specific format. Can be combined with `fmt=auto`. | Parameter | Applies to | |---|---| | `fmt.avif.qlt` | AVIF | | `fmt.webp.qlt` | WebP | | `fmt.jp2.qlt` | JPEG 2000 | | `fmt.jpeg.qlt` | JPEG | | `fmt.png.qlt` | PNG | **Example:** ```uri https://cdn.media.amplience.net/i/ampproduct/women-bright-colors.jpg?fmt=auto&fmt.webp.qlt=50 ``` #### Other format and output parameters | Parameter | Values | Description | |---|---|---| | `dpi` | integer | Changes the image resolution. Returns original DPI if omitted. | | `dpiFilter` | `q`, `s`, `l` (default), `p`, `c` | Resampling algorithm used when DPI is changed. | | `strip` | `true` / `false` | Removes commands and metadata from the image. Default: `false`. | | `fmt.jpeg.interlaced` | `true` / `false` | Returns a progressive JPEG - loads a low-quality version first and improves as more data downloads. | | `fmt.jpeg.chroma` | `2,1,1` / `1,1,1` | JPEG chroma subsampling. `2,1,1` = enabled (default); `1,1,1` = disabled. Disabling increases file size. | > **Tip: Full reference and examples** > See [`dpi`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/format-and-quality/#dpi) · [`dpiFilter`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/format-and-quality/#dpifilter) · [`strip`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/format-and-quality/#strip) · [`fmt.jpeg.interlaced`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/format-and-quality/#fmt-jpeg-interlaced) · [`fmt.jpeg.chroma`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/format-and-quality/#fmt-jpeg-chroma) #### PNG-specific parameters | Parameter | Values | Description | |---|---|---| | `fmt.png.indexed` | `true` / `false` | Use an indexed colour palette. Default: `false`. | | `fmt.png.palettesize` | 1–256 | Palette size for indexed PNGs. Requires `fmt.png.indexed=true`. Default: `256`. | | `fmt.png.dither` | `true` / `false` | Dithering for indexed PNGs. Smooths colour banding but may slightly increase file size. Default: `true`. | Example: ```uri https://cdn.media.amplience.net/i/ampproduct/woman-checked-skirt-striped-bag?fmt=png&fmt.png.indexed=true&fmt.png.palettesize=256&fmt.png.dither=true ``` ### Image adjustments #### `cs` - Colour space | Value | Description | |---|---| | `rgb` | RGB | | `rgba` | RGBA | | `srgb` | sRGB | | `gray` | Greyscale | | `cmyk` | CMYK | | `ohta` | OHTA | | `lab` | LAB | | `xyz` | XYZ | | `hsb` | Hue, saturation, brightness | | `hsl` | Hue, saturation, lightness | > **Tip: Full reference and interactive examples** > See [`cs`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/image-adjustments/#cs) #### Other adjustment parameters | Parameter | Format / Values | Description | |---|---|---| | `unsharp` | `{radius},{sigma},{amount},{threshold}` | Unsharp mask. radius: 0–5 (0 = auto); sigma: 0.01–5; amount: 1–300%; threshold: 0–255. | | `cm` | `over` (default), `colo`, `dark`, `diff`, `light`, `multi`, `cout`, `cover`, `copy` | Composite mode when applying image over a background color. | | `cm=copy` | - | Removes the alpha channel from an image, leaving the color data that was masked by the alpha channel visible. Must be provisioned on your account - contact your Customer Success Manager or Amplience Support. | | `bg` | color value | Canvas background color. Takes effect with `upscale=padd` or transparent source images. | | `blur` | `{radius},{sigma}` | Gaussian blur. radius: 0–100; sigma: 0–100. | | `noiser` | 0–5 | Noise reduction. Higher values remove more noise but smooth away more fine detail. | | `gamma` | decimal | Gamma correction. Below 1.0 darkens; above 1.0 lightens. | | `hue` | -100 to 100 | Shifts the color based on the hue scale. | | `sat` | -100 to 100 | Adjusts color saturation. | | `bri` | -100 to 100 | Adjusts brightness. | > **Tip: Full reference and interactive examples** > See [`unsharp`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/image-adjustments/#unsharp) · [`cm`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/image-adjustments/#cm) · [`cm=copy`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/image-adjustments/#cm-copy) · [`bg`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/image-adjustments/#bg) · [`blur`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/image-adjustments/#blur) · [`noiser`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/image-adjustments/#noiser) · [`gamma`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/image-adjustments/#gamma) · [`hue`, `sat`, `bri`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/image-adjustments/#hue-sat-bri) ### Layers Layers allow multiple images to be composited together. Layer 0 is the `baseImage` - additional layers are applied on top using indexed parameters (`layer1`, `layer2`, and so on). Parameters for each layer are enclosed in square brackets `[]`. Example: ```uri https://cdn.media.amplience.net/i/ampproduct/woman-in-blue-spotted-dress?layer1=[src=/i//blue-roundel&top=50%&left=50%] ``` | Parameter | Format / Values | Description | |---|---|---| | `src` | URL path | Image source for the layer. Starting the path with `/i//` reuses the account domain from the base URL. | | `top` / `left` / `bottom` / `right` | px or % | Positions a layer relative to the previous layer. Default: top-left corner. | | `anchor` | `TL` `TC` `TR` `ML` `MC` `MR` `BL` `BC` `BR` | Which point of the layer aligns to the position coordinates. | | `opacity` | 0–100 | Layer transparency. 0 = fully transparent; 100 = fully opaque. | | `visible` | `0` / `1` | Controls layer rendering. Default: `1`. | | `canvas` | `{width},{height}` | Creates a blank canvas. Optionally set background with `bg`. Default background: white. | > **Tip: Full reference and interactive examples** > See [Layers](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/layers/#layers) · [`src`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/layers/#layer-src) · [`top`, `left`, `bottom`, `right`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/layers/#layer-position) · [`anchor`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/layers/#anchor) · [`opacity`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/layers/#opacity) · [`visible`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/layers/#visible) · [`canvas`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/layers/#canvas) ### Text layers Text can be rendered as a layer on top of an image. Example: ```uri https://cdn.media.amplience.net/i/ampproduct/women-wearing-denim-small?layer1=[text=New%20denim\nShop%20now&fontSize=48&textColor=white&textAlign=center&fontWeight=400] ``` | Parameter | Values | Description | |---|---|---| | `text` | string | Text string to render. Use `\n` to insert a line break. | | `fontSize` | integer (pt) | Font size in points. Default: `10`. | | `fontFamily` | string | Font family. Default: `Helvetica`. Falls back to Helvetica if the requested font is not installed. | | `fontStyle` | `normal`, `italic`, `oblique` | Font style. Follows CSS `font-style` rules. | | `fontWeight` | 100–900, `normal`, `bold` | Text weight. `normal` = 400; `bold` = 700. | | `fontStretch` | `ultra-condensed` … `ultra-expanded` | Widens or narrows text. Follows CSS `font-stretch` rules. | | `textColor` | hex, `rgb()`, or named colour | Colour of the rendered text. Default: black. | | `textDecoration` | `underline`, `overline`, `linethrough` | Decoration applied to the text. | | `textAlign` | `left`, `center`, `right` | Alignment within the text layer (applies when text spans multiple lines). Default: `left`. | > **Tip: Full reference and interactive examples** > See [Text layers](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/layers/#text-layers) ### Metadata | Parameter | Values | Description | |---|---|---| | `metadata` | `true` | Returns all metadata associated with an image. Append `.js` (JSONP), `.json`, or `.xml` to the URL. | | `metaFilter` | type string or `*` | Filters metadata to the specified type. `*` returns all types. The `image` block is always included. | > **Tip: Full reference and examples** > See [`metadata=true`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/metadata/#metadata-true) · [`metaFilter`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/metadata/#metafilter) **Metadata tokens** - reference image metadata directly within transformation queries: | Token | Description | |---|---| | `{$this.metadata}` | Metadata from the current layer | | `{$root.metadata}` | Metadata from the root layer | | `{$root.layerX.metadata}` | Metadata from the root layer. Where multiple layers exist, checks the specific layer you want, for example `layer2`. | | `{$parent.metadata}` | Metadata from the parent layer. Where multiple layers exist, this will always check for the immediate parent. | > **Tip: Full reference and interactive examples** > See [Referencing metadata in queries](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/metadata/#metadata-tokens) ### Other image features #### `img404` - Missing image fallback Specifies the filename of the fallback image to display when the requested image cannot be found. The fallback must be a published image on the same account. Can be set as a query parameter, in a transformation template, or at the account level. > **Tip: Full reference and interactive examples** > See [`img404`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/variables-and-conditionals/#img404) #### `${variable}` - Variables User-defined variables can be declared in the query string and referenced throughout the query. Variable names are prefixed with `$`. Example: ```uri https://cdn.media.amplience.net/i/ampproduct/woman-checked-skirt-striped-bag?imageheight=300&h=$imageheight ``` > **Tip: Full reference and interactive examples** > See [`${variable}`](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/variables-and-conditionals/#variables) #### Conditionals Evaluates a comparison and returns one of two values. Format: `{($variable==value)?trueValue:falseValue}` Supported operators: `==`, `>`, `<`, `>=`, `<=`, `!=` Supported types: number, string (must be assigned to a variable first), boolean > **Tip: Full reference and interactive examples** > See [Conditionals](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/variables-and-conditionals/#conditionals) #### Expressions Mathematical expressions can be included in query values, wrapped in `{}`. Supports `+`, `-`, `*`, `/`. Variables can be used within expressions, and percentages are supported (e.g. `w={25%}`). > **Tip: Full reference and interactive examples** > See [Expressions](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/variables-and-conditionals/#expressions) ## SEO SEO-friendly path segments can be appended to image URLs to improve search engine indexing. The SEO text is included in the request path but does not affect the image returned. ```uri https://cdn.media.amplience.net/i/ampproduct/1377455-collection-spring/womens/spring/red-dress ``` > **Tip: Full reference and examples** > See [SEO and sets](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/sets/#seo-and-sets) ## Sets Sets are named groupings of assets. The Set API allows you to retrieve individual elements or full set metadata. ### Retrieving set images | Endpoint | Description | |---|---| | `GET /s/{account}/{setName}` | Returns the first element as an image. For video sets, the thumbnail is returned. Standard image parameters apply. | | `GET /s/{account}/{setName}/{n}` | Returns the nth element as an image. Indexing starts at 1. | | `GET /s/{account}/{setName}/{n}/{n}` | Returns the nth element from within a nested set. | > **Tip: Full reference and interactive examples** > See [Retrieving set images](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/sets/#retrieving-set-images) · [Return first element](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/sets/#set-first-element) · [Return nth element](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/sets/#set-nth-element) · [Return nested nth element](https://amplience.com/developers/docs/apis/media-delivery/media-delivery-reference/sets/#set-nested-element) ### Set metadata **Common parameters for all set metadata formats:** | Parameter | Description | |---|---| | `qual` | Whether URLs in the response are fully qualified. Default: `true`. | | `qry` | Query string appended to all set element URLs. Supports transformation template names. | | `deep` | Whether nested set structure is included in the response. Default: `false`. | | Format | Endpoint | Additional Parameters | |---|---|---| | JSONP | `GET /s/{account}/{setName}.js` | `func` - callback name; `arg` - optional argument | | JSON | `GET /s/{account}/{setName}.json` | - | | XML | `GET /s/{account}/{setName}.xml` | - | | Text | `GET /s/{account}/{setName}.txt` | Returns element URLs in plain text | | HTML | `GET /s/{account}/{setName}.html` | `ulCls` - CSS class on `