POST /v3/ai/image-generations/refine
AI Generator - Image Refining
Use a mask image and text prompts to modify content in a image from the Getty Images creative library (excluding illustrations and vectors). 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. To download a refined image, a traditional license product, such as Premium Access, that provides download access to the original creative image is required. Lastly, downloading a refined image requires the client to first download the original image.
The Image Refine Request
The ImageRefineRequest payload accepts the following
parameters:
| Parameter | Purpose | |
|---|---|---|
id | Required. The creative image id to extend. | |
prompt | The primary text used for refined portion of the images. | |
negative_prompt | Concepts to exclude from the refined portion. | |
product_id | If you have multiple AI Generation Getty Images products, indicate which one you would like to use for this refine request. If you have multiple products, this property is required. | |
notes | A note for the download. Some products require a note. | |
project_code | The project code for the download. Some products require a project code. | |
mask_url | Required. Specifies the location of the mask. |
Uploading mask image
Before calling the refine 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 refining 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 beta/ai/image-generations/{generationRequestId} Get Images Generation endpoint.
Lifetime of Generated Images
Generated images will be retained for 6 months after generation.
Servers
- https://api.gettyimages.com
Request headers
| Name | Type | Required | Description |
|---|---|---|---|
Content-Type |
String | Yes |
The media type of the request body.
Default value: "application/json" |
Request body fields
| Name | Type | Required | Description |
|---|---|---|---|
id |
String | No |
The image id to refine. This value is required. |
prompt |
String | No |
This is the primary text used for refining the images. |
project_code |
String | No |
The project code to use for the request. Some products require this value. |
notes |
String | No |
The notes to use for the request. Some products require this value. |
negative_prompt |
String | No |
Concepts to exclude from the result |
mask_url |
String | No |
The location of the mask. This value is required. |
product_id |
Integer | No |
If you have multiple Getty products, indicate which one you would like to use for this refine request |
How to start integrating
- Add HTTP Task to your workflow definition.
- Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
- Click Test request to test run your request to the API and see the API's response.