---
title: "Replace the background of an existing image"
method: POST
path: "/v3/ai/image-generations/background-replacement"
tags: ["AiGenerator"]
---

# Replace the background of an existing image

`POST /v3/ai/image-generations/background-replacement`

# AI Generator - Background Replacement


Background Replacement allows the client application to change the background of an existing Getty Images creative image or an existing generated image through the use of prompt text or color information. Four images will be generated when prompt text is submitted, while one image will be generated when color information is submitted.


Use of this endpoint is restricted to clients with an AI Generation license product and may result in the deduction of a credit depending on the terms of your license. When generating new images using a reference_asset_id, the reference image must first be licensed (downloaded) through a traditional license product such as Premium Access before the generated image can be downloaded..


## The Background Replacement Request


The BackgroundReplacement Request payload requires one, and only one, reference image (reference_asset_id or reference_generation) and accepts the following optional parameters:

| Parameter              | Purpose                                                                                                                                                                                                                                                                                                                                               |
|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `reference_asset_id`   | Creative image ID of the image being used as a reference.                                                                                                                                                                                                                                                                                             |
| `reference_generation` | Generation details of the image being used as a reference.                                                                                                                                                                                                                                                                                            |
| `prompt`               | The primary text used for the generation of the images.                                                                                                                                                                                                                                                                                               |
| `negative_prompt`      | Concepts to _exclude_ from the result.                                                                                                                                                                                                                                                                                                                |
| `background_color`     | Color information to use for the background replacement. The format is hexadecimal [web colors](https://en.wikipedia.org/wiki/Web_colors), _e.g. #0099CC_.                                                                                                                                                                                            |
| `media_type`           | Media type of the results: `photography` or `illustration`                                                                                                                                                                                                                                                                                            |
| `negative_prompt`      | Concepts to _exclude_ from the result.                                                                                                                                                                                                                                                                                                                |
| `product_id`           | If you have multiple AI Generation Getty Images products, indicate which one you would like to use for this generation request.  If you have multiple products, this property is _required_. Can be retrieved from products (`GET /v3/products`).                                                                                                     |
| `project_code`         | If your Getty Images Generative AI product requires project_codes, use of this parameter is required. If your product does not require a project_code, this parameter must be excluded from the request. This is for use by Getty Images customers only (not iStock). The products endpoint (`GET /v3/products`) provides this information.           |
| `notes`                | This is an optional free text parameter often used by clients who wish to include notes specific to their integration. This is for use by Getty Images customers only (not iStock). The products endpoint (`GET /v3/products`) provides this information.                                                                                             |

## Request body

- ReplaceBackgroundRequest
  - `prompt` string, nullable
  - `reference_asset_id` string, nullable
  - `reference_generation` ReferenceGeneration
    - `generation_request_id` string, nullable — The id from a previous request to generate images.
    - `index` integer — The index of the image from the specific images generation.
  - `product_id` integer, nullable
  - `media_type` 'photography' | 'illustration'
  - `negative_prompt` string, nullable
  - `background_color` string, nullable
  - `project_code` string, nullable
  - `notes` string, nullable

## Response `202`

Returns the request ID for a pending request to replace a background

- PendingImageGenerationResponse
  - `generation_request_id` string, nullable

## Other responses

- `400` — InvalidProduct
- `403` — NotAuthorized
- `404` — GenerationRequestIdNotFound
- `409` — ConcurrencyConflict
- `410` — GenerationRequestGone
- `429` — TooManyConcurrentGenerations

---

[API](https://skmtc.net/gettyimages/apis/getty-images-api.md) · [All operations](https://skmtc.net/gettyimages/apis/getty-images-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gettyimages/getty-images-api/revisions/29f239eeae86/schema)