Getty Images Images API
The Images API from Getty Images — 15 operation(s) for images.
OpenAPI Specification
openapi: 3.0.1
info:
title: Getty Images 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: Images
paths:
/v3/affiliates/search/images:
get:
tags:
- Images
summary: ''
parameters:
- name: Accept-Language
in: header
description: 'Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th (iStock only), tr, uk (iStock only), vi (iStock only), zh-HK (creative assets only).'
schema:
type: string
description: 'Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th (iStock only), tr, uk (iStock only), vi (iStock only), zh-HK (creative assets only).'
- name: GI-Country-Code
in: header
description: Receive regionally relevant search results based on the value specified. Accepts only ISO Alpha-3 country codes. The Countries operation can be used to retrieve the codes.
schema:
type: string
description: Use of this parameter requires configuration changes to your API key. Please contact your sales representative to learn more.
- name: phrase
in: query
description: Search images using a search phrase.
schema:
type: string
description: Search images using a search phrase.
nullable: true
- name: style
in: query
description: Filter based on graphical style of the image.
schema:
$ref: '#/components/schemas/AffiliateSearchStyle'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/AffiliateImageSearchResponse'
/v3/ai/image-generations/{generationRequestId}/images/{index}/variations:
post:
tags:
- Images
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/{generationRequestId}/images/{index}/download-sizes:
get:
tags:
- Images
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:
- Images
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:
- Images
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
/v3/artists/images:
get:
tags:
- Images
summary: Search for images by a photographer
parameters:
- name: Accept-Language
in: header
description: 'Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th (iStock only), tr, uk (iStock only), vi (iStock only), zh-HK (creative assets only).'
schema:
type: string
description: 'Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th (iStock only), tr, uk (iStock only), vi (iStock only), zh-HK (creative assets only).'
- name: artist_name
in: query
description: Name of artist for desired images
schema:
type: string
description: Name of artist for desired images
nullable: true
- name: fields
in: query
description: Comma separated list of fields. Allows restricting which fields are returned. If no fields are selected, the summary_set of fields are returned.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ArtistsImageSearchFieldValues'
description: Comma separated list of fields. Allows restricting which fields are returned. If no fields are selected, the summary_set of fields are returned.
nullable: true
- name: page
in: query
description: Identifies page to return. Default page is 1.
schema:
type: integer
description: Identifies page to return. Default page is 1.
format: int32
default: 1
- name: page_size
in: query
description: Specifies page size. Default page_size is 10, maximum page_size is 100.
schema:
type: integer
description: Specifies page size. Default page_size is 10, maximum page_size is 100.
format: int32
default: 10
responses:
'200':
description: OK
'400':
description: InvalidParameterValue
'401':
description: Unauthorized
/v3/downloads/images/{id}:
post:
tags:
- Images
summary: Download an image
description: "Use this endpoint to generate download URLs and related data for images you are authorized to download.\n\nMost product offerings have enforced periodic download limits such as monthly, weekly, and daily. When this operation executes, the count of allowed downloads is decremented by one for the product offering. Once the download limit is reached for a given product offering, no further downloads may be requested for that product offering until the next download period.\n\nThe download limit for a given download period is covered in your product agreement established with Getty Images.\n\nYou'll need an API key and a [Resource Owner Grant or Implicit Grant](http://developers.gettyimages.com/en/authorization-faq.html) access token to use this resource.\n\n## Auto Downloads\nThe `auto_download` request query parameter specifies whether to automatically download the image.\n\nIf the `auto_download` request query parameter is set to _true_, the API will return an HTTP status code 303 *See Other*.Your client code will need to process this response and redirect to the URI specified in the *Location* header to enable you to automatically download the file. The redirection workflow follows the [HTTP 1.1 protocol](https://tools.ietf.org/html/rfc7231#section-6.4.4).\n\nClient Request:\n\n```\nhttps://api.gettyimages.com/v3/downloads/images/[asset_id]?auto_download=true\n```\n\nServer Response:\n\nYour client code should follow redirect (3xx) status codes returned from the URI in the response Location header. More information here: [HTTP 1.1 protocol](https://tools.ietf.org/html/rfc7231#section-6.4).\n\n```\nHTTP/1.1 303 See Other\nLocation: https://delivery.gettyimages.com/...\n```\n\nIf the `auto_download` request query parameter is set to false, the API will return a HTTP status code 200, along with the URI in the response body which can be used to download the image. \n\nClient Request:\n\n```\nhttps://api.gettyimages.com/v3/downloads/images/[asset_id]?auto_download=false\n```\n\nServer Response:\n\n```\nHTTP/1.1 200 OK\n{\n\t\"uri\": \"https://delivery.gettyimages.com/...\"\n}\n```\n## Downloading Via the Returned URI\n\nYour client code should follow redirect (3xx) status codes returned from the URI in the response. More information here: [HTTP 1.1 protocol](https://tools.ietf.org/html/rfc7231#section-6.4).\n\nThe URI returned by this call should be considered opaque and the format could change at any time.\nIn order to get the filename, length or file type, the response headers must be inspected. An example\nresponse follows:\n\n```\ncontent-length: 33959979\ncontent-type: image/jpeg\ncontent-disposition: attachment; filename=GettyImages-1167612765.jpg\n```\n\nThe `content-disposition` header must be parsed to get a usable filename.\n\n## Download URI expiration\n\nDownload URIs are _**only valid for 24 hours**_, starting from the moment they are returned from this call.\n"
parameters:
- name: Accept-Language
in: header
description: 'Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th (iStock only), tr, uk (iStock only), vi (iStock only), zh-HK (creative assets only).'
schema:
type: string
description: 'Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th (iStock only), tr, uk (iStock only), vi (iStock only), zh-HK (creative assets only).'
- name: id
in: path
description: "<remarks>\r\n Id of image to download.\r\n </remarks>"
required: true
schema:
type: string
description: "<remarks>\r\n Id of image to download.\r\n </remarks>"
nullable: true
- name: auto_download
in: query
description: "<remarks>\r\n Specifies whether to auto-download the image. If true is specified, a 303 SeeOther status is returned with a\r\n Location header set to the location of the image.\r\n If false is specified, the download URI will be returned in the response message. Default is true.\r\n </remarks>"
schema:
type: boolean
description: "<remarks>\r\n Specifies whether to auto-download the image. If true is specified, a 303 SeeOther status is returned with a\r\n Location header set to the location of the image.\r\n If false is specified, the download URI will be returned in the response message. Default is true.\r\n </remarks>"
default: true
- name: file_type
in: query
description: "<remarks>\r\n File Type expressed with three character file extension.\r\n </remarks>"
schema:
$ref: '#/components/schemas/DownloadFileType'
- name: height
in: query
description: "<remarks>\r\n Specifies the pixel height of the particular image to download.\r\n Available heights can be found in the images/{ids} response for the specific image.\r\n If left blank, it will return the largest available size.\r\n </remarks>"
schema:
type: string
description: "<remarks>\r\n Specifies the pixel height of the particular image to download.\r\n Available heights can be found in the images/{ids} response for the specific image.\r\n If left blank, it will return the largest available size.\r\n </remarks>"
nullable: true
- name: product_id
in: query
description: "<remarks>\r\n Identifier of the instance for the selected product offering type.\r\n </remarks>"
schema:
type: integer
description: "<remarks>\r\n Identifier of the instance for the selected product offering type.\r\n </remarks>"
format: int32
nullable: true
- name: product_type
in: query
description: "<remarks>\r\n Product types easyaccess, editorialsubscription, imagepack, and premiumaccess are for GettyImages API keys. Product types royaltyfreesubscription and creditpack are for iStock API keys. Default product type for iStock API keys is creditpack.\r\n </remarks>"
schema:
$ref: '#/components/schemas/ProductTypeForDownloads'
- name: use_team_credits
in: query
description: Specifies whether to download the image with iStock Team Credits. Only applicable to iStock API keys authenticated with a user that has Team Credits. Blank is the same as False.
schema:
type: boolean
description: Specifies whether to download the image with iStock Team Credits. Only applicable to iStock API keys authenticated with a user that has Team Credits. Blank is the same as False.
default: false
nullable: true
requestBody:
description: "<remarks>\r\n Additional information required from specific customers when downloading. \r\n Only users who have been set up with a project code by Getty Images Sales need to use this field.\r\n </remarks>"
content:
application/json:
schema:
$ref: '#/components/schemas/PremiumAccessDownloadData'
responses:
'200':
description: OK
'303':
description: See Other
'400':
description: MissingRequiredQueryParameters
'401':
description: AuthorizationTokenRequired
'403':
description: OverageLimitReached
'404':
description: ImageNotFound
/v3/images:
get:
tags:
- Images
summary: Get metadata for multiple images by supplying multiple image ids
description: "This endpoint returns the detailed image metadata for all specified images.\n\nYou'll need an API key and access token to use this resource.\n\n## Working with Fields Sets\n\nFields sets are used in the **fields** request parameter to receive a suite of metadata fields. The following fields sets are available:\n\n#### Summary Fields Set\n\nThe **summary_set** query string parameter fields value represents a small batch of metadata fields that are often used to build \nsearch response results. The following fields are provided for every image in your result set when you include **summary_set** in your request.\n\n```\n{\n \"images\":\n [\n \"artist\",\n \"asset_family\",\n \"caption\",\n \"collection_code\",\n \"collection_id\",\n \"collection_name\",\n \"license_model\",\n \"max_dimensions\",\n \"title\"\n ]\n}\n```\n\n#### Detail Fields Set\n\nThe **detail_set** query string parameter fields value represents a large batch of metadata fields that are often used to build a \ndetailed view of images. The following fields are provided for every image in your result set when you include **detail_set** in your request.\n\n```\n{\n \"images\":\n [\n \"allowed_use\",\n \"artist\", \n \"artist_title\", \n \"asset_family\",\n \"call_for_image\",\n \"caption\", \n \"city\",\n \"collection_code\",\n \"collection_id\", \n \"collection_name\",\n \"color_type\", \n \"copyright\", \n \"country\", \n \"credit_line\", \n \"date_created\", \n \"date_submitted\",\n \"download_sizes\", \n \"editorial_segments\",\n \"event_ids\",\n \"graphical_style\",\n \"license_model\",\n \"max_dimensions\",\n \"orientation\",\n \"product_types\",\n \"quality_rank\",\n \"referral_destinations\",\n \"state_province\", \n \"title\"\n ]\n}\n```\n\n#### Display Fields Set\n\nThe **display_set** query string parameter fields value represents the fields that provide you with URLs for the low resolution\nfiles that are most frequently used to build a UI displaying search results. The following fields are provided for every image \nin your result set when you include **display_set** in your request.\n\nThe URI provided is subject to change at any time and must be used as-is with no modification.\n\n```\n{\n \"images\":\n [\n \"display_sizes\": \n [\n {\n \"is_watermarked\": <boolean>,\n \"name\": \"comp\",\n \"uri\": \"<link>\"\n },\n {\n \"is_watermarked\": <boolean>,\n \"name\": \"preview\",\n \"uri\": \"<link>\"\n },\n {\n \"is_watermarked\": <boolean>,\n \"name\": \"thumb\",\n \"uri\": \"<link>\"\n }\n ]\n ]\n}\n```\n\n## Request Usage Considerations\n\n- Specifying the \"entity_details\" response field can have significant performance implications. The field should be used only when necessary.\n"
parameters:
- name: Accept-Language
in: header
description: 'Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th (iStock only), tr, uk (iStock only), vi (iStock only), zh-HK (creative assets only).'
schema:
type: string
description: 'Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th (iStock only), tr, uk (iStock only), vi (iStock only), zh-HK (creative assets only).'
- name: ids
in: query
description: Specifies one or more image ids to return. Use comma delimiter when requesting multiple ids. Maximum of 100 ids.
style: form
explode: false
schema:
type: array
items:
type: string
description: Specifies one or more image ids to return. Use comma delimiter when requesting multiple ids. Maximum of 100 ids.
nullable: true
- name: fields
in: query
description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes, height, and width returned by ''download_sizes'' field are estimates.'
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ImageDetailFieldValues'
description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes, height, and width returned by ''download_sizes'' field are estimates.'
nullable: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ImagesDetailResults'
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
'404':
description: ImageNotFound
'500':
description: InvalidIStockCollection
/v3/images/{id}:
get:
tags:
- Images
summary: Get metadata for a single image by supplying one image id
description: "This endpoint returns the detailed image metadata for a specified image.\n\nYou'll need an API key and access token to use this resource. \n \n## Working with Fields Sets\n\nFields sets are used in the **fields** request parameter to receive a suite of metadata fields. The following fields sets are available:\n\n#### Summary Fields Set\n\nThe **summary_set** query string parameter fields value represents a small batch of metadata fields that\nare often used to build search response results. The following fields are provided for every image in your\nresult set when you include **summary_set** in your request.\n\n```\n{\n \"images\":\n [\n \"artist\",\n \"asset_family\",\n \"caption\",\n \"collection_code\",\n \"collection_id\
# --- truncated at 32 KB (142 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/getty-images/refs/heads/main/openapi/getty-images-images-api-openapi.yml