Documentation

Background color parameter in Dynamic Media Open API does not apply as expected

Last update: Thu Feb 05 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

If you are using the background-color parameter in the Dynamic Media Open API and the color does not appear, the issue occurs because the parameter only applies when the original image has transparency and is delivered in a format that does not support transparency, such as JPG. To resolve this, request the image in JPG format and disable auto-formatting.

Description description

Environment

  • Product: Experience Manager Assets – Dynamic Media Open API
  • Version/Constraints: Applicable when delivering assets with transparency using the background-color parameter.

Issue/Symptoms

The background-color parameter does not appear to apply when requested through the delivery API. This can result in:

  • Transparent areas remaining unchanged when the image is delivered.
  • Confusion about whether the parameter is functional.

For example, if you request a PNG image with transparency and include background-color=rgb,00ff00, the image will still display transparency instead of the specified color. This makes it difficult to achieve a solid background color for assets intended for formats like JPG.

Resolution resolution

To make the background-color parameter work as expected in Dynamic Media Open API:

  1. Request the asset in a format that does not support transparency, such as JPG.

    PNG supports transparency, so the background color will not apply if you deliver the image as PNG.

  2. Disable auto-formatting by adding auto-format=false to the query string.

    Auto-formatting can override your chosen format and prevent the parameter from applying.

  3. Specify the background color using RGB values in the request.

    Example: background-color=rgb,00ff00 fills transparent areas with bright green.

Sample URLs

Here is an image on a test instance that has an alpha channel for transparency:

https://{delivery-instance}/adobe/assets/urn:aaid:aem:{asset-id}/as/Backpack_vert.png?width=1024&quality=65

To apply the background color, request the image in JPG format and disable auto-formatting:

https://{delivery-instance}/adobe/assets/urn:aaid:aem:{asset-id}/as/Backpack_vert.jpg?auto-format=false&width=1024&quality=65&background-color=rgb,00ff00

API Call Example

You can make this request using a standard HTTP GET call:

GET https://{delivery-instance}/adobe/assets/urn:aaid:aem:{asset-id}/as/Backpack_vert.jpg?auto-format=false&width=1024&quality=65&background-color=rgb,00ff00

Or use curl:

curl "https://{delivery-instance}/adobe/assets/urn:aaid:aem:{asset-id}/as/Backpack_vert.jpg?auto-format=false&width=1024&quality=65&background-color=rgb,00ff00"

Explanation:

  • auto-format=false ensures the API respects your format choice.
  • background-color=rgb,00ff00 replaces transparency with green.
  • The original image must have transparency for this to take effect.
recommendation-more-help
3d58f420-19b5-47a0-a122-5c9dab55ec7f