Getty Images Generations API
The Generations API from Getty Images — 12 operation(s) for generations.
OpenAPI Specification
openapi: 3.0.1
info:
title: Getty Images Generations API
version: '3'
description: '
Developer resources for the Getty Images API including SDK, documentation,
release notes, status, notifications and sample code.'
security:
- Api-Key: []
- OAuth2: []
tags:
- name: Generations
paths:
/v3/ai/image-generations:
post:
tags:
- Generations
summary: Generates images from a prompt
description: "# AI Generator - Generate Images\n\nUse a text prompt to generate images. Use of this endpoint is restricted to clients with an AI Generation license\nproduct.\n\n## The Image Generations Request\n\nThe `ImageGenerationsRequest` payload to be posted contains the required `prompt` as well as some other optional\nparameters:\n\n| Parameter | Purpose |\n|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `prompt` _Required_ | The primary text used for the generation of the images. |\n| `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`). |\n| `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. |\n| `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. |\n| `negative_prompt` | Concepts to _exclude_ from the result |\n| `seed`\t\t | To create new images that have a similar aesthetic, include the seed value from a set of previously generated images. Seed can also be used to reproduce previous results. |\n| `aspect_ratio` | The \"width:height\" aspect ratio of the resultant images. Must be one of: `1:1`, `3:4`, `4:3`, `9:16`, or `16:9` |\n| `media_type` | Media type of the results: `photography` or `illustration` |\n| `mood` | Can be `black_and_white`, `warm`, `cool`, `natural`, `vivid`, `dramatic`, or `bold` |\n| `lens_type` | Can be `wide_angle` or `telephoto` |\n| `depth_of_field` | Can be `shallow` or `deep` |\n\n## Fulfilled and Pending Results\n\nIn many cases the result of this call will be the final fulfilled result. In these cases, you will see a `HTTP 200 OK`\nresult and a payload including URLs to the result images and a generation request `id` value.\n\nHowever some generations may take more time than can be accommodated in the initial call. In these cases the result of\nthis call is `HTTP 202 Accepted` and the payload will only contain a generation request `id` value. This value must be\nretained by the client for subsequent polling of the `GET v3/ai/image-generations/{generationRequestId}` Get Images Generation endpoint.\n\n## Lifetime of Generated Images\n\nGenerated images will be retained for 6 months after generation.\n"
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationsRequest'
text/json:
schema:
$ref: '#/components/schemas/ImageGenerationsRequest'
application/*+json:
schema:
$ref: '#/components/schemas/ImageGenerationsRequest'
responses:
'200':
description: Returns the result of a request to generate images
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationsResponse'
'202':
description: Returns the request ID for a pending request
content:
application/json:
schema:
$ref: '#/components/schemas/PendingImageGenerationResponse'
'400':
description: The request was invalid
'403':
description: Product quota exceeded
'429':
description: TooManyConcurrentGenerations
/v3/ai/image-generations/{generationRequestId}:
get:
tags:
- Generations
summary: Get generated images from a previous generation request
description: '# AI Generator - Get Generated Images
Gets a previously generated set of images. This endpoint is used after a call to `POST v3/ai/image-generations`, passing the `id` value from the result of that call.
## Fulfilled and Pending Results
Like the `POST v3/ai/image-generations` endpoint, the result of calling this endpoint will be either:
- `HTTP 200 OK` with the generated images'' URLs and a generation request `id` value
- `HTTP 202 Accepted` with the payload only containing a generation request `id` value
`HTTP 202 Accepted` is returned in the case where the generation of images has not yet completed. In this case it is expected that the client will occasionally poll this endpoint until a `HTTP 200 OK` result with a full payload is returned.
## Lifetime of Generated Images
Generated images will be retained for 6 months after generation.
'
parameters:
- name: generationRequestId
in: path
description: The ID from a previous request to generate images
required: true
style: simple
schema:
type: string
responses:
'200':
description: Returns the result of a request to generate images
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationsResponse'
'202':
description: Returns the request ID for a pending request
content:
application/json:
schema:
$ref: '#/components/schemas/PendingImageGenerationResponse'
'400':
description: InvalidProduct
'403':
description: NotAuthorized
'404':
description: The request ID was not found
'410':
description: GenerationRequestGone
'429':
description: TooManyConcurrentGenerations
/v3/ai/image-generations/{generationRequestId}/images/{index}/variations:
post:
tags:
- Generations
summary: Get variations on a generated image
description: '# AI Generator - Generate Variations
Generate image variations from a previously-generated image.
## The Image Variation Request
The `ImageVariationRequest` payload to be posted contains the optional
parameters:
| Parameter | Purpose |
|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `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. |
## 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.
'
parameters:
- name: generationRequestId
in: path
description: The ID from a previous request to generate images
required: true
style: simple
schema:
type: string
- name: index
in: path
description: The index of the image from the specific images generation
required: true
style: simple
schema:
type: integer
format: int32
requestBody:
description: Request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ImageVariationRequest'
text/json:
schema:
$ref: '#/components/schemas/ImageVariationRequest'
application/*+json:
schema:
$ref: '#/components/schemas/ImageVariationRequest'
responses:
'200':
description: Returns the result of a request to generate a variation of images
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationsResponse'
'202':
description: Returns the request ID for a pending request to generate a variation of images
content:
application/json:
schema:
$ref: '#/components/schemas/PendingImageGenerationResponse'
'400':
description: InvalidProduct
'403':
description: Product quota exceeded
'404':
description: Either the generation id does not exist, the index is incorrect, or the generation is still pending
'429':
description: TooManyConcurrentGenerations
/v3/ai/image-generations/refine:
post:
tags:
- Generations
summary: Refine a creative image
description: "# AI Generator - Image Refining\n\nUse a mask image and text prompts to modify content in a image from the Getty Images creative library (excluding illustrations and vectors).\nUse 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. \nTo download a refined image, a traditional license product, such as Premium Access, that provides download access to the original creative image is required.\nLastly, downloading a refined image requires the client to first download the original image.\n \n\n## The Refine Request\n\nThe `RefineRequest` payload one, and only one, reference image (`reference_asset_id`, `reference_generation`) and accepts the following\nparameters:\n\n| Parameter | Purpose |\n|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `reference_asset_id`| Creative image id to modify. |\n| `reference_generation`| Generation details of image to modify. |\n| `prompt`\t\t | The primary text used for refined portion of the images. |\n| `negative_prompt` | Concepts to _exclude_ from the refined portion. |\n| `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`). |\n| `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. |\n| `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. |\n| `mask_url` | Required. Specifies the location of the mask. | |\n\n## Uploading mask image\n\nBefore 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.\n\nFor example, using cURL:\n\n``` sh\ncurl -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\"\n```\n\nOnce the mask has been uploaded, use the full URL as the `mask_url`.\n\n- Uploaded files must be 10MB or smaller.\n- Uploads to the same URL will overwrite each other, so ensure that the client application is handling naming uniqueness appropriately.\n- Uploads expire after 24 hours.\n- Uploads and refining must be performed using the _same_ API Key.\n\n## Fulfilled and Pending Results\n\nIn many cases the result of this call will be the final fulfilled result. In these cases, you will see a `HTTP 200 OK`\nresult and a payload including URLs to the result images and a `generation_request_id` value.\n\nHowever some generations may take more time than can be accommodated in the initial call. In these cases the result of\nthis call is `HTTP 202 Accepted` and the payload will only contain a `generation_request_id` value. This value must be\nretained by the client for subsequent polling of the `GET v3/ai/image-generations/{generationRequestId}` Get Images Generation endpoint.\n\n## Lifetime of Generated Images\n\nGenerated images will be retained for 6 months after generation.\n"
requestBody:
description: Request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/RefineRequest'
text/json:
schema:
$ref: '#/components/schemas/RefineRequest'
application/*+json:
schema:
$ref: '#/components/schemas/RefineRequest'
responses:
'200':
description: Returns the result of a request to refine an image
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationsResponse'
'202':
description: Returns the request ID for a pending request to refine an image
content:
application/json:
schema:
$ref: '#/components/schemas/PendingImageGenerationResponse'
'400':
description: InvalidProduct
'403':
description: Product quota exceeded
'404':
description: Image not found
'410':
description: GenerationRequestGone
'429':
description: TooManyConcurrentGenerations
/v3/ai/image-generations/extend:
post:
tags:
- Generations
summary: Extend a creative image
description: '# AI Generator - Image Extension
Use text prompts and numerical values to extend the content beyond the borders of 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 an extended image, a traditional license product, such as Premium Access, that provides download access to the original creative image is required.
Lastly, downloading an extended image requires the client to first download the original image.
Extension involves adding content to one or more sides of an image by specifying a percentage by which you want the image extended.
This means that the aspect ratio of the generated images will differ from the original unless the same value is specified for all four sides.
Additionally, the pixel dimensions on the longest side will remain the same - 612px for the
images provided in this endpoint''s response, 1024px and 4096px on the images retrieved through the download process.
## The Extend Request
The `ExtendRequest` payload requires one, and only one, reference image (`reference_asset_id`, `reference_generation`) and requires at least one percentage to be greater than zero (`left_percentage`, `right_percentage`, `top_percentage`, or `bottom_percentage`) and accepts the following optional
parameters:
| Parameter | Purpose |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `reference_asset_id`| Creative image id to modify. |
| `reference_generation`| Generation details of image to modify. |
| `prompt` | The primary text used for the extended portion of the images. |
| `negative_prompt` | Concepts to _exclude_ from the extended portion. |
| `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 to add to the left side of the image. This must be a float that is equal to or greater than 0. Default is 0. |
| `right_percentage` | Percentage to add to the right side of the image. This must be a float that is equal to or greater than 0. Default is 0. |
| `top_percentage` | Percentage to add to the top side of the image. This must be a float that is equal to or greater than 0. Default is 0. |
| `bottom_percentage` | Percentage to add to the bottom side of the image. This must be a float that is equal to or greater than 0. Default is 0. |
## 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.
'
requestBody:
description: Request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ExtendRequest'
text/json:
schema:
$ref: '#/components/schemas/ExtendRequest'
application/*+json:
schema:
$ref: '#/components/schemas/ExtendRequest'
responses:
'200':
description: Returns the result of a request to extend an image
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationsResponse'
'202':
description: Returns the request ID for a pending request to extend an image
content:
application/json:
schema:
$ref: '#/components/schemas/PendingImageGenerationResponse'
'400':
description: InvalidProduct
'403':
description: Product quota exceeded
'404':
description: Image not found
'410':
description: GenerationRequestGone
'429':
description: TooManyConcurrentGenerations
/v3/ai/image-generations/background-removal:
post:
tags:
- Generations
summary: Remove a background
description: "# AI Generator - Background Removal\nUse 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.\nWhen 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.\n\n## The Background Removal Request\n\nThe `BackgroundRemovalRequest` payload requires one, and only one, reference image (`reference_asset_id`, `reference_generation`) and accepts the following optional\nparameters:\n\n| Parameter\t\t\t | Purpose |\n|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `reference_asset_id`| Creative image id to modify. |\n| `reference_generation`| Generation details of image to modify. | |\n| `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`). |\n| `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. |\n| `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. | |\n\n## Fulfilled and Pending Results\n\nIn many cases the result of this call will be the final fulfilled result. In these cases, you will see a `HTTP 200 OK`\nresult and a payload including URLs to the result images and a `generation_request_id` value.\n\nHowever some generations may take more time than can be accommodated in the initial call. In these cases the result of\nthis call is `HTTP 202 Accepted` and the payload will only contain a `generation_request_id` value. This value must be\nretained by the client for subsequent polling of the `GET v3/ai/image-generations/{generationRequestId}` Get Images Generation endpoint.\n\n## Lifetime of Generated Images\n\nGenerated images will be retained for 6 months after generation.\n"
requestBody:
description: Request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/BackgroundRemovalRequest'
text/json:
schema:
$ref: '#/components/schemas/BackgroundRemovalRequest'
application/*+json:
schema:
$ref: '#/components/schemas/BackgroundRemovalRequest'
responses:
'200':
description: Returns the result of a request to extend an image
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationsResponse'
'202':
description: Returns the request ID for a pending request to extend an image
content:
application/json:
schema:
$ref: '#/components/schemas/PendingImageGenerationResponse'
'400':
description: The request was invalid
'403':
description: Product quota exceeded
'404':
description: Image not found
'410':
description: GenerationRequestGone
'429':
description: TooManyConcurrentGenerations
/v3/ai/image-generations/object-removal:
post:
tags:
- Generations
summary: Remove object(s)
description: "# AI Generator - Object Removal\n\nUse 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.\n\nWhen 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.\n\n## The Remove Object Request\n\nThe `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.\n\n| Parameter | Purpose |\n|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `reference_asset_id` | Creative image id to modify.
# --- truncated at 32 KB (83 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/getty-images/refs/heads/main/openapi/getty-images-generations-api-openapi.yml