Background Replacement

The Background Replacement parameter (bg-replace) accepts a string prompt value. Based on the prompt, bg-replace will identify a subject or object within a photo and replace the background based on the prompt.

Here's an example of an original image of a runner:

By applying bg-replace=in%20desert, the Background Replacement API replaces the original background with the prompt (in desert):

Supported Image Size and Resolution

Images larger than 12 megabytes or 50 megapixels will be optimized for background replacement by default.

Recommendations

• Images with good lighting and high contrast between the foreground and background work best for background replacement.
• Blurry or single-color backgrounds are preferred.
• Use an image with a sharp foreground since blurry foregrounds may be replaced.
• For product images, the whole product should be visible and not cut off.
• The main subject or product should be in focus.
• Avoid hard shadows and reflections.
• Natural and eye-level angles are best.

Preprocessing

Background replacement can be a time-intensive process. You can speed up perceived performance by warming the cache. This can be done by issuing a rendering request to the Background Replacement API before publicly making the image available.

Handling failures

If bg-replace fails, we will return the original image by default. You can control this behavior by using bg-replace-fallback.

Additionally, an additional header will be included in the response:

X-Imgix-Bg-Replace-Failure-Reason

Async Responses

For many requests, the first time a background is replaced, it will return within a few seconds. During higher loads, you may receive a temporary response while we're processing your request. This temporary response will send a 200 status code or a 423 error if bg-replace-fallback=false is present. Regardless of the bg-replace-fallback setting, the cached response will be set to a short interval so that the requested background replacement image can be returned.

This temporary response will also have the following header:

X-Imgix-Bg-Replace-Failure-Reason: Processing background removal request.

You can continue to retry the request until you receive the processed image without the failure header. All subsequent requests will return the image with the background replaced.

Questions

Please reach out to your Account Manager or to Support if you have any questions or feedback.