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

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 in the overview for more detail.

Info

For full documentation including interactive examples, see the Media Delivery API guide.

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.

Full reference and interactive examples

See Sizing · w · h · maxW · 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

Full reference and interactive examples

See Scale mode · sm · sm=edge · 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

Full reference and interactive examples

See scaleFit=poi in the poi example.

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

Full reference and interactive examples

See 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

Full reference and interactive examples

See 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.

Full reference and interactive examples

See 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.

Full reference and interactive examples

See crop · ecrop · pcrop · pecrop · rotate · protate · 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. 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.

Full reference and examples

See fmt · 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.

Full reference and interactive examples

See qlt · 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:

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.

Full reference and examples

See dpi · dpiFilter · strip · fmt.jpeg.interlaced · 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:

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

Full reference and interactive examples

See 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.

Full reference and interactive examples

See unsharp · cm · cm=copy · bg · blur · noiser · gamma · 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:

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.

Full reference and interactive examples

See Layers · src · top, left, bottom, right · anchor · opacity · visible · canvas

Text layers

Text can be rendered as a layer on top of an image.

Example:

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.

Full reference and interactive examples

See 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.

Full reference and examples

See metadata=true · 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.

Full reference and interactive examples

See Referencing metadata in queries

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.

Full reference and interactive examples

See img404

${variable} - Variables

User-defined variables can be declared in the query string and referenced throughout the query. Variable names are prefixed with $.

Example:

https://cdn.media.amplience.net/i/ampproduct/woman-checked-skirt-striped-bag?imageheight=300&h=$imageheight

Full reference and interactive examples

See ${variable}

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

Full reference and interactive examples

See 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%}).

Full reference and interactive examples

See 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.

https://cdn.media.amplience.net/i/ampproduct/1377455-collection-spring/womens/spring/red-dress

Full reference and examples

See 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.

Full reference and interactive examples

See Retrieving set images · Return first element · Return nth element · Return nested nth 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 <ul>; liCls - CSS class on <li>; size - adds width and height attributes to <img> tags when true

Full reference and examples

Se. Set metadata · JSONP format · JSON format · XML format · Text format · HTML format · SEO and sets

Video

Video assets are accessed by including the transcode profile name in the URL path.

Format: GET /v/{account}/{videoName}/{profile}

Example:

https://cdn.media.amplience.net/v/ampproduct/ski-collection/mp4_720p?protocol=https

Omitting the profile returns the poster frame (or the first frame if no poster has been set).

Add protocol=https to the video URL to serve over HTTPS. Can also be set in the account root template.

Video thumbnails

100 thumbnails are generated at regular intervals during ingest. Standard image manipulation parameters can be applied.

Endpoint	Description
GET /v/{account}/{videoName}	Returns the poster frame, or the first generated thumbnail if no poster is set.
GET /v/{account}/{videoName}/thumbs/{frame}	Returns a specific thumbnail by frame index (e.g. frame_0020.png).

Full reference and interactive examples

See Video thumbnails · Return poster frame · Return specified thumbnail

Video metadata

Common parameters for all video metadata formats:

Parameter	Description
qual	Whether video URLs in the response are fully qualified. Default: true.
profile	Return metadata for the specified profile only.

Format	Endpoint	Additional Parameters
JSONP	GET /v/{account}/{videoName}.js	func - callback name; arg - optional argument
JSON	GET /v/{account}/{videoName}.json	-
XML	GET /v/{account}/{videoName}.xml	-
Text	GET /v/{account}/{videoName}.txt	-
Sitemap	GET /v/{account}/{videoName}.sitemap	Generates a sitemap from video metadata

Full reference and examples

See Video metadata · JSONP format · JSON format · XML format · Text format · Sitemap

HTML video embeds

Append .html to a video URL to return a complete HTML page with <video> and <source> elements for each transcode profile.

Format: GET /v/{account}/{videoName}.html

Parameter	Type	Default	Description
preload	auto | metadata | none	auto	Controls browser preload behaviour
loop	boolean	false	Loops the video continuously
controls	boolean	true	Shows player controls
autoplay	boolean	false	Starts playback on page load
resize	boolean	true	Resizes the video to fit the screen
snippet	boolean	false	Returns only the <video> tag instead of a full HTML page
bitrate	integer	-	Selects the profile with the closest matching bitrate
width	integer	-	Width of the video in pixels
height	integer	-	Height of the video in pixels
css	string	-	Style attributes applied to the <video> tag
bodyCSS	string	-	Style attributes applied to the <body> tag

Full reference and interactive examples

See Generating HTML video embeds

Accelerated Media

Accelerated Media is an optional add-on that unlocks the following features:

• Amplience Smart Images - automatic format selection via fmt=auto
• AVIF format - next-generation image compression
• VP9 and HEVC video codecs

To enable Accelerated Media on your account, contact your Account Manager.

Related pages

• Media Delivery API overview
• Media cache settings
• Video transcode profiles
• Working with video
• Amplience Smart Images