Media delivery API overview
The Media Delivery API gives you access to the features of Dynamic Media - a URL-based service that transforms, optimizes, and delivers images, sets, and video on the fly. You upload a single high-quality master asset, and every variant your site needs - every size, crop, format, and composition - is rendered at request time by appending parameters to the asset's URL.
Why Dynamic Media?Link copied!
Images typically make up the largest share of a web page’s payload - and page speed drives engagement and conversion. The right image, size, and format aren’t fixed, they depend on several factors:
- Viewport - from phone screens to ultra wide monitors
- Pixel density - high-density (retina) displays need 2× or 3× the pixels
- Connection speed - everything from 2G to 5G
- Browser support - not all browsers support modern formats like WebP and AVIF
HTML gives you native tools to handle images. The srcset and sizes attributes let the browser pick the best-sized candidate from a list you provide, and the <picture> tag adds format fallbacks and art direction through media conditions.
Dynamic Media builds on HTML features and removes the manual work behind them:
-
One asset, every rendition - Your
srcsetcandidates become the same master URL with differentw=values, so no renditions are manufactured. -
Simpler markup, same power - Amplience Smart Images (
fmt=auto) picks the best format for each browser automatically - no<source>elements needed. Point of interest cropping re-crops the master to any aspect ratio while keeping the subject in frame, replacing manually cut portrait and landscape versions.
There is no SDK to install and no build step. If your code can construct a URL, it can use the API.
URL structureLink copied!
Dynamic Media URLs follow the pattern:
| Segment | Description |
|---|---|
{type} | Asset type: i for images, s for sets, v for video |
{account} | Your Amplience account identifier |
{assetName} | The name of the published asset |
For example, this resizes an image to 300 pixels wide:
Chaining parameters together
Combine multiple parameters in a single URL with &.
Here the image is resized and flipped vertically:
The Media Delivery API guide documents every parameter with interactive examples you can adjust live.
Example- Responsive image URLLink copied!
The following builds a fully responsive, format-optimized image from a single master asset using a plain <img> tag:
Each part of the tag does a specific job:
| Mechanism | Handled by | What it does |
|---|---|---|
srcset + sizes | Browser | Picks the best-sized candidate for the viewport width and device pixel ratio |
w | Media Delivery API | Renders the chosen width from the master - no renditions are created or stored |
fmt=auto | Media Delivery API | Returns the most efficient format the browser supports (AVIF, WebP, JP2, JPEG, or PNG) |
qlt=default | Media Delivery API | Applies the tuned default quality setting for whichever format was chosen |
Every candidate is the same asset. Adding a breakpoint means adding a URL, not producing an image - and if the design calls for a different shape at small sizes, appending sm=aspect&aspect=1:1&scaleFit=poi to those candidates re-crops the same master around its point of interest, still without a <picture> tag or a separately cut asset.
Try it out
The fastest way to learn the API is to use it. The Media Delivery API guide includes interactive examples for most parameters - adjust the controls, watch the image and URL update, and copy the result straight into your code.
Resize, scale, crop and adjust imagesLink copied!
Resize, scale, crop, rotate, flip, and adjust images by adding query parameters to the asset URL. Sizing and cropping parameters accept pixels or percentages, and operations can be applied before or after resizing (crop vs pcrop). Adjustments include sharpening, blur, gamma, and hue/saturation/brightness.
See Sizing, Cropping and rotation, and Image adjustments.
Crop without losing the subjectLink copied!
Set a scale mode and a point of interest, and the crop follows the subject instead of the image center.
Scale modes control what happens when an image doesn't fit the requested dimensions - crop to fit, stretch, maintain aspect ratio, or align to an edge or corner. Combined with a point of interest, the crop follows a focal region instead of the image center, so one master renders to portrait, landscape, and square without losing the subject:
The point of interest can be set visually in Content Hub and stored as asset metadata, then referenced in URLs via metadata tokens - so the URL never hard-codes coordinates. Amplience image recognition can populate focal-point metadata automatically when a face is detected, removing even the manual step.
Convert and compress imagesLink copied!
Convert between JPEG, PNG, GIF, BMP, WebP, AVIF, and JP2 with fmt, and control compression with qlt - globally, per format, or using tuned platform defaults (qlt=default).
With Amplience Smart Images, fmt=auto returns the most efficient format each browser supports. On accounts with Accelerated Media this includes AVIF, with file sizes up to 50% smaller than JPEG and 20% smaller than WebP. Accelerated Media also adds the VP9 and HEVC video codecs, which encode video at roughly 40% of the size of VP8 and H264.
See Format and quality.
Add layers and textLink copied!
Composite multiple images - for example, a product shot with a promotional roundel - or render styled text over an image, all within a single URL. Layers can be positioned, anchored, and made semi-transparent, and a blank canvas layer can serve as the base.
See Layers and text.
Add conditional logicLink copied!
Declare variables, evaluate conditional expressions, and perform arithmetic - for example, swapping a roundel or changing a layout based on the requested size.
Reuse parameters with templatesLink copied!
Save named lists of Dynamic Media parameters in Content Hub as transformation templates, then apply them to any URL by wrapping the name in $ characters:
Templates solve three problems at once. They keep complex URLs short - a point-of-interest crop that would otherwise take several metadata-token parameters becomes a single token. They apply the same parameters consistently across every URL that references them. And most usefully, they centralize change: update and re-publish a template in Content Hub and every URL using it picks up the new parameters, with no changes to your website code. Multiple templates can be combined in a single URL, alongside ordinary parameters:
In the responsive example above, the point-of-interest and quality parameters are natural template candidates - the one exception is fmt=auto, which must appear in the image URL itself and cannot be included in a transformation or root template.
Templates are created, edited, and published in Content Hub. See the transformation templates guide for the full workflow.
Read asset metadataLink copied!
Every asset can carry metadata - captured EXIF data, or custom schemas such as product information and point of interest. Metadata is retrievable as JSON, XML, or JSONP, and can be referenced inside transformation queries via tokens like {$this.metadata...}:
See Metadata in the API reference, and the asset metadata guide for defining schemas and adding metadata to assets.
Deliver a set of assetsLink copied!
Sets are named groupings of assets, such as all the images for one product. The API can return a single element as an image, with all image transformations available, or the whole set's contents as JSON, XML, text, or ready-made HTML:
See Sets.
Deliver videoLink copied!
Serve video by transcode profile, with thumbnails generated automatically at ingest. Poster frames and thumbnails are images, so the full image API applies to them. Metadata endpoints and generated HTML embeds are also available.
See Video in the API reference and working with video for transcode profiles and ingestion.
Customize SVGsLink copied!
SVGs are delivered through a dedicated graphics endpoint. They can be served statically, rasterized into any supported image format (and then used like any other image - as a layer, for instance), or customized at render time by substituting text and colors through URL parameters:
Read more in the SVG guide.
Frequently asked questionsLink copied!
What is the Amplience Media Delivery API?Link copied!
The Media Delivery API is a URL-based API that provides access to Amplience Dynamic Media. It transforms, optimizes, and delivers images, sets, and video at request time: you append query parameters to an asset's URL to resize, crop, convert, or composite it, and every variant is rendered on the fly from a single master asset.
Do I need an SDK to use the Media Delivery API?Link copied!
No. There is no SDK to install and no build step. Any code that can construct a URL can use the Media Delivery API - transformations are requested by appending query parameters, such as ?w=300, to the URL of a published asset.
Does transforming an image change the original asset?Link copied!
No. Transformations are applied at delivery time and rendered from the master asset, which is never modified. The same master image can serve any number of sizes, crops, formats, and compositions simultaneously.
How do I resize an image with the Media Delivery API?Link copied!
Add the w (width) or h (height) parameter to the image URL, with the value in pixels - for example ?w=300. If only one dimension is specified, the other is calculated automatically to preserve the image's aspect ratio.
How do I automatically serve WebP or AVIF to browsers that support them?Link copied!
Add fmt=auto to the image URL. Amplience Smart Images then returns the most efficient format the requesting browser supports - AVIF, WebP, JP2, JPEG, or PNG - without any <picture> tag format fallbacks in your markup. AVIF delivery requires Accelerated Media to be enabled on your account.
How do I crop an image to different aspect ratios without losing the subject?Link copied!
Set a point of interest on the image and add scaleFit=poi to the URL. The crop then follows the focal region instead of the image center, so a single master renders to portrait, landscape, or square with the subject kept in frame. The point of interest can be set visually in Content Hub and stored as asset metadata, so URLs never need to hard-code coordinates.
What is a transformation template?Link copied!
A transformation template is a named list of Dynamic Media parameters stored on your account and referenced in image URLs by wrapping the name in $ characters - for example ?$example-template$. Updating and re-publishing a template applies the change to every URL that uses it, without modifying website code. Templates are created and published in Content Hub. Note that fmt=auto cannot be included in a transformation template.
Can the Media Delivery API deliver video?Link copied!
Yes. Video is delivered by transcode profile (for example mp4_720p), with thumbnails generated automatically when the video is ingested. Poster frames and thumbnails are images, so all image transformation parameters apply to them, and metadata endpoints and generated HTML embeds are also available. With Accelerated Media enabled, the VP9 and HEVC codecs are supported.
Can I transform SVG images with the Media Delivery API?Link copied!
Yes, using delivery URLs that start with cdn.graphics.amplience.net. SVGs can be served statically, rasterized into formats such as JPEG or PNG (and then used like any other image, for example as a layer), or customized at render time by substituting text and color values through URL parameters.