Generative AI Refine

Refine

The process of refining, often called “inpainting” on other platforms, allows users to mask a region of a previously generated image and then fill in the region with a person or object described via a text prompt. The mask needs to be made of black and white areas, where the white defines the area to be refined and the black defines the area to leave untouched. The mask should be the same size as the original image.

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.

Uploading a mask

Before calling the refine endpoint, a mask in JPG 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.

You may find it easier to test this by uploading your mask by using the upload endpoint on our Swagger page

Refer to Swagger for full technical documentation of the refine endpoint

Example

In this example, we’re going to replace this simple volleyball with a soccer ball.

Initial image generation parameters:
{ 
  "prompt": "white volleyball on a sandy beach, realistic"
} 
Generated Image:

AI Gen Refine - Original Image

Mask:

AI Gen Refine - Mask Image

Refine Parameters:
{ 
  "prompt": "soccer ball", 
  "mask_url": "https://api.gettyimages.com/v3/search/by-image/uploads/refine-volleyball-mask" 
} 
Refined Image:

AI Gen Refine - Refined Image