Gettyimagesconnector v1.0 | OneTeg Documentation

/v3/affiliates/search/images

Search for images using affiliate search parameters.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Gi-country-code`	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.
`Phrase`	Search images using a search phrase.
`Style`	Filter based on graphical style of the image.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/affiliates/search/videos

Search for videos using affiliate search.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Gi-country-code`	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.
`Phrase`	Provide a search phrase to filter video results.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/ai/image-generations/{generationRequestId}/images/{index}/download

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 either `4k` or `1k`
`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.

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 beta/ai/image-generations/{generationRequestId}/images/{index}/download periodically to get the final
download.

Parameters

Parameter Name	Description
`Content Type`	The content type of the request payload sent to the API (e.g. application/json).
`headers`	Additional HTTP header name/value pairs to include in the request.
`Generationrequestid`	The ID from a previous request to generate images
`Index`	The index of the image from the specific images generation
`Response Type`	The response format expected from the API (e.g. application/json).

Options (3)

Option Name	Description
`Notes`	The notes to use for the download request. Some products require this value.
`Project Code`	The project code to use for the download request. Some products require this value.
`Size Name`	The size name. Valid values are 1k or 4k.

/v3/ai/image-generations/extend

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 Image Extend Request

The ImageExtendRequest payload 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
`id`	Required. The creative image id to extend.
`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 extension 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.
`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 beta/ai/image-generations/{generationRequestId} Get Images Generation endpoint.

Lifetime of Generated Images

Generated images will be retained for 6 months after generation.

Parameters

Parameter Name	Description
`Content Type`	The content type of the request payload sent to the API (e.g. application/json).
`headers`	Additional HTTP header name/value pairs to include in the request.
`Response Type`	The response format expected from the API (e.g. application/json).

Options (10)

Option Name	Description
`Id`	The image id to extend. This value is required.
`Prompt`	This is the primary text used for the extension of the image.
`Negative Prompt`	Concepts to exclude from the result
`Product Id`	If you have multiple Getty products, indicate which one you would like to use for this extend request
`Project Code`	The project code to use for the request. Some products require this value.
`Notes`	The notes to use for the request. Some products require this value.
`Left Percentage`	The percentage to add to the left side of the image.
`Right Percentage`	The percentage to add to the right side of the image.
`Top Percentage`	The percentage to add to the top of the image.
`Bottom Percentage`	The percentage to add to the bottom of the image.

/beta/ai/image-generations/{generationRequestId}/images/{index}/extend

AI Generator - Image Extension

Use text prompts and numerical values to extend the content beyond the borders of a previously generated 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.

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 Image Extend Request

The ImageExtendRequest payload 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
`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 extension 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.
`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 beta/ai/image-generations/{generationRequestId} Get Images Generation endpoint.

Lifetime of Generated Images

Generated images will be retained for 6 months after generation.

Parameters

Parameter Name	Description
`Content Type`	The content type of the request payload sent to the API (e.g. application/json).
`headers`	Additional HTTP header name/value pairs to include in the request.
`Generationrequestid`	The ID from a previous request to generate images
`Index`	The index of the image from the specific images generation
`Response Type`	The response format expected from the API (e.g. application/json).

Options (9)

Option Name	Description
`Prompt`	This is the primary text used for the extension of the image.
`Negative Prompt`	Concepts to exclude from the result
`Product Id`	If you have multiple Getty products, indicate which one you would like to use for this extend request
`Project Code`	The project code to use for the request. Some products require this value.
`Notes`	The notes to use for the request. Some products require this value.
`Left Percentage`	The percentage to add to the left side of the image.
`Right Percentage`	The percentage to add to the right side of the image.
`Top Percentage`	The percentage to add to the top of the image.
`Bottom Percentage`	The percentage to add to the bottom of the image.

/v3/ai/image-generations

AI Generator - Generate Images

Use a text prompt to generate images. Use of this endpoint is restricted to clients with an AI Generation license
product.

The Image Generations Request

The ImageGenerationsRequest payload to be posted contains the required prompt as well as some other optional
parameters:

Parameter	Purpose
`prompt` _Required_	The primary text used for the generation of the images.
`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_.
`negative_prompt`	Concepts to _exclude_ from the result
`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`
`media_type`	Media type of the results: `photography` or `illustration`
`mood`	Can be `black_and_white`, `warm`, `cool`, `natural`, `vivid`, `dramatic`, or `bold`

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.

Parameters

Parameter Name	Description
`Content Type`	The content type of the request payload sent to the API (e.g. application/json).
`headers`	Additional HTTP header name/value pairs to include in the request.
`Response Type`	The response format expected from the API (e.g. application/json).

Options (9)

Option Name	Description
`Prompt`	The only required parameter, this is the primary text used for the generation of the images.
`Seed`	The seed to use for generation. This is not used for most generation cases but is available for use to ensure a repeatable result.
`Negative Prompt`	Concepts to exclude from the result
`Aspect Ratio`	Aspect ratio of the result images. Must be one of 1:1, 3:4, 4:3, 9:16, or 16:9
`Media Type`	Specify the media type for the generated image (e.g., 'photography', 'illustration').
`Mood`	Set the desired mood for the image generation (e.g., 'happy', 'serious').
`Product Id`	If you have multiple Getty products, indicate which one you would like to use for this generation request
`Project Code`	The project code to use for the generation request. Some products require this value.
`Notes`	The notes to use for the generation request. Some products require this value.

/v3/ai/image-generations/{generationRequestId}/images/{index}/download-sizes

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

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Generationrequestid`	The ID from a previous request to generate images
`Index`	The index of the image from the specific images generation
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/ai/image-generations/{generationRequestId}

AI Generator - Get Generated Images

Gets a previously generated set of images. This endpoint is used after a call to POST beta/ai/image-generations, passing the id value from the result of that call.

Fulfilled and Pending Results

Like the POST beta/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

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Generationrequestid`	The ID from a previous request to generate images
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/ai/image-generations/{generationRequestId}/images/{index}/variations

AI Generator - Generate Variations

Generate image variations from a previously-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 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.

Parameters

Parameter Name	Description
`Content Type`	The content type of the request payload sent to the API (e.g. application/json).
`headers`	Additional HTTP header name/value pairs to include in the request.
`Generationrequestid`	The ID from a previous request to generate images
`Index`	The index of the image from the specific images generation
`Response Type`	The response format expected from the API (e.g. application/json).

Options (3)

Option Name	Description
`Product Id`	If you have multiple Getty products, indicate which one you would like to use for this generation request
`Project Code`	The project code to use for the generation request. Some products require this value.
`Notes`	The notes to use for the generation request. Some products require this value.

/v3/ai/image-generations/{generationRequestId}/images/{index}/download

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 beta/ai/image-generations/{generationRequestId}/images/{index}/download periodically to get the final
download.

Like the PUT beta/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

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Generationrequestid`	The ID from a previous request to generate images
`Index`	The index of the image from the specific images generation
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/ai/redownloads

Re-download AI Generated media

Re-download previously downloaded AI generated media.

`ReDownloadRequest` details

Parameter	Purpose
`generated_asset_id` _Required_	The generated asset identifier to re-download. Can be retrieved from previously downloaded assets (`GET /v3/downloads`)
`product_id` _Required_	The product to use to re-download. Can be retrieved from products (`GET /v3/products`)
`size_name` _Required_	The size to re-download. Valid values are `1k` and `4k`
`project_code`	The project code to use for the download. Some products require a value for this. The products endpoint (`GET /v3/products`) provides this information.
`notes`	The notes to use for the download. Some products require a value for this. The products endpoint (`GET /v3/products`) provides this information.

Parameters

Parameter Name	Description
`Content Type`	The content type of the request payload sent to the API (e.g. application/json).
`headers`	Additional HTTP header name/value pairs to include in the request.
`Response Type`	The response format expected from the API (e.g. application/json).

Options (5)

Option Name	Description
`Generated Asset Id`	The identifier of the previously-downloaded generated asset.
`Product Id`	The product ID to use for the download.
`Size Name`	The size name. Valid values are 1k or 4k.
`Project Code`	The project code to use for the download request. Some products require this value.
`Notes`	The notes to use for the download request. Some products require this value.

/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.

Parameters

Parameter Name	Description
`Content Type`	The content type of the request payload sent to the API (e.g. application/json).
`headers`	Additional HTTP header name/value pairs to include in the request.
`Response Type`	The response format expected from the API (e.g. application/json).

Options (7)

Option Name	Description
`Id`	The image id to refine. This value is required.
`Prompt`	This is the primary text used for refining the images.
`Negative Prompt`	Concepts to exclude from the result
`Product Id`	If you have multiple Getty products, indicate which one you would like to use for this refine request
`Project Code`	The project code to use for the request. Some products require this value.
`Notes`	The notes to use for the request. Some products require this value.
`Mask Url`	The location of the mask. This value is required.

/beta/ai/image-generations/{generationRequestId}/images/{index}/refine

AI Generator - Image Refining

Use a mask image and text prompts to modify content in a previously generated 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.

The Image Refine Request

The ImageRefineRequest payload requires a valid mask_url and accepts the following optional
parameters:

Parameter	Purpose
`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.

Parameters

Parameter Name	Description
`Content Type`	The content type of the request payload sent to the API (e.g. application/json).
`headers`	Additional HTTP header name/value pairs to include in the request.
`Generationrequestid`	The ID from a previous request to generate images
`Index`	The index of the image from the specific images generation
`Response Type`	The response format expected from the API (e.g. application/json).

Options (6)

Option Name	Description
`Prompt`	This is the primary text used for refining the images.
`Negative Prompt`	Concepts to exclude from the result
`Product Id`	If you have multiple Getty products, indicate which one you would like to use for this refine request
`Project Code`	The project code to use for the request. Some products require this value.
`Notes`	The notes to use for the request. Some products require this value.
`Mask Url`	The location of the mask.

/beta/ai/generation-history/{generationRequestId}

Retrieve the history details for a specific AI image generation request.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Generationrequestid`	The ID from a previous request to generate images
`Response Type`	The response format expected from the API (e.g. application/json).

/beta/ai/generation-history

AI Generator - Generation History

Get the history of AI generation requests.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Date Start`	If included, limits the results to those generation requests made on or after date_start. Both dates and datetimes are supported. Dates should be submitted in ISO 8601 format YYYY-MM-DD. The time will default to 00:00:00 UTC. Datetimes should be submitted in ISO 8601 format YYYY-MM-DDTHH:mm:ssZ.
`Date End`	If included, limits the results to those generation requests made on or before date_end. Both dates and datetimes are supported. Dates should be submitted in ISO 8601 format YYYY-MM-DD. The time will default to 00:00:00 UTC. Datetimes should be submitted in ISO 8601 format YYYY-MM-DDTHH:mm:ssZ.
`Media Type`	If included, limits the results to those generation requests made for the given media type.
`Page Size`	The page size of results. Default is 30.
`Page`	The page number of results. Default is 1.
`Product Ids`	If included, limits the results to only those requests made against the indicated products.
`Company Generations`	If true, returns the list of previously downloaded images for all users in your company. Your account must be enabled for this functionality. Contact your Getty Images account rep for more information. Default is false.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/artists/images

Search for images associated with a specific photographer.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Artist Name`	Name of artist for desired images
`Fields`	Comma separated list of fields. Allows restricting which fields are returned. If no fields are selected, the summary_set of fields are returned.
`Page`	Identifies page to return. Default page is 1.
`Page Size`	Specifies page size. Default page_size is 10, maximum page_size is 100.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/artists/videos

Search for videos associated with a specific photographer.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Artist Name`	Name of artist for desired images
`Fields`	Comma separated list of fields. Allows restricting which fields are returned. If no fields are selected, the summary_set of fields are returned.
`Page`	Identifies page to return. Default page is 1.
`Page Size`	Specifies page size. Default page_size is 10, maximum page_size is 100.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/asset-changes/change-sets/{change-set-id}

Delete Asset Changes

Confirm asset changes acknowledges receipt of asset changes (from the PUT asset-changes endpoint).

Quickstart

You'll need an API key and an access token to use this resource.

Use the change_set_id from the PUT asset-changes/change-sets endpoint to confirm receipt of notifications.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Change-set-id`	Specify the change-set-id associated with a transaction resource whose receipt you want to confirm.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/asset-changes/channels

Get Partner Channels

Retrieves the channel data for the partner. This data can be used to populate the channel_id parameter in the Put Asset Changes query.

Quickstart

You'll need an API key and an access token to use this resource.

Partners who have a channel that has been removed should contact their sales representative to be set up again.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/asset-changes/change-sets

Asset Changes

Get notifications about new, updated or deleted assets for a specific channel.

Quickstart

You'll need an API key and an access token to use this resource.

Maximum batch size is 2200.

Change-sets must be confirmed before a new batch of notifications can be retrieved from this endpoint. Use the DELETE asset-changes/change-sets/{change-set-id} endpoint to confirm reciept of these notifications.

Values returned for asset_type include Image, Film, and null. Values returned for asset_lifecycle include New, Update, and Delete.

Delete notifications may be provided for asset ids that have not previously been received as New or Update notifications. Delete notifications may return null for the asset_type.

If there are no notifications in the channel an empty response body will be returned.

Notifications older than 60 days will be removed from partner channels.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Channel Id`	Specifies the id of the channel for the asset data. Valid channel ids can be found in the results of the Get Partner Channel query.
`Batch Size`	Specifies the number of assets to return. The default is 2200; maximum is 2200.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/asset-licensing/{assetId}

Acquire extended licenses for an asset using iStock credits.

Parameters

Parameter Name	Description
`Content Type`	The content type of the request payload sent to the API (e.g. application/json).
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Assetid`	Getty Images assetId - examples 520621493, 112301284
`Response Type`	The response format expected from the API (e.g. application/json).

Options (2)

Option Name	Description
`Extended Licenses`	Provide a list of extended license options to apply.
`Use Team Credits`	Defaults to false.

/v3/asset-management/assets/send-events

Send events related to asset management.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Last Offset`	Specifies a date/time (with timezone information) for continuing retrieval of events. Events occuring _after_ the last_offset value provided will be returned.
`Event Count`	Specifies the number of events to return. Default is 50, maximum value is 100.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/boards/{board_id}/comments

Add a comment to a specified board.

Parameters

Parameter Name	Description
`Content Type`	The content type of the request payload sent to the API (e.g. application/json).
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Board Id`	Specify the board to add a comment to.
`Response Type`	The response format expected from the API (e.g. application/json).

Options (1)

Option Name	Description
`Text`	Enter the text content of the comment.

/v3/boards/{board_id}/assets/{asset_id}

Add a single asset to a board using the asset ID in the path.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Board Id`	Specify the board to add an asset to.
`Asset Id`	Specify the asset to add to the board. If it is already in the board's asset collection, no action is taken.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/boards/{board_id}/assets

Add multiple assets to a board.

Parameters

Parameter Name	Description
`Content Type`	The content type of the request payload sent to the API (e.g. application/json).
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Board Id`	Specify the board to add assets to.
`Response Type`	The response format expected from the API (e.g. application/json).

Options (1)

Option Name	Description
`Asset Id`	Provide the asset ID to include in the board.

/v3/boards

Create a new board with a name and optional description.

Parameters

Parameter Name	Description
`Content Type`	The content type of the request payload sent to the API (e.g. application/json).
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Response Type`	The response format expected from the API (e.g. application/json).

Options (2)

Option Name	Description
`Name`	Set the name for the new board.
`Description`	Provide a description for the board.

/v3/boards/{board_id}

Permanently delete a board specified by its ID.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Board Id`	Specify the board to delete.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/boards/{board_id}/comments/{comment_id}

Delete a specific comment from a board.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Board Id`	Specify the board containing the comment to delete.
`Comment Id`	Specify the comment to delete.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/boards

Retrieve a list of all boards the current user participates in.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Page`	Request results starting at a page number (default is 1).
`Board Relationship`	Search for boards the user owns or has been invited to as an editor.
`Sort Order`	Sort the list of boards by last update date or name. Defaults to date_last_updated_descending.
`Pagesize`	Request number of boards to return in each page. (default is 30).
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/boards/{board_id}

Retrieve the assets and metadata for a specific board.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Board Id`	Retrieve details for a specific board.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/boards/{board_id}/comments

Retrieve all comments from a specified board.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Board Id`	Specify the board to retrieve comments from.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/boards/{board_id}/assets/{asset_id}

Remove a single asset from a board using the asset ID.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Board Id`	Specify the board to remove an asset from.
`Asset Id`	Specify the asset to remove from the board.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/boards/{board_id}/assets

Remove multiple assets from a board.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Board Id`	Specify the board to remove assets from.
`Asset Ids`	List the assets to be removed from the board.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/boards/{board_id}

Update the name and/or description of an existing board.

Parameters

Parameter Name	Description
`Content Type`	The content type of the request payload sent to the API (e.g. application/json).
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Board Id`	Specify the board to update.
`Response Type`	The response format expected from the API (e.g. application/json).

Options (2)

Option Name	Description
`Name`	Set the new name for the board.
`Description`	Set the new description for the board.

/v3/collections

Use this endpoint to retrieve collections associated with your Getty Images account. To browse available collections see our Image collections page.

You'll need an API key and access token to use this resource.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/countries

Returns a list of country objects that contains country name, two letter ISO abbreviation and three letter ISO abbreviation.

You'll need an API key and access token to use this resource.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/customers/current

Returns the first, middle and last name of the authenticated user.

You'll need an API key and access token to use this resource.

Please consult our Authorization FAQ for more information on authorization tokens.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/downloads/videos/{id}

Use this endpoint to generate download URLs and related data for videos you are authorized to download.

Most 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.

The download limit for a given download period is covered in your product agreement established with Getty Images.

You'll need an API key and a Resource Owner Grant or Implicit Grant access token to use this resource.

Auto Downloads

The auto_download request query parameter specifies whether to automatically download the video.

If 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.

Client Request:

C

https://api.gettyimages.com/v3/downloads/videos/[asset_id]?auto_download=true

Server Response:

Your client code should follow redirect (3xx) status codes returned from the URI in the response Location header. More information here: HTTP 1.1 protocol.

HTTP/1.1 303 See Other
Location: https://delivery.gettyimages.com/...

If 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 video.

Client Request:

C

https://api.gettyimages.com/v3/downloads/videos/[asset_id]?auto_download=false

Server Response:

HTTP/1.1 200 OK
{
	"uri": "https://delivery.gettyimages.com/..."
}

Downloading Via the Returned URI

Your client code should follow redirect (3xx) status codes returned from the URI in the response. More information here: HTTP 1.1 protocol.

The URI returned by this call should be considered opaque and the format could change at any time.
In order to get the filename, length or file type, the response headers must be inspected. An example
response follows:

C

content-length: 283925783
content-type: video/quicktime
content-disposition: attachment; filename=GettyImages-690773579.mov

The content-disposition header must be parsed to get a usable filename.

Download URI expiration

Download URIs are _only valid for 24 hours_, starting from the moment they are returned from this call.

Parameters

Parameter Name	Description
`Content Type`	The content type of the request payload sent to the API (e.g. application/json).
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Id`	Id of video to download.
`Auto Download`	Specifies whether to auto-download the video. If true is specified, a 303 SeeOther status is returned with a Location header set to the location of the video. If false is specified, the download URI will be returned in the response message. Default is false.
`Size`	Specifies the size to be downloaded.
`Product Id`	Identifier of the instance for the selected product offering type.
`Product Type`	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.
`Use Team Credits`	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.
`Response Type`	The response format expected from the API (e.g. application/json).

Options (2)

Option Name	Description
`Download Notes`	Add notes to accompany the download.
`Project Code`	Specify a project code for tracking the download.

/v3/downloads/images/{id}

Use this endpoint to generate download URLs and related data for images you are authorized to download.

Most 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.

The download limit for a given download period is covered in your product agreement established with Getty Images.

You'll need an API key and a Resource Owner Grant or Implicit Grant access token to use this resource.

Auto Downloads

The auto_download request query parameter specifies whether to automatically download the image.

If 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.

Client Request:

C

https://api.gettyimages.com/v3/downloads/images/[asset_id]?auto_download=true

Server Response:

Your client code should follow redirect (3xx) status codes returned from the URI in the response Location header. More information here: HTTP 1.1 protocol.

HTTP/1.1 303 See Other
Location: https://delivery.gettyimages.com/...

If 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.

Client Request:

C

https://api.gettyimages.com/v3/downloads/images/[asset_id]?auto_download=false

Server Response:

HTTP/1.1 200 OK
{
	"uri": "https://delivery.gettyimages.com/..."
}

Downloading Via the Returned URI

Your client code should follow redirect (3xx) status codes returned from the URI in the response. More information here: HTTP 1.1 protocol.

The URI returned by this call should be considered opaque and the format could change at any time.
In order to get the filename, length or file type, the response headers must be inspected. An example
response follows:

C

content-length: 33959979
content-type: image/jpeg
content-disposition: attachment; filename=GettyImages-1167612765.jpg

The content-disposition header must be parsed to get a usable filename.

Download URI expiration

Download URIs are _only valid for 24 hours_, starting from the moment they are returned from this call.

Parameters

Parameter Name	Description
`Content Type`	The content type of the request payload sent to the API (e.g. application/json).
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Id`	Id of image to download.
`Auto Download`	Specifies whether to auto-download the image. If true is specified, a 303 SeeOther status is returned with a Location header set to the location of the image. If false is specified, the download URI will be returned in the response message. Default is true.
`File Type`	File Type expressed with three character file extension.
`Height`	Specifies the pixel height of the particular image to download. C `Available heights can be found in the images/{ids} response for the specific image. If left blank, it will return the largest available size.`
`Product Id`	Identifier of the instance for the selected product offering type.
`Product Type`	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.
`Use Team Credits`	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.
`Response Type`	The response format expected from the API (e.g. application/json).

Options (2)

Option Name	Description
`Download Notes`	Add notes to accompany the download.
`Project Code`	Specify a project code for tracking the download.

/v3/downloads

Returns information about a customer's previously downloaded assets.

You'll need an API key and access token to use this resource.

This endpoint requires being a Getty Images customer to limit your results to only assets that you have a license to use,
you need to also include an authorization token in the header of your request.
Please consult our Authorization FAQ for more information on authorization tokens.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Date From`	If specified, selects assets downloaded on or after this date. Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD). Any hour, minute, second values in the request are not used, unless useTimePart parameter is included. Date/times in the response are UTC. Default is 30 days prior to date_to
`Date To`	If specified, selects assets downloaded on or before this date. Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD) Any hour, minute, second values in the request are not used, unless useTimePart parameter is included. Date/times in the response are UTC. Default is current date or 30 days after specified start date, whichever one is earlier.
`Use Time`	If specified, time values provided with date_to or date_from will be used. Time values should be appended to the date value in ISO 8601 format i.e.: 2019-09-19T19:30:37 or 2019-09-19 19:30:37. Time zone can be specified as optional. Default value is false
`Page`	Identifies page to return. Default is 1.
`Page Size`	Specifies page size. Default is 30, maximum page_size is 100.
`Product Type`	Specifies product type to be included in the previous download results. Product types easyaccess, editorialsubscription, imagepack, and premiumaccess are for GettyImages API keys. Product types royaltyfreesubscription and creditpack are for iStock API keys. To get previous iStockPhoto credit downloads, creditpack must be selected.
`Company Downloads`	If specified, returns the list of previously downloaded images for all users in your company. Your account must be enabled for this functionality. Contact your Getty Images account rep for more information. Default is false.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/events/{id}

This endpoint returns the detailed event metadata for a specified event. Getty Images news, sports and entertainment
photographers and videographers cover editorially relevant events occurring around the world.
All images or video clips produced in association with an event, are assigned the same EventID.
EventIDs are part of the meta-data returned in SearchForImages Results. Only content produced under a Getty Images
brand name (Getty Images News, Getty Images Sports, Getty Images Entertainment, Film Magic, Wire Image) will be
consistently assigned an EventID. The Event framework may also be used to group similar content, such as
"Hats from the Royal Wedding" or "Odd-ballOffbeat images of the week".

You'll need an API key and access token to use this resource.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Id`	An event id.
`Fields`	A comma separated list of fields to return in the response.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/events

This endpoint returns the detailed event metadata for all specified events. Getty Images news, sports and entertainment photographers and
videographers cover editorially relevant events occurring around the world. All images or video clips produced in association with
an event, are assigned the same EventID. EventIDs are part of the meta-data returned in SearchForImages Results. Only content
produced under a Getty Images brand name (Getty Images News, Getty Images Sports, Getty Images Entertainment, Film Magic, Wire Image)
will be consistently assigned an EventID. The Event framework may also be used to group similar content, such as
"Hats from the Royal Wedding" or "Odd-ballOffbeat images of the week".

You'll need an API key and access token to use this resource.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Ids`	A comma separated list of event ids.
`Fields`	A comma separated list of fields to return in the response.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/images/{id}

This endpoint returns the detailed image metadata for a specified image.

You'll need an API key and access token to use this resource.

Working with Fields Sets

Fields sets are used in the fields request parameter to receive a suite of metadata fields. The following fields sets are available:

Summary Fields Set

The summary_set query string parameter fields value represents a small batch of metadata fields that
are often used to build search response results. The following fields are provided for every image in your
result set when you include summary_set in your request.

JSON

{
    "images":
    [
        "artist",
        "asset_family",
        "caption",
        "collection_code",
        "collection_id",
        "collection_name",
        "license_model",
        "max_dimensions",
        "title"
    ]
}

Detail Fields Set

The detail_set query string parameter fields value represents a large batch of metadata fields that are
often used to build a detailed view of images. The following fields are provided for every image in your
result set when you include detail_set in your request.

JSON

{
    "images":
    [
        "allowed_use",
        "artist", 
        "artist_title", 
        "asset_family",
        "call_for_image",
        "caption", 
        "city",
        "collection_code",
        "collection_id", 
        "collection_name",
        "color_type", 
        "copyright", 
        "country", 
        "credit_line", 
        "date_created", 
        "date_submitted",
        "download_sizes", 
        "editorial_segments",
        "event_ids",
        "graphical_style",
        "license_model",
        "max_dimensions",
        "orientation",
        "product_types",
        "quality_rank",
        "referral_destinations",
        "state_province", 
        "title"
    ]
}

Display Fields Set

The display_set query string parameter fields value represents the fields that provide you with URLs for the low
resolution files that are most frequently used to build a UI displaying search results. The following fields are provided
for every image in your result set when you include display_set in your request.

The URI provided is subject to change at any time and must be used as-is with no modification.

JSON

{
    "images":
    [
        "display_sizes": 
        [
            {
                "is_watermarked": <boolean>,
                "name": "comp",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "preview",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "thumb",
                "uri": "<link>"
            }
        ]
    ]
}

Request Usage Considerations

Specifying the "entity_details" response field can have significant performance implications. The field should be used only when necessary.

"name": "string",
"uri": "string"

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Id`	An image id. For more than one image please use the /v3/images endpoint.
`Fields`	Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/images

This endpoint returns the detailed image metadata for all specified images.

You'll need an API key and access token to use this resource.

Working with Fields Sets

Fields sets are used in the fields request parameter to receive a suite of metadata fields. The following fields sets are available:

Summary Fields Set

The summary_set query string parameter fields value represents a small batch of metadata fields that are often used to build
search response results. The following fields are provided for every image in your result set when you include summary_set in your request.

JSON

{
    "images":
    [
        "artist",
        "asset_family",
        "caption",
        "collection_code",
        "collection_id",
        "collection_name",
        "license_model",
        "max_dimensions",
        "title"
    ]
}

Detail Fields Set

The detail_set query string parameter fields value represents a large batch of metadata fields that are often used to build a
detailed view of images. The following fields are provided for every image in your result set when you include detail_set in your request.

JSON

{
    "images":
    [
        "allowed_use",
        "artist", 
        "artist_title", 
        "asset_family",
        "call_for_image",
        "caption", 
        "city",
        "collection_code",
        "collection_id", 
        "collection_name",
        "color_type", 
        "copyright", 
        "country", 
        "credit_line", 
        "date_created", 
        "date_submitted",
        "download_sizes", 
        "editorial_segments",
        "event_ids",
        "graphical_style",
        "license_model",
        "max_dimensions",
        "orientation",
        "product_types",
        "quality_rank",
        "referral_destinations",
        "state_province", 
        "title"
    ]
}

Display Fields Set

The display_set query string parameter fields value represents the fields that provide you with URLs for the low resolution
files that are most frequently used to build a UI displaying search results. The following fields are provided for every image
in your result set when you include display_set in your request.

The URI provided is subject to change at any time and must be used as-is with no modification.

JSON

{
    "images":
    [
        "display_sizes": 
        [
            {
                "is_watermarked": <boolean>,
                "name": "comp",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "preview",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "thumb",
                "uri": "<link>"
            }
        ]
    ]
}

Request Usage Considerations

Specifying the "entity_details" response field can have significant performance implications. The field should be used only when necessary.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Ids`	Specifies one or more image ids to return. Use comma delimiter when requesting multiple ids. Maximum of 100 ids.
`Fields`	Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/images/{id}/same-series

This endpoint will provide the list of images, if any exist, from the same series as the specified creative asset id. These images are typically from the same photo shoot. This functionality will not work for editorial assets.

You'll need an API key and access token to use this resource.

Working with Fields Sets

Fields sets are used in the fields request parameter to receive a suite of metadata fields. The following fields sets are available:

Summary Fields Set

The summary_set query string parameter fields value represents a small batch of metadata fields that are often used to build
search response results. The following fields are provided for every image in your result set when you include summary_set in your request.

JSON

{
    "images":
    [
        "asset_family",
        "caption",
        "collection_code",
        "collection_id",
        "collection_name",
        "display_sizes": 
        [
            {
                "name": "thumb"
            }
        ]
        "license_model",
        "max_dimensions",
        "title"
    ]
}

Detail Fields Set

The detail_set query string parameter fields value represents a large batch of metadata fields that are often used to build a
detailed view of images. The following fields are provided for every image in your result set when you include detail_set in your request.

JSON

{
    "images":
    [
        "allowed_use",
        "artist",
        "asset_family",
        "call_for_image",
        "caption",
        "collection_code",
        "collection_id",
        "collection_name",
        "copyright",
        "date_created",
        "display_sizes": 
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ],
        "editorial_segments",
        "event_ids",
        "graphical_style",
        "license_model",
        "max_dimensions",
        "orientation",
        "product_types",
        "quality_rank",
        "referral_destinations",
        "title"
    ]
}

Display Fields Set

The display_set query string parameter fields value represents the fields that provide you with URLs for the low resolution files
that are most frequently used to build a UI displaying search results. The following fields are provided for every image in your result
set when you include display_set in your request.

The URI provided is subject to change at any time and must be used as-is with no modification.

JSON

{
    "images":
    [
        "display_sizes": 
        [
            {
                "is_watermarked": <boolean>,
                "name": "comp",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "preview",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "thumb",
                "uri": "<link>"
            }
        ]
    ]
}

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Id`	Identifies an existing image
`Fields`	Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates.
`Page`	Identifies page to return. Default is 1.
`Page Size`	Specifies page size. Default is 30, maximum page_size is 100.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/images/{id}/similar

This endpoint will provide a list of images that are similar to the specified asset id.

You'll need an API key and access token to use this resource.

Working with Fields Sets

Fields sets are used in the fields request parameter to receive a suite of metadata fields. The following fields sets are available:

Summary Fields Set

The summary_set query string parameter fields value represents a small batch of metadata fields that are often used to build
search response results. The following fields are provided for every image in your result set when you include summary_set in your request.

JSON

{
    "images":
    [
        "asset_family",
        "caption",
        "collection_code",
        "collection_id",
        "collection_name",
        "display_sizes": 
        [
            {
                "name": "thumb"
            }
        ]
        "license_model",
        "max_dimensions",
        "title"
    ]
}

Detail Fields Set

The detail_set query string parameter fields value represents a large batch of metadata fields that are often used to build a
detailed view of images. The following fields are provided for every image in your result set when you include detail_set in your request.

JSON

{
    "images":
    [
        "allowed_use",
        "artist",
        "asset_family",
        "call_for_image",
        "caption",
        "collection_code",
        "collection_id",
        "collection_name",
        "copyright",
        "date_created",
        "display_sizes": 
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ],
        "editorial_segments",
        "event_ids",
        "graphical_style",
        "license_model",
        "max_dimensions",
        "orientation",
        "product_types",
        "quality_rank",
        "referral_destinations",
        "title"
    ]
}

Display Fields Set

The display_set query string parameter fields value represents the fields that provide you with URLs for the low resolution files
that are most frequently used to build a UI displaying search results. The following fields are provided for every image in your result
set when you include display_set in your request.

The URI provided is subject to change at any time and must be used as-is with no modification.

JSON

{
    "images":
    [
        "display_sizes": 
        [
            {
                "is_watermarked": <boolean>,
                "name": "comp",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "preview",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "thumb",
                "uri": "<link>"
            }
        ]
    ]
}

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Id`	Identifies an existing image
`Fields`	Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates.
`Page`	Identifies page to return. Default is 1.
`Page Size`	Specifies page size. Default is 30, maximum page_size is 100.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/images/{id}/downloadhistory

Retrieve the download history for a specific image asset.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Id`	An image id.
`Company Downloads`	If specified, returns the list of previously downloaded images for all users in your company. Your account must be enabled for this functionality. Contact your Getty Images account rep for more information. Default is false.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/orders/{id}

This endpoint returns detailed order metadata for a specified order.
Use of this endpoint requires configuration changes to your API key.

You'll need an API key and access token to use this resource.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Id`	An order id.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/products

This endpoint returns all products available to the username used during authentication. As such, this endpoint requires the use of
a fully authorized access_token. The product data can then be used as search filters, restricting results to images from a specific product.

You'll need an API key and access token to use this resource.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Fields`	Comma separated list of fields. Allows product download requirements to be returned.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/purchased-assets

This endpoint returns a list of all assets purchased on gettyimages.com by the username used for authentication.
Use of this endpoint requires configuration changes to your API key. Please contact your sales representative
to learn more.

You'll need an API key and access token to use this resource.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Date To`	If specified, retrieves previous purchases on or before this date. Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD).
`Page`	Identifies page to return. Default is 1.
`Page Size`	Specifies page size. Default is 75, maximum page_size is 100.
`Date From`	If specified, retrieves previous purchases on or after this date. Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD).
`Company Purchases`	If specified, returns the list of previously purchased assets for all users in your company. Your account must be enabled for this functionality. Contact your Getty Images account rep for more information. Default is false.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/search/images

_This endpoint draws from such a large diversity of content, the results will not be as relevant as when the more specific Creative or Editorial endpoints are used. Additionally, the response time for this endpoint is slower compared to that for Creative and Editorial-specific endpoints. For these reasons,_ _it is highly recommended that those endpoints are used instead of this blended endpoint._

You'll need an API key and access token to use this resource.

You can show different information in the response by specifying values on the "fields" parameter (see details below).
You can search with only an API key, and that will give you search results that are equivalent to doing a search on the GettyImages.com site without being logged in (anonymous search). If you are a Getty Images API customer and would like to ensure that your API searches return only assets that you have a license to use, you need to also include an authorization token in the header of your request. Please consult our Authorization FAQ for more information on authorization tokens, and our Authorization Workflows for code examples of getting a token.

To include your API token in the search request, add it to the headers as a Bearer token (example in curl):

-H "Authorization: Bearer "

Search requests without a phrase parameter are not supported and may not always work.

Working with Fields Sets

Fields sets are used in the fields request parameter to receive a suite of metadata fields. The following fields sets are available:

Summary Fields Set

The summary_set query string parameter fields value represents a small batch of metadata fields that are often used to build search response results. The following fields are provided for every image in your result set when you include summary_set in your request.

JSON

{
    "images": 
    [
        "asset_family",
        "caption",
        "collection_code",
        "collection_id",
        "collection_name",
        "display_sizes": 
        [
            {
                "name": "thumb"
            }
        ],
        "license_model",
        "max_dimensions",
        "title"
    ]
}

Detail Fields Set

The detail_set query string parameter fields value represents a large batch of metadata fields that are often used to build a detailed view of images.
The following fields are provided for every image in your result set when you include detail_set in your request.

JSON

{
    "images": 
    [
        "allowed_use",
        "artist",
        "asset_family",
        "call_for_image",
        "caption",
        "collection_code",
        "collection_id",
        "collection_name",
        "copyright",
        "date_created",
        "display_sizes": 
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ],
        "editorial_segments",
        "event_ids",
        "graphical_style",
        "license_model",
        "max_dimensions",
        "orientation",
        "product_types",
        "quality_rank",
        "referral_destinations",
        "title"
    ]
]

Display Fields Set

The display_set query string parameter fields value represents the fields that provide you with URLs for the low resolution files that are most
frequently used to build a UI displaying search results. The following fields are provided for every image in your result set when you include display_set
in your request.

The URI provided is subject to change at any time and must be used as-is with no modification.

JSON

{
    "images":
    [
        "display_sizes": 
        [
            {
                "is_watermarked": <boolean>,
                "name": "comp",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "preview",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "thumb",
                "uri": "<link>"
            }
        ]
    ]
}

Request Usage Considerations

Specifying the "entity_details" response field can have significant performance implications. The field should be used only when necessary.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Gi-country-code`	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.
`Age Of People`	Filter based on the age of individuals in an image.
`Artists`	Search for images by specific artists (free-text, comma-separated list of artists).
`Collection Codes`	Filter by collection codes (comma-separated list). Include or exclude based on collections_filter_type.
`Collections Filter Type`	Provides searching based on specified collection(s). The default is Include
`Color`	Filter based on predominant color in an image. Use 6 character hexidecimal format (e.g., #002244). Note: when specified, results will not contain editorial images.
`Compositions`	Filter based on image composition.
`Download Product`	Filters based on which product the asset will download against. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription. If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. Product ID can be obtained from the GET /products response.
`Embed Content Only`	Restrict search results to embeddable images. The default is false.
`Event Ids`	Filter based on specific events
`Ethnicity`	Filter search results based on the ethnicity of individuals in an image.
`Exclude Nudity`	Excludes images containing nudity. The default is false.
`Fields`	Specifies fields to return. Defaults to 'summary_set'.
`File Types`	Return only images having a specific file type.
`Graphical Styles`	Filter based on graphical style of the image.
`Graphical Styles Filter Type`	Provides searching based on specified graphical style(s). The default is Include
`Include Related Searches`	Specifies whether or not to include related searches in the response. The default is false.
`Keyword Ids`	Return only images tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those images matching the query phrase which also contain the requested keyword(s) are returned.
`Minimum Size`	Filter based on minimum size requested. The default is x-small
`Number Of People`	Filter based on the number of people in the image.
`Orientations`	Return only images with selected aspect ratios.
`Page`	Request results starting at a page number (default is 1).
`Page Size`	Request number of images to return in each page. Default is 30, maximum page_size is 100.
`Phrase`	Search images using a search phrase.
`Sort Order`	Select sort order of results. The default is best_match
`Specific People`	Return only images associated with specific people (using a comma-delimited list).
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/search/images/creative/by-image

Search for similar creative images by passing an image_url to an uploaded image OR an asset_id of an asset in our catalog. All responses will have the exclude_nudity filter automatically applied.

Searching by URL

Before calling the search by image endpoint, an image 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 image has been uploaded, use the full URL in the image_url parameter, e.g. image_url=https://api.gettyimages.com/v3/search/by-image/uploads/my-test-image.jpg.

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 searches must be performed using the _same_ API Key.

Searching by asset id

When searching by asset_id, any image or video asset id in the Getty/iStock catalog can be used as the source for similar images.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Gi-country-code`	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.
`Asset Id`	Specifies the Getty image id to use in the search.
`Exclude Editorial Use Only`	Exclude images that are only available for editorial (non-commercial) use. Default value is false.
`Facet Fields`	Specifies the facets to return in the response. Facets provide additional search parameters to refine your results. The include_facets parameter must be set to "true" for facets to be returned.
`Facet Max Count`	Specifies the maximum number of facets to return per type. Default is 300.
`Fields`	Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates.
`Image Url`	Specifies the location of the image to use in the search.
`Include Facets`	Specifies whether or not to include facets in the result set. Default is "false".
`Page`	Request results starting at a page number (default is 1).
`Page Size`	Request number of images to return in each page. Default is 30, maximum page_size is 100.
`Phrase`	Free-text search query.
`Product Types`	Filter images to those from one of your product types. Allowed values are easyaccess, imagepack, premiumaccess and royaltyfreesubscription. If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. For example, some users may have more than one premiumaccess product, so the product_types value would be premiumaccess:1234. Product ID can be obtained from the GET /products response.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/search/images/creative

Use this endpoint to search our contemporary stock photos, illustrations and archival images.

You'll need an API key and access token to use this resource.

You can show different information in the response by specifying values on the "fields" parameter (see details below).
You can search with only an API key, and that will give you search results that are equivalent to doing a search on the GettyImages.com site without being logged in (anonymous search). If you are a Getty Images API customer and would like to ensure that your API searches return only assets that you have a license to use, you need to also include an authorization token in the header of your request. Please consult our Authorization FAQ for more information on authorization tokens, and our Authorization Workflows for code examples of getting a token.

Search requests without a phrase parameter are not supported and may not always work.

Working with Fields Sets

Fields sets are used in the fields request parameter to receive a suite of metadata fields. The following fields sets are available:

Summary Fields Set

The summary_set query string parameter fields value represents a small batch of metadata fields that are often used to
build search response results. The following fields are provided for every image in your result set when you include summary_set in your request.

JSON

{
    "images": 
    [
        "asset_family",
        "caption",
        "collection_code",
        "collection_id",
        "collection_name",
        "display_sizes": 
        [
            {
                "name": "thumb"
            }
        ],
        "license_model",
        "max_dimensions",
        "title"
    ]
}

Detail Fields Set

The detail_set query string parameter fields value represents a large batch of metadata fields that are often used to
build a detailed view of images. The following fields are provided for every image in your result set when you include detail_set in your request.

JSON

{
    "images": 
    [
        "allowed_use",
        "artist",
        "asset_family",
        "call_for_image",
        "caption",
        "collection_code",
        "collection_id",
        "collection_name",
        "copyright",
        "date_created",
        "display_sizes": 
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ],
        "editorial_segments",
        "event_ids",
        "graphical_style",
        "license_model",
        "max_dimensions",
        "orientation",
        "product_types",
        "quality_rank",
        "referral_destinations",
        "title"
    ]
]

Display Fields Set

The display_set query string parameter fields value represents the fields that provide you with URLs for the low resolution
files that are most frequently used to build a UI displaying search results. The following fields are provided for every image
in your result set when you include display_set in your request.

The URI provided is subject to change at any time and must be used as-is with no modification.

JSON

{
    "images":
    [
        "display_sizes": 
        [
            {
                "is_watermarked": <boolean>,
                "name": "comp",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "preview",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "thumb",
                "uri": "<link>"
            }
        ]
    ]
}

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Gi-country-code`	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.
`Age Of People`	Filter based on the age of individuals in an image.
`Artists`	Search for images by specific artists (free-text, comma-separated list of artists).
`Collection Codes`	Filter by collection codes (comma-separated list). Include or exclude based on collections_filter_type.
`Collections Filter Type`	Use to include or exclude collections from search. The default is include
`Color`	Filter based on predominant color in an image. Use 6 character hexadecimal format (e.g., #002244).
`Compositions`	Filter based on image composition.
`Download Product`	Filters based on which product the asset will download against. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription. If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. Product ID can be obtained from the GET /products response.
`Embed Content Only`	Restrict search results to embeddable images. The default is false.
`Ethnicity`	Filter search results based on the ethnicity of individuals in an image.
`Exclude Keyword Ids`	Return only images not tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those images matching the query phrase which also do not contain the requested keyword(s) are returned.
`Exclude Nudity`	Excludes images containing nudity. The default is false.
`Exclude Editorial Use Only`	Exclude images that are only available for editorial (non-commercial) use. Default value is false.
`Fields`	Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates.
`File Types`	Return only images having a specific file type.
`Graphical Styles`	Filter based on graphical style of the image.
`Graphical Styles Filter Type`	Provides searching based on specified graphical style(s). The default is include.
`Include Related Searches`	Specifies whether or not to include related searches in the response. The default is false.
`Keyword Ids`	Return only images tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those images matching the query phrase which also contain the requested keyword(s) are returned.
`Minimum Size`	Filter based on minimum size requested. The default is x-small.
`Moods`	Filter based on predominant mood in an image.
`Number Of People`	Filter based on the number of people in the image.
`Orientations`	Return only images with selected aspect ratios.
`Page`	Request results starting at a page number (default is 1).
`Page Size`	Request number of images to return in each page. Default is 30, maximum page_size is 100.
`Phrase`	Search images using a search phrase.
`Safe Search`	Setting safe_search to "true" excludes images containing nudity, death, profanity, drugs and alcohol, suggestive content, and graphic content from the result set. The default is false. Because this is a keyword-based filter, it's possible that a small number of unsafe images may not be caught by the filter. Please direct feedback to your Getty Images Account or API support representative.
`Sort Order`	Select sort order of results. The default is best_match
`Facet Fields`	Specifies the facets to return in the response. Facets provide additional search parameters to refine your results. The include_facets parameter must be set to "true" for facets to be returned.
`Include Facets`	Specifies whether or not to include facets in the result set. Default is "false".
`Facet Max Count`	Specifies the maximum number of facets to return per type. Default is 300.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/search/videos/creative

Use this endpoint to search premium stock video, from archival film to contemporary 4K and HD footage.

You'll need an API key and access token to use this resource.

You can show different information in the response by specifying values on the "fields" parameter (see details below).
You can search with only an API key, and that will give you search results that are equivalent to doing a search on the GettyImages.com site without
being logged in (anonymous search). If you are a Getty Images API customer and would like to ensure that your API searches return only
assets that you have a license to use, you need to also include an authorization token in the header of your request.
Please consult our Authorization FAQ for more information on authorization tokens.

Search requests without a phrase parameter are not supported and may not always work.

Working with Fields Sets

Fields sets are used in the fields request parameter to receive a suite of metadata fields. The following fields sets are available:

Summary Fields Set

The summary_set query string parameter fields value represents a small batch of metadata fields that are often used to build search
response results. The following fields are provided for every video in your result set when you include summary_set in your request.

JSON

{
    "videos": 
    [
        "asset_family", 
        "caption",
        "collection_code",
        "collection_name",
        "display_sizes":
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ],
        "license_model",
        "title"
    ]
}

Detail Fields Set

The detail_set query string parameter fields value represents a large batch of metadata fields that are often used to build a
detailed view of videos. The following fields are provided for every video in your result set when you include detail_set in your request.

JSON

{
    "videos": 
    [
        "allowed_use",
        "artist",
        "asset_family", 
		"call_for_image",
        "caption", 
        "clip_length",
        "collection_code",
        "collection_id",
        "collection_name", 
        "color_type",
        "copyright",
        "date_created",
        "display_sizes":
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ],
        "era",
        "license_model",
        "mastered_to",
        "originally_shot_on",
        "product_types",
        "quality_rank",
        "shot_speed",
        "source",
        "title"
    ]
}

Display Fields Set

The display_set query string parameter fields value represents the fields that provide you with URLs for the low resolution files
that are most frequently used to build a UI displaying search results. The following fields are provided for every video in your result
set when you include display_set in your request.

The URI provided is subject to change at any time and must be used as-is with no modification.

JSON

{
    "videos":
    [
        "display_sizes": 
        [
            {
                "is_watermarked": <boolean>,
                "name": "comp",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "preview",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "thumb",
                "uri": "<link>"
            }
        ]
    ]
}

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Gi-country-code`	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.
`Age Of People`	Provides filtering according to the age of individuals in a video.
`Artists`	Search for videos by specific artists (free-text, comma-separated list of artists).
`Aspect Ratios`	Search for videos by specific aspect ratios.
`Collection Codes`	Provides filtering by collection code.
`Collections Filter Type`	Use to include or exclude collections from search. The default is include
`Compositions`	Filter based on video composition.
`Download Product`	Filters based on which product the asset will download against. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription. If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. Product ID can be obtained from the GET /products response.
`Ethnicity`	Filter search results based on the ethnicity of individuals.
`Exclude Nudity`	Excludes videos containing nudity. The default is false.
`Exclude Editorial Use Only`	Exclude videos that are only available for editorial (non-commercial) use. Default value is false.
`Exclude Keyword Ids`	Return only videos not tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those videos matching the query phrase which also do not contain the requested keyword(s) are returned.
`Fields`	Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate.
`Format Available`	Filters according to the digital video format available on a film asset.
`Frame Rates`	Provides filtering by video frame rate (frames/second).
`Image Techniques`	Filter based on image technique.
`Include Related Searches`	Specifies whether or not to include related searches in the response. The default is false.
`Keyword Ids`	Return only videos tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those videos matching the query phrase which also contain the requested keyword(s) are returned.
`License Models`	Specifies the video licensing model(s).
`Number Of People`	Filter based on the number of people.
`Orientations`	Return only videos with selected orientations.
`Min Clip Length`	Provides filtering by minimum length of video clip, in seconds
`Max Clip Length`	Provides filtering by maximum length of video, in seconds
`Page`	Identifies page to return. Default is 1.
`Page Size`	Specifies page size. Default is 30, maximum page_size is 100.
`Phrase`	Free-text search query.
`Safe Search`	Setting safe_search to "true" excludes images containing nudity, death, profanity, drugs and alcohol, suggestive content, and graphic content from the result set. The default is false. Because this is a keyword-based filter, it's possible that a small number of unsafe images may not be caught by the filter. Please direct feedback to your Getty Images Account or API support representative.
`Sort Order`	Select sort order of results. The default is best_match
`Release Status`	Allows filtering by type of model release.
`Facet Fields`	Specifies the facets to return in the response. Facets provide additional search parameters to refine your results. The include_facets parameter must be set to "true" for facets to be returned.
`Facet Max Count`	Specifies the maximum number of facets to return per type. Default is 300.
`Include Facets`	Specifies whether or not to include facets in the result set. Default is "false".
`Viewpoints`	Filter based on viewpoint.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/search/videos/creative/by-image

Search for similar creative videos by passing an image_url to an uploaded image/frame grab from a video OR an asset_id of an asset in our catalog. All responses will have the exclude_nudity filter automatically applied.

Searching by URL

Before calling the search by image endpoint, an image or frame grab 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 image has been uploaded, use the full URL in the image_url parameter, e.g. image_url=https://api.gettyimages.com/v3/search/by-image/uploads/my-test-image.jpg.

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 searches must be performed using the _same_ API Key.

Searching by asset id

When searching by asset_id, any image or video asset id in the Getty/iStock catalog can be used as the source for similar videos.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Gi-country-code`	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.
`Asset Id`	Specifies the Getty video id to use in the search.
`Exclude Editorial Use Only`	Exclude videos that are only available for editorial (non-commercial) use. Default value is false.
`Facet Fields`	Specifies the facets to return in the response. Facets provide additional search parameters to refine your results. The include_facets parameter must be set to "true" for facets to be returned.
`Facet Max Count`	Specifies the maximum number of facets to return per type. Default is 300.
`Fields`	Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate.
`Image Url`	Specifies the location of the image to use in the search.
`Include Facets`	Specifies whether or not to include facets in the result set. Default is "false".
`Page`	Request results starting at a page number (default is 1).
`Page Size`	Request number of images to return in each page. Default is 30, maximum page_size is 100.
`Phrase`	Free-text search query.
`Product Types`	Filter images to those from one of your product types. Allowed values are easyaccess, imagepack, premiumaccess and royaltyfreesubscription. If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. For example, some users may have more than one premiumaccess product, so the product_types value would be premiumaccess:1234. Product ID can be obtained from the GET /products response.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/search/images/editorial

Use this endpoint to search our editorial stock photos, illustrations and archival images. Editorial images represent newsworthy events or illustrate matters of general interest, such as news, sport and entertainment and are generally intended for editorial use.

You'll need an API key and access token to use this resource.

You can show different information in the response by specifying values on the "fields" parameter (see details below).
You can search with only an API key, and that will give you search results that are equivalent to doing a search on the GettyImages.com site without being logged in (anonymous search). If you are a Getty Images API customer and would like to ensure that your API searches return only assets that you have a license to use, you need to also include an authorization token in the header of your request. Please consult our Authorization FAQ for more information on authorization tokens, and our Authorization Workflows for code examples of getting a token.
To include your API token in the search request, add it to the headers as a Bearer token (example in curl):

-H "Authorization: Bearer "

Search requests without a phrase parameter are not supported and may not always work.

Working with Fields Sets

Fields sets are used in the fields request parameter to receive a suite of metadata fields. The following fields sets are available:

Summary Fields Set

The summary_set query string parameter fields value represents a small batch of metadata fields that are often used to build search response results. The following fields are provided for every image in your result set when you include summary_set in your request.

JSON

{
    "images": 
    [
        "asset_family",
        "caption",
        "collection_code",
        "collection_id",
        "collection_name",
        "display_sizes": 
        [
            {
                "name": "thumb"
            }
        ],
        "license_model",
        "max_dimensions",
        "title"
    ]
}

Detail Fields Set

The detail_set query string parameter fields value represents a large batch of metadata fields that are often used to build a detailed view of images. The following fields are provided for every image in your result set when you include detail_set in your request.

JSON

{
    "images": 
    [
        "allowed_use",
        "artist",
        "asset_family",
        "call_for_image",
        "caption",
        "collection_code",
        "collection_id",
        "collection_name",
        "copyright",
        "date_created",
        "display_sizes": 
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ],
        "editorial_segments",
        "event_ids",
        "graphical_style",
        "license_model",
        "max_dimensions",
        "orientation",
        "product_types",
        "quality_rank",
        "referral_destinations",
        "title"
    ]
]

Display Fields Set

The display_set query string parameter fields value represents the fields that provide you with URLs for the low resolution files that are most frequently used to build a UI displaying search results. The following fields are provided for every image in your result set when you include display_set in your request.

The URI provided is subject to change at any time and must be used as-is with no modification.

JSON

{
    "images":
    [
        "display_sizes": 
        [
            {
                "is_watermarked": <boolean>,
                "name": "comp",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "preview",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "thumb",
                "uri": "<link>"
            }
        ]
    ]
}

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Gi-country-code`	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.
`Age Of People`	Filter based on the age of individuals in an image.
`Artists`	Search for images by specific artists (free-text, comma-separated list of artists).
`Collection Codes`	Filter by collections (comma-separated list of collection codes). Include or exclude based on collections_filter_type.
`Collections Filter Type`	Use to include or exclude collections from search. The default is include
`Compositions`	Filter based on image composition.
`Date From`	Return only images that are created on or after this date. Use ISO 8601 format (e.g., 1999-12-31).
`Date To`	Return only images that are created on or before this date. Use ISO 8601 format (e.g., 1999-12-31).
`Download Product`	Filters based on which product the asset will download against. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription. If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. Product ID can be obtained from the GET /products response.
`Editorial Segments`	Return only events with a matching editorial segment.
`Embed Content Only`	Restrict search results to embeddable images. The default is false.
`Ethnicity`	Filter search results based on the ethnicity of individuals in an image.
`Event Ids`	Filter based on specific events
`Exclude Keyword Ids`	Return only images not tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those images matching the query phrase which also do not contain the requested keyword(s) are returned.
`Fields`	Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates.
`File Types`	Return only images having a specific file type.
`Graphical Styles`	Filter based on graphical style of the image.
`Graphical Styles Filter Type`	Provides searching based on specified graphical style(s). The default is include.
`Include Related Searches`	Specifies whether or not to include related searches in the response. The default is false.
`Keyword Ids`	Return only images tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those images matching the query phrase which also contain the requested keyword(s) are returned.
`Minimum Size`	Filter based on minimum size requested. The default is x-small.
`Number Of People`	Filter based on the number of people in the image.
`Orientations`	Return only images with selected aspect ratios.
`Page`	Request results starting at a page number (default is 1).
`Page Size`	Request number of images to return in each page. Default is 30, maximum page_size is 100.
`Phrase`	Search images using a search phrase.
`Sort Order`	Select sort order of results. The default is best_match
`Specific People`	Return only images associated with specific people (using a comma-delimited list).
`Minimum Quality Rank`	Filter search results based on minimum quality ranking. Possible values 1, 2, 3 with 1 being best.
`Facet Fields`	Specifies the facets to return in the response. Facets provide additional search parameters to refine your results. The include_facets parameter must be set to "true" for facets to be returned.
`Include Facets`	Specifies whether or not to include facets in the result set. Default is "false".
`Facet Max Count`	Specifies the maximum number of facets to return per type. Default is 300.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/search/videos/editorial

Use this endpoint to search current and archival video clips of celebrities, newsmakers, and events.

You'll need an API key and access token to use this resource.

You can show different information in the response by specifying values on the "fields" parameter (see details below).
You can search with only an API key, and that will give you search results that are equivalent to doing a search on the GettyImages.com site without being logged in (anonymous search). If you are a Getty Images API customer and would like to ensure that your API searches return only assets that you have a license to use, you need to also include an authorization token in the header of your request. Please consult our Authorization FAQ for more information on authorization tokens, and our Authorization Workflows for code examples of getting a token.

Search requests without a phrase parameter are not supported and may not always work.

Working with Fields Sets

Fields sets are used in the fields request parameter to receive a suite of metadata fields. The following fields sets are available:

Summary Fields Set

The summary_set query string parameter fields value represents a small batch of metadata fields that are often used to build search response results. The following fields are provided for every video in your result set when you include summary_set in your request.

JSON

{
    "videos": 
    [
        "asset_family", 
        "caption",
        "collection_code",
        "collection_name",
        "display_sizes":
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ],
        "license_model",
        "title"
    ]
}

Detail Fields Set

The detail_set query string parameter fields value represents a large batch of metadata fields that are often used to build a detailed view of videos. The following fields are provided for every video in your result set when you include detail_set in your request.

JSON

{
    "videos": 
    [
        "allowed_use",
        "artist",
        "asset_family", 
		"call_for_image",
        "caption", 
        "clip_length",
        "collection_code",
        "collection_id",
        "collection_name", 
        "color_type",
        "copyright",
        "date_created",
        "display_sizes":
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ],
        "era",
        "event_ids",
        "license_model",
        "mastered_to",
        "originally_shot_on",
        "product_types",
        "quality_rank",
        "shot_speed",
        "source",
        "title"
    ]
}

Display Fields Set

The display_set query string parameter fields value represents the fields that provide you with URLs for the low resolution files that are most frequently used to build a UI displaying search results. The following fields are provided for every video in your result set when you include display_set in your request.

The URI provided is subject to change at any time and must be used as-is with no modification.

JSON

{
    "videos":
    [
        "display_sizes": 
        [
            {
                "is_watermarked": <boolean>,
                "name": "comp",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "preview",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "thumb",
                "uri": "<link>"
            }
        ]
    ]
}

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Gi-country-code`	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.
`Age Of People`	Provides filtering according to the age of individuals in a video.
`Artists`	Search for videos by specific artists (free-text, comma-separated list of artists).
`Aspect Ratios`	Search for videos by specific aspect ratios.
`Collection Codes`	Provides filtering by collection code.
`Collections Filter Type`	Use to include or exclude collections from search. The default is include
`Compositions`	Filter based on video composition.
`Date From`	Return only images that are created on or after this date. Use ISO 8601 format (e.g., 1999-12-31).
`Date To`	Return only images that are created on or before this date. Use ISO 8601 format (e.g., 1999-12-31).
`Download Product`	Filters based on which product the asset will download against. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription. If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. Product ID can be obtained from the GET /products response.
`Editorial Video Types`	Allows filtering by types of video.
`Event Ids`	Filter based on specific events
`Fields`	Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate.
`Format Available`	Filters according to the digital video format available on a film asset.
`Frame Rates`	Provides filtering by video frame rate (frames/second).
`Image Techniques`	Filter based on image technique.
`Include Related Searches`	Specifies whether or not to include related searches in the response. The default is false.
`Keyword Ids`	Return only videos tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those videos matching the query phrase which also contain the requested keyword(s) are returned.
`Min Clip Length`	Provides filtering by minimum length of video clip, in seconds
`Max Clip Length`	Provides filtering by maximum length of video clip, in seconds
`Orientations`	Return only videos with selected orientations.
`Page`	Identifies page to return. Default is 1.
`Page Size`	Specifies page size. Default is 30, maximum page_size is 100.
`Phrase`	Free-text search query.
`Sort Order`	Select sort order of results. The default is best_match
`Specific People`	Allows filtering by specific peoples' names.
`Release Status`	Allows filtering by type of model release.
`Facet Fields`	Specifies the facets to return in the response. Facets provide additional search parameters to refine your results. The include_facets parameter must be set to "true" for facets to be returned.
`Include Facets`	Specifies whether or not to include facets in the result set. Default is "false".
`Facet Max Count`	Specifies the maximum number of facets to return per type. Default is 300.
`Viewpoints`	Filter based on viewpoint.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/search/events

Use this endpoint to search Getty Images news, sports and entertainment events. Getty Images photographers and videographers cover editorially-relevant events occurring around the world. All images or video clips produced in association with a specific event are assigned the same event ID. Event IDs are part of the metadata returned in Search results. Only content produced under a Getty Images brand name (Getty Images News, Getty Images Sports, Getty Images Entertainment, Film Magic, Wire Image) will be consistently assigned an event ID.

This endpoint will provide events based on a search phrase or editorial segment and an optional from/to date filter. You can show different information in the response by specifying values on the "fields" parameter. The results will include events whose associated images or videos may not be included in your product(s).

This endpoint requires only an API key. An access token is NOT required.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Gi-country-code`	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.
`Editorial Segment`	Filters to events with a matching editorial segment.
`Date From`	Filters to events that start on or after this date. Use ISO 8601 format (e.g., 1999-12-31). Defaults to UTC unless otherwise specified.
`Date To`	Filters to events that start on or before this date. Use ISO 8601 format (e.g., 1999-12-31). Defaults to UTC unless otherwise specified.
`Fields`	Specifies fields to return. Default set is 'id','name','start_date'.
`Page`	Request results starting at a page number (default is 1, maximum is 50).
`Page Size`	Request number of events to return in each page. Default is 30, maximum page_size is 100.
`Phrase`	Filters to events related to this phrase
`Sort Order`	Specifies the order in which to sort the results. Default is newest.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/search/by-image/uploads/{file-name}

Upload an image file to be used for search by image operations.

Parameters

Parameter Name	Description
`Content Type`	The content type of the request payload sent to the API (e.g. application/json).
`headers`	Additional HTTP header name/value pairs to include in the request.
`File-name`	Specify the file name for the uploaded image.
`Response Type`	The response format expected from the API (e.g. application/json).

Options (1)

Option Name	Description
`Options`	Provide additional options for the upload.

/v3/usage-batches/{id}

Report Usage

Use this endpoint to report the usages of a set of assets. The count of assets submitted in a single batch to this endpoint is limited to 1000. Note that all asset Ids specified must be valid or the operation will fail causing no usages to be recorded. In this case, you will need to remove the invalid asset Ids from the query request and re-submit the query.

Quickstart

You'll need an API key and an access token to use this resource.

_Note_: Date of use can be in any unambiguous date format.

Parameters

Parameter Name	Description
`Content Type`	The content type of the request payload sent to the API (e.g. application/json).
`headers`	Additional HTTP header name/value pairs to include in the request.
`Id`	Specifies a unique batch transaction id to identify the report.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/videos/{id}

Use this endpoint to return detailed video metadata for the specified video id.

You'll need an API key and access token to use this resource.

You can show different information in the response by specifying values on the "fields" parameter (see details below).
You can search with only an API key, and that will give you search results that are equivalent to doing a search on the GettyImages.com site without being logged in (anonymous search). If you are a Getty Images API customer and would like to ensure that your API searches return only assets that you have a license to use, you need to also include an authorization token in the header of your request. Please consult our Authorization FAQ for more information on authorization tokens, and our Authorization Workflows for code examples of getting a token.

Working with Fields Sets

Fields sets are used in the fields request parameter to receive a suite of metadata fields. The following fields sets are available:

Summary Fields Set

The summary_set query string parameter fields value represents a small batch of metadata fields that are often used to build search response results. The following fields are provided for every video in your result set when you include summary_set in your request.

JSON

{
    "videos":
    [
        "asset_family",
        "caption",
        "collection_code",
        "collection_name",
        "display_sizes":
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ],
        "license_model",
        "title"
    ]
}

Detail Fields Set

The detail_set query string parameter fields value represents a large batch of metadata fields that are often used to build a detailed view of videos. The following fields are provided for every video in your result set when you include detail_set in your request.

JSON

{
    "videos":
    [
        "allowed_use",
        "artist",
        "asset_family",
		"call_for_image",
        "caption",
        "clip_length",
        "collection_code",
        "collection_id",
        "collection_name",
        "color_type",
        "copyright",
        "date_created",
        "display_sizes":
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ],
        "download_sizes",
        "era",
        "event_ids",
        "license_model",
        "mastered_to",
        "originally_shot_on",
        "product_types",
        "quality_rank",
        "shot_speed",
        "source",
        "title"
    ]
}

Display Fields Set

The display_set query string parameter fields value represents the fields that provide you with URLs for the low resolution files that are most frequently used to build a UI displaying search results. The following fields are provided for every video in your result set when you include display_set in your request.

The URI provided is subject to change at any time and must be used as-is with no modification.

JSON

{
    "display_sizes": [
        {
            "is_watermarked": <boolean>,
            "name": "comp",
            "uri": "<link>"
        },
        {
            "is_watermarked": <boolean>,
            "name": "preview",
            "uri": "<link>"
        },
        {
            "is_watermarked": <boolean>,
            "name": "thumb",
            "uri": "<link>"
        }
    ],
    "key_frames": [
        {
            "uri": "<link>"
        },
        {
            "uri": "<link>"
        },
        {
            "uri": "<link>"
        },
        {
            "uri": "<link>"
        },
        {
            "uri": "<link>"
        }
    ]
}

Request Usage Considerations

Specifying the "entity_details" response field can have significant performance implications. The field should be used only when necessary.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Id`	A video id. For more than one video please use the /v3/video endpoint.
`Fields`	Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/videos

Use this endpoint to return detailed video metadata for all the specified video ids.

You'll need an API key and access token to use this resource.

You can show different information in the response by specifying values on the "fields" parameter (see details below).
You can search with only an API key, and that will give you search results that are equivalent to doing a search on the GettyImages.com site without being logged in (anonymous search). If you are a Getty Images API customer and would like to ensure that your API searches return only assets that you have a license to use, you need to also include an authorization token in the header of your request. Please consult our Authorization FAQ for more information on authorization tokens, and our Authorization Workflows for code examples of getting a token.

Working with Fields Sets

Fields sets are used in the fields request parameter to receive a suite of metadata fields. The following fields sets are available:

Summary Fields Set

The summary_set query string parameter fields value represents a small batch of metadata fields that are often used to build search response results. The following fields are provided for every video in your result set when you include summary_set in your request.

JSON

{
    "videos": 
    [
        "asset_family",
        "caption",
        "collection_code",
        "collection_name",
        "display_sizes":
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ],
        "license_model",
        "title"
    ]
}

Detail Fields Set

The detail_set query string parameter fields value represents a large batch of metadata fields that are often used to build a detailed view of videos. The following fields are provided for every video in your result set when you include detail_set in your request.

JSON

{
    "videos": 
    [
        "allowed_use",
        "artist",
        "asset_family",
		"call_for_image",
        "caption",
        "clip_length",
        "collection_code",
        "collection_id",
        "collection_name",
        "color_type",
        "copyright",
        "date_created",
        "display_sizes":
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ],
        "download_sizes",
        "era",
        "event_ids",
        "license_model",
        "mastered_to",
        "originally_shot_on",
        "product_types",
        "quality_rank",
        "shot_speed",
        "source",
        "title"
    ]
}

Display Fields Set

The display_set query string parameter fields value represents the fields that provide you with URLs for the low resolution files that are most frequently used to build a UI displaying search results. The following fields are provided for every video in your result set when you include display_set in your request.

The URI provided is subject to change at any time and must be used as-is with no modification.

JSON

{
    "videos":
    [
      {
        "display_sizes": 
        [
            {
                "is_watermarked": <boolean>,
                "name": "comp",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "preview",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "thumb",
                "uri": "<link>"
            }
        ],
        "key_frames": [
            {
              "uri": "<link>"
            },
            {
              "uri": "<link>"
            },
            {
              "uri": "<link>"
            },
            {
              "uri": "<link>"
            },
            {
              "uri": "<link>"
            }
        ]
      }
    ]
}

Request Usage Considerations

Specifying the "entity_details" response field can have significant performance implications. The field should be used only when necessary.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Ids`	Specifies one or more video ids to return. Use comma delimiter when requesting multiple ids. Maximum of 100 ids.
`Fields`	Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/videos/{id}/same-series

This endpoint will provide the list of videos, if any exist, from the same series as the specified creative asset id. These images are typically from the same photo shoot. This functionality will not work for editorial assets.

You'll need an API key and access token to use this resource.

Working with Fields Sets

Fields sets are used in the fields request parameter to receive a suite of metadata fields. The following fields sets are available:

Summary Fields Set

The summary_set query string parameter fields value represents a small batch of metadata fields that are often used to build search response results. The following fields are provided for every video in your result set when you include summary_set in your request.

JSON

{
    "videos":
    [
        "asset_family",
        "caption",
        "collection_code",
        "collection_name",
        "display_sizes":
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ],
        "license_model",
        "title"
    ]
}

Detail Fields Set

The detail_set query string parameter fields value represents a large batch of metadata fields that are often used to build a detailed view of videos. The following fields are provided for every video in your result set when you include detail_set in your request.

JSON

{
    "videos":
    [
        "allowed_use",
        "artist",
        "asset_family",
		"call_for_image",
        "caption",
        "clip_length",
        "collection_code",
        "collection_id",
        "collection_name",
        "color_type",
        "copyright",
        "date_created",
        "display_sizes":
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ],
        "download_sizes",
        "era",
        "license_model",
        "mastered_to",
        "originally_shot_on",
        "product_types",
        "quality_rank",
        "shot_speed",
        "source",
        "title"
    ]
}

Display Fields Set

The display_set query string parameter fields value represents the fields that provide you with URLs for the low resolution files that are most frequently used to build a UI displaying search results. The following fields are provided for every video in your result set when you include display_set in your request.

The URI provided is subject to change at any time and must be used as-is with no modification.

JSON

{
    "videos":
    [
        "display_sizes": 
        [
            {
                "is_watermarked": <boolean>,
                "name": "comp",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "preview",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "thumb",
                "uri": "<link>"
            }
        ]
    ]
}

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Id`	Identifies an existing video
`Fields`	Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate.
`Page`	Identifies page to return. Default is 1.
`Page Size`	Specifies page size. Default is 30, maximum page_size is 100.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/videos/{id}/similar

This endpoint will provide a list of videos that are similar to the specified asset id.

You'll need an API key and access token to use this resource.

Working with Fields Sets

Fields sets are used in the fields request parameter to receive a suite of metadata fields. The following fields sets are available:

Summary Fields Set

The summary_set query string parameter fields value represents a small batch of metadata fields that are often used to build search response results. The following fields are provided for every video in your result set when you include summary_set in your request.

JSON

{
    "videos": 
    [
        "asset_family",
        "caption",
        "collection_code",
        "collection_name",
        "display_sizes":
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ],
        "license_model",
        "title"
    ]
}

Detail Fields Set

The detail_set query string parameter fields value represents a large batch of metadata fields that are often used to build a detailed view of videos. The following fields are provided for every video in your result set when you include detail_set in your request.

JSON

{
    "videos": 
    [
        "allowed_use",
        "artist",
        "asset_family",
		"call_for_image",
        "caption",
        "clip_length",
        "collection_code",
        "collection_id",
        "collection_name",
        "color_type",
        "copyright",
        "date_created",
        "display_sizes":
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ],
        "download_sizes",
        "era",
        "event_ids",
        "license_model",
        "mastered_to",
        "originally_shot_on",
        "product_types",
        "quality_rank",
        "shot_speed",
        "source",
        "title"
    ]
}

Display Fields Set

The display_set query string parameter fields value represents the fields that provide you with URLs for the low resolution files that are most frequently used to build a UI displaying search results. The following fields are provided for every video in your result set when you include display_set in your request.

The URI provided is subject to change at any time and must be used as-is with no modification.

JSON

{
    "videos":
    [
        "display_sizes": 
        [
            {
                "is_watermarked": <boolean>,
                "name": "comp",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "preview",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "thumb",
                "uri": "<link>"
            }
        ]
    ]
}

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Id`	A video id.
`Fields`	Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate.
`Page`	Identifies page to return. Default is 1.
`Page Size`	Specifies page size. Default is 30, maximum page_size is 100.
`Response Type`	The response format expected from the API (e.g. application/json).

/v3/videos/{id}/downloadhistory

Retrieve the download history for a specific video asset.

Parameters

Parameter Name	Description
`headers`	Additional HTTP header name/value pairs to include in the request.
`Accept-language`	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).
`Id`	A video id.
`Company Downloads`	If specified, returns the list of previously downloaded videos for all users in your company. Your account must be enabled for this functionality. Contact your Getty Images account rep for more information. Default is false.
`Response Type`	The response format expected from the API (e.g. application/json).

AffiliateSearch (2)

AiGenerator (13)

AI Generator - Download Image

Download Image Request body details

Fulfilled and Pending Results

AI Generator - Image Extension

The Image Extend Request

Fulfilled and Pending Results

Lifetime of Generated Images

AI Generator - Image Extension

The Image Extend Request

Fulfilled and Pending Results

Lifetime of Generated Images

AI Generator - Generate Images

The Image Generations Request

Fulfilled and Pending Results

Lifetime of Generated Images

AI Generator - Get Download Sizes

AI Generator - Get Generated Images

Fulfilled and Pending Results

Lifetime of Generated Images

AI Generator - Generate Variations

Fulfilled and Pending Results

Lifetime of Generated Images

AI Generator - Get Download Image

Fulfilled and Pending Results

Re-download AI Generated media

`ReDownloadRequest` details

AI Generator - Image Refining

The Image Refine Request

Uploading mask image

Fulfilled and Pending Results

Lifetime of Generated Images

AI Generator - Image Refining

The Image Refine Request

Uploading mask image

Fulfilled and Pending Results

Lifetime of Generated Images

AI Generator - Generation History

Artists (2)

AssetChanges (3)

Delete Asset Changes

Quickstart

Get Partner Channels

Quickstart

Asset Changes

Quickstart

AssetLicensing

AssetManagement

Boards (12)

Collections

Countries

Customers

Downloads (3)

Auto Downloads

Downloading Via the Returned URI

Download URI expiration

Auto Downloads

Downloading Via the Returned URI

Download URI expiration

Events (2)

Images (5)

Working with Fields Sets

Summary Fields Set

Detail Fields Set

Display Fields Set

Request Usage Considerations

Working with Fields Sets

Summary Fields Set

Detail Fields Set

Display Fields Set

Request Usage Considerations

Working with Fields Sets

Summary Fields Set

Detail Fields Set

Display Fields Set

Working with Fields Sets

Summary Fields Set

Detail Fields Set

Display Fields Set