v1
latestOpenAPI 3.0.42026-07-1376217536.1 KBRemove object(s)
AI Generator - Object Removal
Use a mask image to remove object content in a previously generated image or a previously licensed image from the Getty Images creative library. 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 downloading an image generated using a reference_asset_id, a traditional license product, such as Premium Access, that provides download access to the original creative image is required. Downloading an image generated using a reference_asset_id also requires the client to first download the original image.
The Remove Object Request
The RemoveObjectRequest payload accepts the following parameters. One, and only one, of either reference_asset_id or reference_generation must be used. Omitting or including both are invalid.
| Parameter | Purpose |
|---|---|
| reference_asset_id | Creative image id to modify. |
| reference_generation | Generation details of image to modify. |
| mask_url | Required: Specifies the location of the mask. |
| 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 | This is for use by Getty Images customers only (not iStock). If your Getty Images Generative AI product requires project codes, use of this parameter is required. Otherwise, this parameter must be excluded from the request. The products endpoint (GET /v3/products) provides this information. |
Uploading mask image
Before calling the endpoint, a mask in JPEG format must be uploaded to https://api.gettyimages.com/v3/search/by-image/uploads/{CLIENT_IMAGE.jpg}, where the client defines the {CLIENT_IMAGE.jpg} portion of the URL.
For example, using cURL:
curl -i -X PUT https://api.gettyimages.com/v3/search/by-image/uploads/my-test-image.jpg -H 'Content-Type: image/jpeg' -H 'Api-Key: API_KEY' --data-binary "@testimage.jpg"
Once the mask has been uploaded, use the full URL as the mask_url.
- Uploaded files must be 10MB or smaller.
- Uploads to the same URL will overwrite each other, so ensure that the client application is handling naming uniqueness appropriately.
- Uploads expire after 24 hours.
- Uploads and object removal must be performed using the same API Key.
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
Response
Returns the request ID for a pending request to refine images