--- title: "Add a background to a reference image" method: POST path: "/v3/ai/image-generations/background-generations" tags: ["AiGenerator"] --- # Add a background to a reference image `POST /v3/ai/image-generations/background-generations` # AI Generator - Background Generation Background Generation allows the client application to provide a `reference_file_registration_id` as a reference for creating new AI-generated product photos. Our technology will generate new background content behind the image based on the prompt and other parameters submitted with the request. The padding values are used to position the product on the canvas. Use of this endpoint may result in the deduction of a credit depending on the terms of your license. ## The Background Generation Request The `BackgroundGenerationRequest` payload requires a reference image (`reference_file_registration_id`) and `prompt` and accepts the following parameters: | Parameter | Purpose | |---------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `reference_file_registration_id` _Required_ | Registered file id of the image being used as a reference. The `CustomerProduct` category **must** be used when registering the file. | | `prompt` | The primary text used for refined portion of the images. | | `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`). | | `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. | | `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. | | `left_percentage` | Percentage of padding to add to the left side of the item in the image. Default is 0. | | `right_percentage` | Percentage of padding to add to the right side of the item in the image. Default is 0. | | `top_percentage` | Percentage of padding to add to the top side of the item in the image. Default is 0. | | `bottom_percentage` | Percentage of padding to add to the bottom side of the item in the image. Default is 0. | | `background_file_registration_id` | Optional registered file id for use in influencing the generation of the background. The `ImageReference` category **must** be used when registering the file. | | `background_asset_id` | Optional asset id for use in influencing the generation of the background. | | `background_reference_generation` | Optional reference to a previously generated image for use in influencing the background generation. | | `background_reference_adherence` | Optional value to control how closely the AI follows your reference image. Accepted values are `flexible` and `strong`. Use flexible to focus on visual balance, or strong to preserve more of the reference image's details. | ## Fulfilled and Pending Results In many cases the result of this call will be the final fulfilled result. In these cases, you will see a `HTTP 200 OK` result and a payload including URLs to the result images and a `generation_request_id` value. However some generations may take more time than can be accommodated in the initial call. In these cases the result of this call is `HTTP 202 Accepted` and the payload will only contain a `generation_request_id` value. This value must be retained by the client for subsequent polling of the `GET v3/ai/image-generations/{generationRequestId}` Get Images Generation endpoint. ## Lifetime of Generated Images Generated images will be retained for 6 months after generation. ## Request body - BackgroundGenerationRequest - `reference_file_registration_id` string, nullable - `prompt` string, nullable - `product_id` integer, nullable - `project_code` string, nullable - `notes` string, nullable - `left_percentage` number, float, nullable - `right_percentage` number, float, nullable - `top_percentage` number, float, nullable - `bottom_percentage` number, float, nullable - `background_file_registration_id` string, nullable - `background_asset_id` string, nullable - `background_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. - `background_reference_adherence` 'flexible' | 'strong' ## Response `202` Returns the request ID for a pending request - PendingImageGenerationResponse - `generation_request_id` string, nullable ## Other responses - `400` — InvalidProduct - `403` — Product quota exceeded - `404` — Image not found - `409` — ConcurrencyConflict - `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/d069958d92a6/schema)