Version 1
Connector Overview: This page documents all 65 actions for the Gettyimagesconnector v1.
AffiliateSearch (2)
GET /v3/affiliates/search/images
/v3/affiliates/search/images
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
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. |
|
|
Search images using a search phrase. |
|
|
Filter based on graphical style of the image. |
|
|
N/A |
GET /v3/affiliates/search/videos
/v3/affiliates/search/videos
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
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. |
|
|
N/A |
|
|
N/A |
AiGenerator (13)
PUT Begin the download process
/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 |
|---|---|
|
|
Must be either |
|
|
A note for the download. Some products require a note. |
|
|
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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID from a previous request to generate images |
|
|
The index of the image from the specific images generation |
|
|
N/A |
Options (3)
|
Option Name |
Description |
|---|---|
|
|
The notes to use for the download request. Some products require this value. |
|
|
The project code to use for the download request. Some products require this value. |
|
|
The size name. Valid values are 1k or 4k. |
POST Extend a creative image
/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 |
|---|---|
|
|
Required. The creative image id to extend. |
|
|
The primary text used for the extended portion of the images. |
|
|
Concepts to _exclude_ from the extended portion. |
|
|
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_. |
|
|
A note for the download. Some products require a note. |
|
|
The project code for the download. Some products require a project code. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (10)
|
Option Name |
Description |
|---|---|
|
|
The image id to extend. This value is required. |
|
|
This is the primary text used for the extension of the image. |
|
|
Concepts to exclude from the result |
|
|
If you have multiple Getty products, indicate which one you would like to use for this extend request |
|
|
The project code to use for the request. Some products require this value. |
|
|
The notes to use for the request. Some products require this value. |
|
|
The percentage to add to the left side of the image. |
|
|
The percentage to add to the right side of the image. |
|
|
The percentage to add to the top of the image. |
|
|
The percentage to add to the bottom of the image. |
POST Extend a generated 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 |
|---|---|
|
|
The primary text used for the extended portion of the images. |
|
|
Concepts to _exclude_ from the extended portion. |
|
|
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_. |
|
|
A note for the download. Some products require a note. |
|
|
The project code for the download. Some products require a project code. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID from a previous request to generate images |
|
|
The index of the image from the specific images generation |
|
|
N/A |
Options (9)
|
Option Name |
Description |
|---|---|
|
|
This is the primary text used for the extension of the image. |
|
|
Concepts to exclude from the result |
|
|
If you have multiple Getty products, indicate which one you would like to use for this extend request |
|
|
The project code to use for the request. Some products require this value. |
|
|
The notes to use for the request. Some products require this value. |
|
|
The percentage to add to the left side of the image. |
|
|
The percentage to add to the right side of the image. |
|
|
The percentage to add to the top of the image. |
|
|
The percentage to add to the bottom of the image. |
POST Generates images from a prompt
/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 |
|---|---|
|
|
The primary text used for the generation of the images. |
|
|
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_. |
|
|
Concepts to _exclude_ from the result |
|
|
The "width:height" aspect ratio of the resultant images. Must be one of: |
|
|
Media type of the results: |
|
|
Can be |
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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (9)
|
Option Name |
Description |
|---|---|
|
|
The only required parameter, this is the primary text used for the generation of the images. |
|
|
The seed to use for generation. This is not used for most generation cases but is available for use to ensure a repeatable result. |
|
|
Concepts to exclude from the result |
|
|
Aspect ratio of the result images. Must be one of 1:1, 3:4, 4:3, 9:16, or 16:9 |
|
|
N/A |
|
|
N/A |
|
|
If you have multiple Getty products, indicate which one you would like to use for this generation request |
|
|
The project code to use for the generation request. Some products require this value. |
|
|
The notes to use for the generation request. Some products require this value. |
GET Get download sizes for a generated image
/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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID from a previous request to generate images |
|
|
The index of the image from the specific images generation |
|
|
N/A |
GET Get generated images from a previous generation request
/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 OKwith the generated images' URLs and a generation requestidvalue -
HTTP 202 Acceptedwith the payload only containing a generation requestidvalue
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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID from a previous request to generate images |
|
|
N/A |
POST Get variations on a generated image
/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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID from a previous request to generate images |
|
|
The index of the image from the specific images generation |
|
|
N/A |
Options (3)
|
Option Name |
Description |
|---|---|
|
|
If you have multiple Getty products, indicate which one you would like to use for this generation request |
|
|
The project code to use for the generation request. Some products require this value. |
|
|
The notes to use for the generation request. Some products require this value. |
GET Once the download process has started, this endpoint can be used to check the status of the download and get the download URL once it is completed.
/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 OKwith the download URL -
HTTP 202 Acceptedwith 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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID from a previous request to generate images |
|
|
The index of the image from the specific images generation |
|
|
N/A |
POST Re-download a previously downloaded item
/v3/ai/redownloads
Re-download AI Generated media
Re-download previously downloaded AI generated media.
`ReDownloadRequest` details
|
Parameter |
Purpose |
|---|---|
|
|
The generated asset identifier to re-download. Can be retrieved from previously downloaded assets ( |
|
|
The product to use to re-download. Can be retrieved from products ( |
|
|
The size to re-download. Valid values are |
|
|
The project code to use for the download. Some products require a value for this. The products endpoint ( |
|
|
The notes to use for the download. Some products require a value for this. The products endpoint ( |
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (5)
|
Option Name |
Description |
|---|---|
|
|
The identifier of the previously-downloaded generated asset. |
|
|
The product ID to use for the download. |
|
|
The size name. Valid values are 1k or 4k. |
|
|
The project code to use for the download request. Some products require this value. |
|
|
The notes to use for the download request. Some products require this value. |
POST Refine a creative image
/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 |
|
|---|---|---|
|
|
Required. The creative image id to extend. |
|
|
|
The primary text used for refined portion of the images. |
|
|
|
Concepts to _exclude_ from the refined portion. |
|
|
|
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_. |
|
|
|
A note for the download. Some products require a note. |
|
|
|
The project code for the download. Some products require a project code. |
|
|
|
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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (7)
|
Option Name |
Description |
|---|---|
|
|
The image id to refine. This value is required. |
|
|
This is the primary text used for refining the images. |
|
|
Concepts to exclude from the result |
|
|
If you have multiple Getty products, indicate which one you would like to use for this refine request |
|
|
The project code to use for the request. Some products require this value. |
|
|
The notes to use for the request. Some products require this value. |
|
|
The location of the mask. This value is required. |
POST Refine a generated image
/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 |
|
|---|---|---|
|
|
The primary text used for refined portion of the images. |
|
|
|
Concepts to _exclude_ from the refined portion. |
|
|
|
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_. |
|
|
|
A note for the download. Some products require a note. |
|
|
|
The project code for the download. Some products require a project code. |
|
|
|
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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID from a previous request to generate images |
|
|
The index of the image from the specific images generation |
|
|
N/A |
Options (6)
|
Option Name |
Description |
|---|---|
|
|
This is the primary text used for refining the images. |
|
|
Concepts to exclude from the result |
|
|
If you have multiple Getty products, indicate which one you would like to use for this refine request |
|
|
The project code to use for the request. Some products require this value. |
|
|
The notes to use for the request. Some products require this value. |
|
|
The location of the mask. |
GET Retrieve history item for an individual generation request
/beta/ai/generation-history/{generationRequestId}
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
The ID from a previous request to generate images |
|
|
N/A |
GET Retrieve history of AI generations
/beta/ai/generation-history
AI Generator - Generation History
Get the history of AI generation requests.
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
If included, limits the results to those generation requests made on or after date_start. Both dates and datetimes are supported.
|
|
|
If included, limits the results to those generation requests made on or before date_end. Both dates and datetimes are supported.
|
|
|
If included, limits the results to those generation requests made for the given media type. |
|
|
The page size of results. Default is 30. |
|
|
The page number of results. Default is 1. |
|
|
If included, limits the results to only those requests made against the indicated products. |
|
|
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
|
|
|
N/A |
Artists (2)
GET Search for images by a photographer
/v3/artists/images
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th (iStock only), tr, uk (iStock only), vi (iStock only), zh-HK (creative assets only). |
|
|
Name of artist for desired images |
|
|
Comma separated list of fields. Allows restricting which fields are returned. If no fields are selected, the summary_set of fields are returned. |
|
|
Identifies page to return. Default page is 1. |
|
|
Specifies page size. Default page_size is 10, maximum page_size is 100. |
|
|
N/A |
GET Search for videos by a photographer
/v3/artists/videos
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th (iStock only), tr, uk (iStock only), vi (iStock only), zh-HK (creative assets only). |
|
|
Name of artist for desired images |
|
|
Comma separated list of fields. Allows restricting which fields are returned. If no fields are selected, the summary_set of fields are returned. |
|
|
Identifies page to return. Default page is 1. |
|
|
Specifies page size. Default page_size is 10, maximum page_size is 100. |
|
|
N/A |
AssetChanges (3)
DELETE Confirm asset change notifications.
/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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Specify the change-set-id associated with a transaction resource whose receipt you want to confirm. |
|
|
N/A |
GET Get a list of asset change notification channels.
/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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
PUT Get asset change notifications.
/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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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. |
|
|
Specifies the number of assets to return. The default is 2200; maximum is 2200. |
|
|
N/A |
AssetLicensing
POST Endpoint for acquiring extended licenses with iStock credits for an asset.
/v3/asset-licensing/{assetId}
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
Getty Images assetId - examples 520621493, 112301284 |
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
N/A |
|
|
Defaults to false. |
AssetManagement
GET /v3/asset-management/assets/send-events
/v3/asset-management/assets/send-events
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
Specifies a date/time (with timezone information) for continuing retrieval of events.
|
|
|
Specifies the number of events to return. Default is 50, maximum value is 100. |
|
|
N/A |
Boards (12)
POST Add a comment to a board
/v3/boards/{board_id}/comments
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
Specify the board to add a comment to. |
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
N/A |
PUT Add an asset to a board
/v3/boards/{board_id}/assets/{asset_id}
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
Specify the board to add an asset to. |
|
|
Specify the asset to add to the board. If it is already in the board's asset collection, no action is taken. |
|
|
N/A |
PUT Add assets to a board
/v3/boards/{board_id}/assets
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
Specify the board to add assets to. |
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
N/A |
POST Create a new board
/v3/boards
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
DELETE Delete a board
/v3/boards/{board_id}
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
Specify the board to delete. |
|
|
N/A |
DELETE Delete a comment from a board
/v3/boards/{board_id}/comments/{comment_id}
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
Specify the board containing the comment to delete. |
|
|
Specify the comment to delete. |
|
|
N/A |
GET Get all boards that the user participates in
/v3/boards
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
Request results starting at a page number (default is 1). |
|
|
Search for boards the user owns or has been invited to as an editor. |
|
|
Sort the list of boards by last update date or name. Defaults to date_last_updated_descending. |
|
|
Request number of boards to return in each page. (default is 30). |
|
|
N/A |
GET Get assets and metadata for a specific board
/v3/boards/{board_id}
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
Retrieve details for a specific board. |
|
|
N/A |
GET Get comments from a board
/v3/boards/{board_id}/comments
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
Specify the board to retrieve comments from. |
|
|
N/A |
DELETE Remove an asset from a board
/v3/boards/{board_id}/assets/{asset_id}
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
Specify the board to remove an asset from. |
|
|
Specify the asset to remove from the board. |
|
|
N/A |
DELETE Remove assets from a board
/v3/boards/{board_id}/assets
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
Specify the board to remove assets from. |
|
|
List the assets to be removed from the board. |
|
|
N/A |
PUT Update a board
/v3/boards/{board_id}
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
Specify the board to update. |
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
Collections
GET Gets collections applicable for the customer.
/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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
N/A |
Countries
GET Gets countries codes and names.
/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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
N/A |
Customers
GET Returns information about the current user.
/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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
N/A |
Downloads (3)
POST Download a video
/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:
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:
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:
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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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 of video to 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.
|
|
|
Specifies the size to be downloaded. |
|
|
Identifier of the instance for the selected product offering 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. |
|
|
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. |
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
POST Download an image
/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:
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:
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:
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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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 of image to 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.
|
|
|
File Type expressed with three character file extension. |
|
|
Specifies the pixel height of the particular image to download. C
|
|
|
Identifier of the instance for the selected product offering 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. |
|
|
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. |
|
|
N/A |
Options (2)
|
Option Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
GET Returns information about a customer's downloaded assets.
/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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
If specified, selects assets downloaded on or after this date. Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD).
|
|
|
If specified, selects assets downloaded on or before this date. Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD)
|
|
|
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
|
|
|
Identifies page to return. Default is 1. |
|
|
Specifies page size. Default is 30, maximum page_size is 100. |
|
|
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. |
|
|
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. |
|
|
N/A |
Events (2)
GET Get metadata for a single event
/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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
An event id. |
|
|
A comma separated list of fields to return in the response. |
|
|
N/A |
GET Get metadata for multiple events
/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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
A comma separated list of event ids. |
|
|
A comma separated list of fields to return in the response. |
|
|
N/A |
Images (5)
GET Get metadata for a single image by supplying one image id
/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.
{
"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.
{
"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.
{
"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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
An image id. For more than one image please use the /v3/images endpoint. |
|
|
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates. |
|
|
N/A |
GET Get metadata for multiple images by supplying multiple image ids
/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.
{
"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.
{
"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.
{
"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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
Specifies one or more image ids to return. Use comma delimiter when requesting multiple ids. Maximum of 100 ids. |
|
|
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates. |
|
|
N/A |
GET Retrieve creative images from the same series
/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.
{
"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.
{
"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.
{
"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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
Identifies an existing image |
|
|
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates. |
|
|
Identifies page to return. Default is 1. |
|
|
Specifies page size. Default is 30, maximum page_size is 100. |
|
|
N/A |
GET Retrieve similar images
/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.
{
"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.
{
"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.
{
"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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
Identifies an existing image |
|
|
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates. |
|
|
Identifies page to return. Default is 1. |
|
|
Specifies page size. Default is 30, maximum page_size is 100. |
|
|
N/A |
GET Returns information about a customer's download history for a specific asset
/v3/images/{id}/downloadhistory
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
An image id. |
|
|
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. |
|
|
N/A |
Orders
GET Get order metadata
/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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
An order id. |
|
|
N/A |
Products
GET Get Products
/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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
Comma separated list of fields. Allows product download requirements to be returned. |
|
|
N/A |
Purchases
GET Get Previously Purchased Images and Video
/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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
If specified, retrieves previous purchases on or before this date. Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD). |
|
|
Identifies page to return. Default is 1. |
|
|
Specifies page size. Default is 75, maximum page_size is 100. |
|
|
If specified, retrieves previous purchases on or after this date. Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD). |
|
|
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. |
|
|
N/A |
Search (9)
GET Search for both creative and editorial images - *** DEPRECATED ***
/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.
{
"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.
{
"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.
{
"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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
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. |
|
|
Filter based on the age of individuals in an image. |
|
|
Search for images by specific artists (free-text, comma-separated list of artists). |
|
|
Filter by collection codes (comma-separated list). Include or exclude based on collections_filter_type. |
|
|
Provides searching based on specified collection(s). The default is Include |
|
|
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. |
|
|
Filter based on image composition. |
|
|
Filters based on which product the asset will download against. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription.
|
|
|
Restrict search results to embeddable images. The default is false. |
|
|
Filter based on specific events |
|
|
Filter search results based on the ethnicity of individuals in an image. |
|
|
Excludes images containing nudity. The default is false. |
|
|
Specifies fields to return. Defaults to 'summary_set'. |
|
|
Return only images having a specific file type. |
|
|
Filter based on graphical style of the image. |
|
|
Provides searching based on specified graphical style(s). The default is Include |
|
|
Specifies whether or not to include related searches in the response. The default is false. |
|
|
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. |
|
|
Filter based on minimum size requested. The default is x-small |
|
|
Filter based on the number of people in the image. |
|
|
Return only images with selected aspect ratios. |
|
|
Request results starting at a page number (default is 1). |
|
|
Request number of images to return in each page. Default is 30, maximum page_size is 100. |
|
|
Search images using a search phrase. |
|
|
Select sort order of results. The default is best_match |
|
|
Return only images associated with specific people (using a comma-delimited list). |
|
|
N/A |
GET Search for creative images based on url
/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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
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. |
|
|
Specifies the Getty image id to use in the search. |
|
|
Exclude images that are only available for editorial (non-commercial) use. Default value is false. |
|
|
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. |
|
|
Specifies the maximum number of facets to return per type. Default is 300. |
|
|
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates. |
|
|
Specifies the location of the image to use in the search. |
|
|
Specifies whether or not to include facets in the result set. Default is "false". |
|
|
Request results starting at a page number (default is 1). |
|
|
Request number of images to return in each page. Default is 30, maximum page_size is 100. |
|
|
Free-text search query. |
|
|
Filter images to those from one of your product types. Allowed values are easyaccess, imagepack, premiumaccess and royaltyfreesubscription.
|
|
|
N/A |
GET Search for creative images only
/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.
{
"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.
{
"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.
{
"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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
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. |
|
|
Filter based on the age of individuals in an image. |
|
|
Search for images by specific artists (free-text, comma-separated list of artists). |
|
|
Filter by collection codes (comma-separated list). Include or exclude based on collections_filter_type. |
|
|
Use to include or exclude collections from search. The default is include |
|
|
Filter based on predominant color in an image. Use 6 character hexadecimal format (e.g., #002244). |
|
|
Filter based on image composition. |
|
|
Filters based on which product the asset will download against. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription.
|
|
|
Restrict search results to embeddable images. The default is false. |
|
|
Filter search results based on the ethnicity of individuals in an image. |
|
|
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. |
|
|
Excludes images containing nudity. The default is false. |
|
|
Exclude images that are only available for editorial (non-commercial) use. Default value is false. |
|
|
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates. |
|
|
Return only images having a specific file type. |
|
|
Filter based on graphical style of the image. |
|
|
Provides searching based on specified graphical style(s). The default is include. |
|
|
Specifies whether or not to include related searches in the response. The default is false. |
|
|
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. |
|
|
Filter based on minimum size requested. The default is x-small. |
|
|
Filter based on predominant mood in an image. |
|
|
Filter based on the number of people in the image. |
|
|
Return only images with selected aspect ratios. |
|
|
Request results starting at a page number (default is 1). |
|
|
Request number of images to return in each page. Default is 30, maximum page_size is 100. |
|
|
Search images using a search phrase. |
|
|
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. |
|
|
Select sort order of results. The default is best_match |
|
|
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. |
|
|
Specifies whether or not to include facets in the result set. Default is "false". |
|
|
Specifies the maximum number of facets to return per type. Default is 300. |
|
|
N/A |
GET Search for creative videos
/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.
{
"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.
{
"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.
{
"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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
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. |
|
|
Provides filtering according to the age of individuals in a video. |
|
|
Search for videos by specific artists (free-text, comma-separated list of artists). |
|
|
Search for videos by specific aspect ratios. |
|
|
Provides filtering by collection code. |
|
|
Use to include or exclude collections from search. The default is include |
|
|
Filter based on video composition. |
|
|
Filters based on which product the asset will download against. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription.
|
|
|
Filter search results based on the ethnicity of individuals. |
|
|
Excludes videos containing nudity. The default is false. |
|
|
Exclude videos that are only available for editorial (non-commercial) use. Default value is false. |
|
|
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. |
|
|
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate. |
|
|
Filters according to the digital video format available on a film asset. |
|
|
Provides filtering by video frame rate (frames/second). |
|
|
Filter based on image technique. |
|
|
Specifies whether or not to include related searches in the response. The default is false. |
|
|
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. |
|
|
Specifies the video licensing model(s). |
|
|
Filter based on the number of people. |
|
|
Return only videos with selected orientations. |
|
|
Provides filtering by minimum length of video clip, in seconds |
|
|
Provides filtering by maximum length of video, in seconds |
|
|
Identifies page to return. Default is 1. |
|
|
Specifies page size. Default is 30, maximum page_size is 100. |
|
|
Free-text search query. |
|
|
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. |
|
|
Select sort order of results. The default is best_match |
|
|
Allows filtering by type of model release. |
|
|
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. |
|
|
Specifies the maximum number of facets to return per type. Default is 300. |
|
|
Specifies whether or not to include facets in the result set. Default is "false". |
|
|
Filter based on viewpoint. |
|
|
N/A |
GET Search for creative videos based on url
/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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
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. |
|
|
Specifies the Getty video id to use in the search. |
|
|
Exclude videos that are only available for editorial (non-commercial) use. Default value is false. |
|
|
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. |
|
|
Specifies the maximum number of facets to return per type. Default is 300. |
|
|
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate. |
|
|
Specifies the location of the image to use in the search. |
|
|
Specifies whether or not to include facets in the result set. Default is "false". |
|
|
Request results starting at a page number (default is 1). |
|
|
Request number of images to return in each page. Default is 30, maximum page_size is 100. |
|
|
Free-text search query. |
|
|
Filter images to those from one of your product types. Allowed values are easyaccess, imagepack, premiumaccess and royaltyfreesubscription.
|
|
|
N/A |
GET Search for editorial images only
/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.
{
"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.
{
"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.
{
"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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
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. |
|
|
Filter based on the age of individuals in an image. |
|
|
Search for images by specific artists (free-text, comma-separated list of artists). |
|
|
Filter by collections (comma-separated list of collection codes). Include or exclude based on collections_filter_type. |
|
|
Use to include or exclude collections from search. The default is include |
|
|
Filter based on image composition. |
|
|
Return only images that are created on or after this date. Use ISO 8601 format (e.g., 1999-12-31). |
|
|
Return only images that are created on or before this date. Use ISO 8601 format (e.g., 1999-12-31). |
|
|
Filters based on which product the asset will download against. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription.
|
|
|
Return only events with a matching editorial segment. |
|
|
Restrict search results to embeddable images. The default is false. |
|
|
Filter search results based on the ethnicity of individuals in an image. |
|
|
Filter based on specific events |
|
|
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. |
|
|
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates. |
|
|
Return only images having a specific file type. |
|
|
Filter based on graphical style of the image. |
|
|
Provides searching based on specified graphical style(s). The default is include. |
|
|
Specifies whether or not to include related searches in the response. The default is false. |
|
|
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. |
|
|
Filter based on minimum size requested. The default is x-small. |
|
|
Filter based on the number of people in the image. |
|
|
Return only images with selected aspect ratios. |
|
|
Request results starting at a page number (default is 1). |
|
|
Request number of images to return in each page. Default is 30, maximum page_size is 100. |
|
|
Search images using a search phrase. |
|
|
Select sort order of results. The default is best_match |
|
|
Return only images associated with specific people (using a comma-delimited list). |
|
|
Filter search results based on minimum quality ranking. Possible values 1, 2, 3 with 1 being best. |
|
|
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. |
|
|
Specifies whether or not to include facets in the result set. Default is "false". |
|
|
Specifies the maximum number of facets to return per type. Default is 300. |
|
|
N/A |
GET Search for editorial videos
/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.
{
"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.
{
"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.
{
"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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
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. |
|
|
Provides filtering according to the age of individuals in a video. |
|
|
Search for videos by specific artists (free-text, comma-separated list of artists). |
|
|
Search for videos by specific aspect ratios. |
|
|
Provides filtering by collection code. |
|
|
Use to include or exclude collections from search. The default is include |
|
|
Filter based on video composition. |
|
|
Return only images that are created on or after this date. Use ISO 8601 format (e.g., 1999-12-31). |
|
|
Return only images that are created on or before this date. Use ISO 8601 format (e.g., 1999-12-31). |
|
|
Filters based on which product the asset will download against. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription.
|
|
|
Allows filtering by types of video. |
|
|
Filter based on specific events |
|
|
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate. |
|
|
Filters according to the digital video format available on a film asset. |
|
|
Provides filtering by video frame rate (frames/second). |
|
|
Filter based on image technique. |
|
|
Specifies whether or not to include related searches in the response. The default is false. |
|
|
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. |
|
|
Provides filtering by minimum length of video clip, in seconds |
|
|
Provides filtering by maximum length of video clip, in seconds |
|
|
Return only videos with selected orientations. |
|
|
Identifies page to return. Default is 1. |
|
|
Specifies page size. Default is 30, maximum page_size is 100. |
|
|
Free-text search query. |
|
|
Select sort order of results. The default is best_match |
|
|
Allows filtering by specific peoples' names. |
|
|
Allows filtering by type of model release. |
|
|
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. |
|
|
Specifies whether or not to include facets in the result set. Default is "false". |
|
|
Specifies the maximum number of facets to return per type. Default is 300. |
|
|
Filter based on viewpoint. |
|
|
N/A |
GET Search for events
/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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
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. |
|
|
Filters to events with a matching editorial segment. |
|
|
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. |
|
|
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. |
|
|
Specifies fields to return. Default set is 'id','name','start_date'. |
|
|
Request results starting at a page number (default is 1, maximum is 50). |
|
|
Request number of events to return in each page. Default is 30, maximum page_size is 100. |
|
|
Filters to events related to this phrase |
|
|
Specifies the order in which to sort the results. Default is newest. |
|
|
N/A |
PUT Upload image for use by the search creative images/videos operations
/v3/search/by-image/uploads/{file-name}
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
Options (1)
|
Option Name |
Description |
|---|---|
|
|
N/A |
Usage
PUT Report usage of assets via a batch format.
/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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
Specifies a unique batch transaction id to identify the report. |
|
|
N/A |
Videos (5)
GET Get metadata for a single video by supplying one video id
/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.
{
"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.
{
"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.
{
"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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
A video id. For more than one video please use the /v3/video endpoint. |
|
|
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate. |
|
|
N/A |
GET Get metadata for multiple videos by supplying multiple video ids
/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.
{
"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.
{
"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.
{
"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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
Specifies one or more video ids to return. Use comma delimiter when requesting multiple ids. Maximum of 100 ids. |
|
|
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate. |
|
|
N/A |
GET Retrieve creative videos from the same series
/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.
{
"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.
{
"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.
{
"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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
Identifies an existing video |
|
|
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate. |
|
|
Identifies page to return. Default is 1. |
|
|
Specifies page size. Default is 30, maximum page_size is 100. |
|
|
N/A |
GET Retrieve similar videos
/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.
{
"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.
{
"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.
{
"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 |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
A video id. |
|
|
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate. |
|
|
Identifies page to return. Default is 1. |
|
|
Specifies page size. Default is 30, maximum page_size is 100. |
|
|
N/A |
GET Returns information about a customer's download history for a specific asset
/v3/videos/{id}/downloadhistory
Parameters
|
Parameter Name |
Description |
|---|---|
|
|
N/A |
|
|
N/A |
|
|
N/A |
|
|
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). |
|
|
A video id. |
|
|
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. |
|
|
N/A |