Getty Images Generation API
The Generation API from Getty Images — 6 operation(s) for generation.
OpenAPI Specification
openapi: 3.0.1
info:
title: Getty Images Generation 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: Generation
paths:
/v3/ai/image-generations/{generationRequestId}:
get:
tags:
- Generation
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:
- Generation
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/generation-history:
get:
tags:
- Generation
summary: Retrieve history of AI generations
description: '# AI Generator - Generation History
Get the history of AI generation requests.'
parameters:
- name: date_start
in: query
description: "If included, limits the results to those generation requests made on or after date_start. Both dates and datetimes are supported. \r\nDates should be submitted in ISO 8601 format YYYY-MM-DD. The time will default to 00:00:00 UTC. \r\nDatetimes should be submitted in ISO 8601 format YYYY-MM-DDTHH:mm:ssZ."
style: form
schema:
type: string
format: date-time
- name: date_end
in: query
description: "If included, limits the results to those generation requests made on or before date_end. Both dates and datetimes are supported. \r\nDates should be submitted in ISO 8601 format YYYY-MM-DD. The time will default to 00:00:00 UTC. \r\nDatetimes should be submitted in ISO 8601 format YYYY-MM-DDTHH:mm:ssZ."
style: form
schema:
type: string
format: date-time
- name: media_type
in: query
description: If included, limits the results to those generation requests made for the given media type.
style: form
schema:
$ref: '#/components/schemas/MediaType'
- name: page_size
in: query
description: The page size of results. Default is 30.
style: form
schema:
maximum: 1000
minimum: 1
type: integer
format: int32
- name: page
in: query
description: The page number of results. Default is 1.
style: form
schema:
maximum: 2147483647
minimum: 1
type: integer
format: int32
- name: product_ids
in: query
description: If included, limits the results to only those requests made against the indicated products.
style: form
schema:
type: array
items:
type: integer
format: int32
- name: company_generations
in: query
description: "If `true`, returns the list of previously downloaded images for all users in\r\n your company. Your account must be enabled for this functionality. Contact your Getty Images account rep for\r\n more information. Default is `false`."
style: form
schema:
type: boolean
default: false
responses:
'200':
description: Returns the history of AI generations
content:
text/plain:
schema:
$ref: '#/components/schemas/GenerationHistoryResponse'
application/json:
schema:
$ref: '#/components/schemas/GenerationHistoryResponse'
text/json:
schema:
$ref: '#/components/schemas/GenerationHistoryResponse'
'403':
description: Company generations were requested but your account is not configured for access.
/v3/ai/generation-history/{generationRequestId}:
get:
tags:
- Generation
summary: Retrieve history item for an individual generation request
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 history item for the request
content:
text/plain:
schema:
$ref: '#/components/schemas/GenerationHistoryItemResponse'
application/json:
schema:
$ref: '#/components/schemas/GenerationHistoryItemResponse'
text/json:
schema:
$ref: '#/components/schemas/GenerationHistoryItemResponse'
'403':
description: NotAuthorized
'404':
description: The request ID was not found
/v3/ai/image-generations/{generationRequestId}/images/{index}/download-sizes:
get:
tags:
- Generation
summary: Get download sizes for a generated image
description: '# AI Generator - Get Download Sizes
Given a fulfilled generation request `id` and the `index` of a generated image, gets a list of download sizes for the image.
'
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
responses:
'200':
description: Returns the result of a request
content:
application/json:
schema:
$ref: '#/components/schemas/DownloadSizesResponse'
'400':
description: InvalidProduct
'404':
description: Either the generation id does not exist, the index is incorrect, or the generation is still pending
'410':
description: GenerationRequestGone
/v3/ai/image-generations/{generationRequestId}/images/{index}/download:
put:
tags:
- Generation
summary: Begin the download process
description: '# AI Generator - Download Image
Download a generated image. Initiating the download process for a 4K file may incur a cost depending on the terms of your agreement.
## Download Image Request body details
The `ImageDownloadRequest` payload to be posted contains the required `size` as well as some other optional
parameters:
| Parameter | Purpose |
|-------------------|----------------------------------------------------------------------------------------------|
| `size_name` _Required_ | Must be one of the valid download sizes retrieved through the "Get Download Sizes" endpoint |
| `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 a URL for the download.
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` with no payload. This client should then
poll `GET v3/ai/image-generations/{generationRequestId}/images/{index}/download` periodically to get the final
download.
'
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/ImageDownloadRequest'
text/json:
schema:
$ref: '#/components/schemas/ImageDownloadRequest'
application/*+json:
schema:
$ref: '#/components/schemas/ImageDownloadRequest'
responses:
'200':
description: Download request was successful and is complete
content:
text/plain:
schema:
$ref: '#/components/schemas/DownloadResponse'
application/json:
schema:
$ref: '#/components/schemas/DownloadResponse'
text/json:
schema:
$ref: '#/components/schemas/DownloadResponse'
'202':
description: Download request was successful put is pending
'400':
description: InvalidProduct
'403':
description: ProductQuotaExceeded
'404':
description: GenerationRequestIdNotFound
'409':
description: A download is already in progress for the given `generationRequestId` and `index`.
'410':
description: GenerationRequestGone
get:
tags:
- Generation
summary: "Once the download process has started, this endpoint can be used to check the status of the download and get the\r\ndownload URL once it is completed."
description: '# AI Generator - Get Download Image
Get the download for a generated image
## 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 a URL for the download.
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` with no payload. This client should then
poll `GET v3/ai/image-generations/{generationRequestId}/images/{index}/download` periodically to get the final
download.
Like the `PUT v3/ai/image-generations/{generationRequestId}/images/{index}/download` endpoint, the result of calling
this endpoint will be either:
- `HTTP 200 OK` with the download URL
- `HTTP 202 Accepted` with no payload
`HTTP 202 Accepted` is returned in the case where the download preparation 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.
'
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
responses:
'200':
description: Download request was successful and is complete
content:
text/plain:
schema:
$ref: '#/components/schemas/DownloadResponse'
application/json:
schema:
$ref: '#/components/schemas/DownloadResponse'
text/json:
schema:
$ref: '#/components/schemas/DownloadResponse'
'202':
description: Download request was successful put is pending
'400':
description: InvalidProduct
'404':
description: GenerationRequestIdNotFound
'410':
description: GenerationRequestGone
components:
schemas:
ImageDataResponse:
type: object
properties:
index:
type: integer
format: int32
is_blocked:
type: boolean
preview_urls:
type: array
items:
$ref: '#/components/schemas/PreviewUrl'
description: The preview URLs for the result
nullable: true
url:
type: string
nullable: true
additionalProperties: false
PendingImageGenerationResponse:
type: object
properties:
generation_request_id:
type: string
nullable: true
additionalProperties: false
DownloadResponse:
type: object
properties:
url:
type: string
nullable: true
generated_asset_id:
type: string
nullable: true
additionalProperties: false
Mood:
enum:
- black_and_white
- warm
- cool
- natural
- vivid
- dramatic
- bold
type: string
GenerationHistoryItemResponse:
type: object
properties:
generation_request_id:
type: string
description: The identifier for the request
nullable: true
seed:
type: integer
description: The seed used for the generation
format: int32
nullable: true
generation_date:
type: string
description: ''
format: date-time
product_revoked_date:
type: string
description: If the the product against which the generation was made has been revoked, this is the date of that revocation.
format: date-time
nullable: true
prompt:
type: string
description: The prompt that was used for the request
nullable: true
negative_prompt:
type: string
description: The negative prompt (if any) that was used for the request
nullable: true
product_id:
type: integer
description: ''
format: int32
notes:
type: string
description: ''
nullable: true
project_code:
type: string
description: ''
nullable: true
generation_type:
$ref: '#/components/schemas/GenerationType'
generation_options:
$ref: '#/components/schemas/GenerationOptions'
source_generation_request:
$ref: '#/components/schemas/SourceGenerationRequest'
original_asset:
$ref: '#/components/schemas/AssetDetail'
results:
type: array
items:
$ref: '#/components/schemas/GenerationHistoryResult'
description: ''
nullable: true
user:
$ref: '#/components/schemas/User'
additionalProperties: false
description: Detail on a specific historical generation
ImageDownloadRequest:
type: object
properties:
notes:
type: string
description: The notes to use for the download request. Some products require this value.
nullable: true
project_code:
type: string
description: The project code to use for the download request. Some products require this value.
nullable: true
size_name:
type: string
description: The size name. Valid values are 1k or 4k.
nullable: true
additionalProperties: false
description: Parameters for requesting an AI generation image download
DownloadSizeResponse:
type: object
properties:
size_name:
type: string
nullable: true
height:
type: integer
format: int32
width:
type: integer
format: int32
additionalProperties: false
AssetDetail:
type: object
properties:
id:
type: string
nullable: true
additionalProperties: false
DownloadSizesResponse:
type: object
properties:
download_sizes:
type: array
items:
$ref: '#/components/schemas/DownloadSizeResponse'
nullable: true
additionalProperties: false
MediaType:
enum:
- photography
- illustration
type: string
GenerationType:
enum:
- text_to_image
- variation
- extend
- refine
- background_removal
- influence_color_by_image
- influence_composition_by_image
- object_removal
- influence_outline_by_image
- background_generation
type: string
ImageGenerationsResponse:
type: object
properties:
generation_request_id:
type: string
nullable: true
seed:
type: integer
format: int32
nullable: true
results:
type: array
items:
$ref: '#/components/schemas/ImageDataResponse'
nullable: true
original_asset:
$ref: '#/components/schemas/AssetDetail'
additionalProperties: false
GenerationOptions:
type: object
properties:
media_type:
$ref: '#/components/schemas/MediaType'
aspect_ratio:
type: string
nullable: true
mood:
$ref: '#/components/schemas/Mood'
additionalProperties: false
User:
type: object
properties:
username:
type: string
nullable: true
first_name:
type: string
nullable: true
middle_name:
type: string
nullable: true
last_name:
type: string
nullable: true
additionalProperties: false
SourceGenerationRequest:
type: object
properties:
source_generation_request_id:
type: string
nullable: true
source_generation_result_index:
type: integer
format: int32
additionalProperties: false
GenerationHistoryResult:
type: object
properties:
index:
type: integer
description: The index of the result from the original generation
format: int32
is_blocked:
type: boolean
description: If `true` the result was blocked due to AI generation policy
preview_urls:
type: array
items:
$ref: '#/components/schemas/PreviewUrl'
description: The preview URLs for the result
nullable: true
additionalProperties: false
description: Individual generated result from a given generation request/response
ImageVariationRequest:
type: object
properties:
product_id:
type: integer
description: If you have multiple Getty products, indicate which one you would like to use for this generation request
format: int32
nullable: true
project_code:
type: string
description: The project code to use for the generation request. Some products require this value.
nullable: true
notes:
type: string
description: The notes to use for the generation request. Some products require this value.
nullable: true
additionalProperties: false
description: Payload with all images variation parameters
PreviewUrl:
type: object
properties:
preview_size:
type: string
nullable: true
image_url:
type: string
nullable: true
width:
type: integer
format: int32
height:
type: integer
format: int32
additionalProperties: false
GenerationHistoryResponse:
type: object
properties:
generations:
type: array
items:
$ref: '#/components/schemas/GenerationHistoryItemResponse'
description: Current page of generations
nullable: true
result_count:
type: integer
description: The total count of results, ignoring paging
format: int32
additionalProperties: false
description: Full generation history response
securitySchemes:
Api-Key:
type: apiKey
name: Api-Key
in: header
OAuth2:
type: oauth2
flows:
password:
tokenUrl: https://api.gettyimages.com/v4/oauth2/token
refreshUrl: https://api.gettyimages.com/v4/oauth2/token
scopes: {}
clientCredentials:
tokenUrl: https://api.gettyimages.com/v4/oauth2/token
scopes: {}
authorizationCode:
authorizationUrl: https://api.gettyimages.com/v4/oauth2/auth
tokenUrl: https://api.gettyimages.com/v4/oauth2/token
refreshUrl: https://api.gettyimages.com/v4/oauth2/token
scopes: {}