DocsDocsMedia/DAM

Image Proxy and Media API

Deliver stored images through the Enad Media CDN, configure allowed image domains, and build safe transformation URLs.

API
Media
Schema
media-api

The Image Proxy CDN serves stored Enad images at the requested size, format, and crop. Use asset APIs when you need to upload media, change metadata, move an asset into a folder, or create shareable access.

For delivery work, rely on the CDN URL shape, media URLs returned by APIs, app-level image-domain allowlists, and the transformation behavior below. Cache-key construction, cache retention, and edge freshness timing are not public contract details.

Choose the right surface

Configure the app image-proxy allowlist before an app imports or proxies images from external domains. Keep that decision at the app level so storefront code can treat delivery URLs as ordinary media URLs.

Delivery URL

GET https://media.enad.io/\{app_id\}/\{filename\}

The path includes the app identifier and the stored image filename. API responses that include image URLs are generated from the configured media CDN base host plus the stored image path.

The CDN endpoint returns processed image bytes. Upload, asset metadata, public asset-library reads, and authenticated DAM administration are separate API jobs.

Allowed domains

FactCurrent behavior
Media CDN hostThe default media CDN host is https://media.enad.io; runtime configuration can override the media CDN base host for generated URLs.
App-level image proxy allowlistApps expose an image_proxy_allowed_domains list in app responses.
Allowlist update payloadThe update payload is a domains array. Missing domains is rejected.
Allowed domain validationEach domain must be an FQDN value. Domains with a URL scheme, path, malformed host, or whitespace are rejected.
Empty list behaviorAn empty array clears the stored list. App reads then return an empty image_proxy_allowed_domains array.
Import and upload fallbackWhen an app has no configured image-proxy domains, external image import and upload URL validation fall back to the configured Media CDN base host.

Transform images

Add query parameters to the Media CDN URL when you need a resized, cropped, padded, blurred, converted, or background-removed image.

ParameterTypeDefaultDescription
widthu32-Target width in pixels, 1-5000.
heightu32-Target height in pixels, 1-5000.
qualityu880Output compression quality, 1-100.
formatstringOriginal format when supported, otherwise JPEGOutput format: webp, avif, png, jpeg, or jpg.
fitstringcontainResize mode. See Fit modes.
blurf32-Blur intensity, 0.0-100.0.
crop_x, crop_yi32Centered cropCrop offset in pixels for cover and crop. Out-of-range values are clamped.
fillstringTransparent padding for padSix-character hex color without #, for example FFFFFF.
bg_removebooleanfalseRemoves the image background. JPEG output is converted to PNG when needed to preserve transparency.

Fit modes

ModeBehaviorBest for
containResize directly to the target dimensions. With one dimension, the missing dimension is calculated from the original aspect ratio.Product thumbnails and previews.
coverFill the target dimensions and crop any excess.Hero images, banners, and card backgrounds.
scale-downResize only when the source image is larger than the target dimensions.Preventing upscaling.
cropFill the target dimensions, then crop to the exact output size.Fixed-size placeholders and strict layout grids.
padResize to fit inside the target box and pad the remaining space. Use fill for a solid background.Product-grid tiles where the full image must stay visible.
squeezeResize directly to the target dimensions.Non-photographic graphics and deliberate distortion effects.

Dimension rules

Request shapeResult
Only widthHeight is calculated from the original aspect ratio.
Only heightWidth is calculated from the original aspect ratio.
Both width and heightfit decides whether the image crops, pads, scales down, or resizes directly.
No dimensionsOriginal dimensions are used. Format conversion and quality still apply.

Request examples

These examples cover common resize, format, crop, blur, and background-removal requests.

GET https://media.enad.io/{app_id}/photo.jpg?width=800
GET https://media.enad.io/{app_id}/photo.jpg?format=webp&quality=90
GET https://media.enad.io/{app_id}/photo.jpg?width=1920&height=1080&fit=cover
GET https://media.enad.io/{app_id}/photo.jpg?width=800&blur=5.0
GET https://media.enad.io/{app_id}/photo.jpg?width=800&bg_remove=true

Keep application URL builders small: choose the closest width, pick the fit mode for the slot, and add format or quality only when the caller needs it.

Responses and limits

Successful responses return processed image bytes. The Content-Type header is image/png, image/jpeg, image/webp, or image/avif.

StatusMeaning
200Image found, transformed, and returned.
400Invalid parameters, out-of-range values, unsupported format, unsupported fit mode, or malformed URL.
404The app ID or filename does not exist.
502External proxy source fetch failed or returned a non-404 failure.
500Processing failed on the CDN side.

The maximum requested dimensions are 5000 x 5000 pixels. The minimum dimension is 1 pixel.

Storefront patterns

# Modern format delivery.
GET https://media.enad.io/{app_id}/photo.jpg?width=800&format=avif&quality=80

# Prevent upscaling.
GET https://media.enad.io/{app_id}/photo.jpg?width=800&height=800&fit=scale-down

# Consistent product-grid tiles.
GET https://media.enad.io/{app_id}/photo.jpg?width=400&height=400&fit=pad&fill=FFFFFF

Use a small breakpoint set, such as 400, 800, 1200, and 1600. Keep parameter order stable in application code so URLs are easier to compare, log, and reuse.

Image delete flows remove the stored source image and transformed derivatives, then request CDN cache cleanup by media URL prefix. Treat that purge as cleanup behavior, not as a guarantee that every edge stops serving stale bytes immediately.

Image Proxy and Media API

# Image proxy and Media API The Image Proxy CDN serves stored Enad images at the requested size, format, and crop. Use asset APIs when you need to upload media, change metadata, move an asset into a folder, or create shareable access. For delivery work, rely on the CDN URL shape, media URLs returned by APIs, app-level image-domain allowlists, and the transformation behavior below. Cache-key construction, cache retention, and edge freshness timing are not public contract details. ## Choose the right surface - Serve a stored image with the Media CDN URL. - Upload or edit image metadata with [Images API reference](/reference/images). - Work with files or videos from [Files API reference](/reference/files) or [Videos API reference](/reference/videos). - Browse public DAM content from [Media](/reference/media), [Folders](/reference/folders), or [Shareable Links](/reference/shareable-links). - Administer DAM content with [DAM administration](/reference/dam). Configure the app image-proxy allowlist before an app imports or proxies images from external domains. Keep that decision at the app level so storefront code can treat delivery URLs as ordinary media URLs. ## Delivery URL **GET** `https://media.enad.io/{app_id}/{filename}` The path includes the app identifier and the stored image filename. API responses that include image URLs are generated from the configured media CDN base host plus the stored image path. The CDN endpoint returns processed image bytes. Upload, asset metadata, public asset-library reads, and authenticated DAM administration are separate API jobs. ## Allowed domains | Fact | Current behavior | | --- | --- | | Media CDN host | The default media CDN host is `https://media.enad.io`; runtime configuration can override the media CDN base host for generated URLs. | | App-level image proxy allowlist | Apps expose an `image_proxy_allowed_domains` list in app responses. | | Allowlist update payload | The update payload is a `domains` array. Missing `domains` is rejected. | | Allowed domain validation | Each domain must be an FQDN value. Domains with a URL scheme, path, malformed host, or whitespace are rejected. | | Empty list behavior | An empty array clears the stored list. App reads then return an empty `image_proxy_allowed_domains` array. | | Import and upload fallback | When an app has no configured image-proxy domains, external image import and upload URL validation fall back to the configured Media CDN base host. | ## Transform images Add query parameters to the Media CDN URL when you need a resized, cropped, padded, blurred, converted, or background-removed image. | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `width` | `u32` | - | Target width in pixels, 1-5000. | | `height` | `u32` | - | Target height in pixels, 1-5000. | | `quality` | `u8` | `80` | Output compression quality, 1-100. | | `format` | `string` | Original format when supported, otherwise JPEG | Output format: `webp`, `avif`, `png`, `jpeg`, or `jpg`. | | `fit` | `string` | `contain` | Resize mode. See [Fit modes](#fit-modes). | | `blur` | `f32` | - | Blur intensity, 0.0-100.0. | | `crop_x`, `crop_y` | `i32` | Centered crop | Crop offset in pixels for `cover` and `crop`. Out-of-range values are clamped. | | `fill` | `string` | Transparent padding for `pad` | Six-character hex color without `#`, for example `FFFFFF`. | | `bg_remove` | `boolean` | `false` | Removes the image background. JPEG output is converted to PNG when needed to preserve transparency. | ## Fit modes | Mode | Behavior | Best for | |------|----------|----------| | `contain` | Resize directly to the target dimensions. With one dimension, the missing dimension is calculated from the original aspect ratio. | Product thumbnails and previews. | | `cover` | Fill the target dimensions and crop any excess. | Hero images, banners, and card backgrounds. | | `scale-down` | Resize only when the source image is larger than the target dimensions. | Preventing upscaling. | | `crop` | Fill the target dimensions, then crop to the exact output size. | Fixed-size placeholders and strict layout grids. | | `pad` | Resize to fit inside the target box and pad the remaining space. Use `fill` for a solid background. | Product-grid tiles where the full image must stay visible. | | `squeeze` | Resize directly to the target dimensions. | Non-photographic graphics and deliberate distortion effects. | ## Dimension rules | Request shape | Result | | --- | --- | | Only `width` | Height is calculated from the original aspect ratio. | | Only `height` | Width is calculated from the original aspect ratio. | | Both `width` and `height` | `fit` decides whether the image crops, pads, scales down, or resizes directly. | | No dimensions | Original dimensions are used. Format conversion and quality still apply. | ## Request examples These examples cover common resize, format, crop, blur, and background-removal requests. ```http GET https://media.enad.io/{app_id}/photo.jpg?width=800 GET https://media.enad.io/{app_id}/photo.jpg?format=webp&quality=90 GET https://media.enad.io/{app_id}/photo.jpg?width=1920&height=1080&fit=cover GET https://media.enad.io/{app_id}/photo.jpg?width=800&blur=5.0 GET https://media.enad.io/{app_id}/photo.jpg?width=800&bg_remove=true ``` Keep application URL builders small: choose the closest width, pick the fit mode for the slot, and add format or quality only when the caller needs it. ## Responses and limits Successful responses return processed image bytes. The `Content-Type` header is `image/png`, `image/jpeg`, `image/webp`, or `image/avif`. | Status | Meaning | |--------|---------| | `200` | Image found, transformed, and returned. | | `400` | Invalid parameters, out-of-range values, unsupported format, unsupported fit mode, or malformed URL. | | `404` | The app ID or filename does not exist. | | `502` | External proxy source fetch failed or returned a non-404 failure. | | `500` | Processing failed on the CDN side. | The maximum requested dimensions are 5000 x 5000 pixels. The minimum dimension is 1 pixel. ## Storefront patterns ```http # Modern format delivery. GET https://media.enad.io/{app_id}/photo.jpg?width=800&format=avif&quality=80 # Prevent upscaling. GET https://media.enad.io/{app_id}/photo.jpg?width=800&height=800&fit=scale-down # Consistent product-grid tiles. GET https://media.enad.io/{app_id}/photo.jpg?width=400&height=400&fit=pad&fill=FFFFFF ``` Use a small breakpoint set, such as 400, 800, 1200, and 1600. Keep parameter order stable in application code so URLs are easier to compare, log, and reuse. Image delete flows remove the stored source image and transformed derivatives, then request CDN cache cleanup by media URL prefix. Treat that purge as cleanup behavior, not as a guarantee that every edge stops serving stale bytes immediately. ## Related docs - [Asset library reads and DAM administration](/media/dam/latest) - [Public asset-library playground](/media/dam/playground) - [Media API reference](/reference/media) - [DAM administration reference](/reference/dam) - [Images API reference](/reference/images) - [Files API reference](/reference/files) - [Videos API reference](/reference/videos) - [Build a storefront page](/react-sdk/latest/guides/storefront-page)