GET

/v3/artists/images

Search for images by a photographer

Request

Query

Name	Data Type	Description
`page_size`	integer	Specifies page size. Default page_size is 10, maximum page_size is 100.
`page`	integer	Identifies page to return. Default page is 1.
`fields`	array	Comma separated list of fields. Allows restricting which fields are returned. If no fields are selected, the summary_set of fields are returned.
`artist_name`	string	Name of artist for desired images

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.
`Accept-Language`	string	Provide a header to specify the language of result values.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsArtistsImageSearchResults`	object

Properties

result_count integer

images array [GettyImagesModelsArtistsImageSearchItem]

GettyImagesModelsArtistsImageSearchItem object

Properties

title string

max_dimensions GettyImagesModelsMaxDimensions

GettyImagesModelsMaxDimensions object

Properties

`width`	integer
`height`	integer

license_model string

keywords array [GettyImagesModelsArtistsKeyword]

GettyImagesModelsArtistsKeyword object

Properties

`type`	string
`text`	string
`keyword_id`	string

id string

display_sizes array [GettyImagesModelsArtistsDisplaySize]

GettyImagesModelsArtistsDisplaySize object

Properties

`uri`	string
`name`	string
`is_watermarked`	boolean
`aspect_ratio`	string

date_submitted dateTime

collection_name string

collection_code string

caption string

asset_type string
Allowed values:
- Image
- Film

asset_family string

alternative_ids object

400InvalidParameterValue

401Unauthorized

GET

/v3/artists/videos

Search for videos by a photographer

Request

Query

Name	Data Type	Description
`page_size`	integer	Specifies page size. Default page_size is 10, maximum page_size is 100.
`page`	integer	Identifies page to return. Default page is 1.
`fields`	array	Comma separated list of fields. Allows restricting which fields are returned. If no fields are selected, the summary_set of fields are returned.
`artist_name`	string	Name of artist for desired images

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.
`Accept-Language`	string	Provide a header to specify the language of result values.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsArtistsVideoSearchResults`	object

Properties

videos array [GettyImagesModelsArtistsVideoSearchItem]

GettyImagesModelsArtistsVideoSearchItem object

Properties

title string

license_model string

keywords array [GettyImagesModelsArtistsKeyword]

GettyImagesModelsArtistsKeyword object

Properties

`type`	string
`text`	string
`keyword_id`	string

id string

display_sizes array [GettyImagesModelsArtistsDisplaySize]

GettyImagesModelsArtistsDisplaySize object

Properties

`uri`	string
`name`	string
`is_watermarked`	boolean
`aspect_ratio`	string

date_submitted dateTime

collection_name string

collection_code string

caption string

asset_type string
Allowed values:
- Image
- Film

asset_family string

alternative_ids object

result_count integer

400InvalidParameterValue

401Unauthorized

DELETE

/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 a Resource Owner Grant access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

Request

Path

Name	Data Type	Description
`change-set-id`	long

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Responses

200OK

403Your access token does not authorize access to this resource

404Transaction was not found

PUT

/v3/asset-changes/change-sets

Asset Changes

Get notifications about new, updated or deleted assets.

Quickstart

You'll need an API key and a Resource Owner Grant access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

Partner channels that have not been checked within the last 120 days will be removed and that partner will no longer be able to get change notifications from that channel. Partners who would like to start using the Asset Changes API again after a period of dormancy should contact their sales representative to be set up again.

Request

Query

Name	Data Type	Description
`batch_size`	integer	Specifies the number of assets to return. The default is 10; maximum is 500.
`channel_id`	integer	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.

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Responses

200OK

Body

Name	Data Type	Description
`AssetChanges`	object

Properties


                        changed_assets

array [ChangedAssetDetail]

Contains a list of ChangedAssetList results for the query.

ChangedAssetDetail object

Properties

`uri`	string	Contains the asset download URL for assets with an AssetLifecycle of "New."
`id`	string	Contains the Id for the asset change.
`asset_type`	string	Contains the type of asset this asset change is (i.e. "Image").
`asset_lifecycle`	string	Contains the type of change this asset change is. (i.e. "New," "Updated" or "Deleted")
`asset_changed_utc_datetime`	dateTime	Contains the date of the asset change.


                        change_set_id

string

Contains the identifier for the change-set resource. Passed into ConfirmAssetChanges requests to confirm receipt of the asset changes in the response.

403Your access token does not authorize access to this resource

404The channel you specified does not exist

GET

/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 a Resource Owner Grant access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

Only channels that have been queried in the last 120 days will be included in the list of channels. Partners who have a channel that has been removed should contact their sales representative to be set up again.

Request

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Responses

200OK

Body

Name	Data Type	Description
`PartnerChannelList`	object

Properties

channels array [PartnerChannel]


                        PartnerChannel

object

partner_channel

Properties

`start_date`	dateTime
`oldest_notification_date_utc`	dateTime	Specifies the date of the oldest notification currently in the channel in UTC
`notification_count`	integer	Specifies the current count of notifications pending in the channel
`channel_type`	string	Specifies the channel type (i.e. "New," "Updated" or "Deleted")
`channel_id`	integer	Specifies the identification number for the channel
`asset_type`	string	Specifies channel's asset type (i.e. "image", "film")
`asset_family`	string	Specifies the asset family for the channel (e.g. "editorial" or "creative")

404ChannelsNotFound

POST

/v3/asset-licensing/{assetId}

Endpoint for acquiring extended licenses with iStock credits for an asset.

Request

Path

Name	Data Type	Description
`assetId`	string	Getty Images assetId - examples 520621493, 112301284

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Body

Name	Data Type	Description
`GettyImagesControllersAssetLicensingAcquireAssetLicensesRequest`	object

Properties

`UseTeamCredits`	boolean	Defaults to false.
`LicenseTypes`	array [string] Allowed values: - `Multiseat` - `Unlimited` - `Resale` - `Indemnification`

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesControllersAssetLicensingAssetLicensingResponse`	object

Properties

`CreditsUsed`	integer
`AcquiredLicenses`	array [string] Allowed values: - `Standard` - `Multiseat` - `Unlimited` - `Resale` - `Indemnification`

400InvalidRequest

401AuthorizationTokenRequired

402NotEnoughCreditsForPurchase

404StandardLicenseNotFound

DELETE

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

Boards are where you collect, curate, collaborate on and manage photo and video assets in one place. More information on the Boards FAQ. Use this endpoint to remove an asset from a board.

You'll need an API key and a Resource Owner Grant access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

Request

Path

Name	Data Type	Description
`board_id`	string
`asset_id`	string

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Responses

204No Content

400InvalidParameterValue

401Unauthorized

403InsufficientAccess

404BoardNotFound

PUT

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

Boards are where you collect, curate, collaborate on and manage photo and video assets in one place. More information on the Boards FAQ. Use this endpoint to add an asset to a board.

You'll need an API key and a Resource Owner Grant access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

Request

Path

Name	Data Type	Description
`board_id`	string
`asset_id`	string

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Responses

201Created

Body

Name	Data Type	Description
`Object`	object

400InvalidParameterValue

401Unauthorized

403AssetNotFound

404BoardNotFound

DELETE

/v3/boards/{board_id}/assets

Boards are where you collect, curate, collaborate on and manage photo and video assets in one place. More information on the Boards FAQ. Use this endpoint to remove a set of assets from a board.

You'll need an API key and a Resource Owner Grant access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

Request

Path

Name	Data Type	Description
`board_id`	string

Query

Name	Data Type	Description
`asset_ids`	array	List the assets to be removed from the board.

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Responses

204No Content

400InvalidParameterValue

401Unauthorized

403InsufficientAccess

404BoardNotFound

PUT

/v3/boards/{board_id}/assets

Boards are where you collect, curate, collaborate on and manage photo and video assets in one place. More information on the Boards FAQ. Use this endpoint to add a set of assets to a board.

You'll need an API key and a Resource Owner Grant access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

Request

Path

Name	Data Type	Description
`board_id`	string

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Body

Name Data Type Description

board_assets array [BoardAsset]

BoardAsset object

Properties

asset_id string

Responses

201Created

Body

Name	Data Type	Description
`AddBoardAssetsResult`	object

Properties

assets_not_added array [string]

assets_added array [BoardAsset]

BoardAsset object

Properties

asset_id string

400InvalidParameterValue

401Unauthorized

403InsufficientAccess

404BoardNotFound

DELETE

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

Boards are where you collect, curate, collaborate on and manage photo and video assets in one place. More information on the Boards FAQ. Use this endpoint to delete a comment from a board.

You'll need an API key and a Resource Owner Grant access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

Request

Path

Name	Data Type	Description
`comment_id`	string
`board_id`	string

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Responses

204CommentDeleted

Body

Name	Data Type	Description
`Object`	object

400InvalidParameterValue

401Unauthorized

403InsufficientAccess

404BoardNotFound

GET

/v3/boards/{board_id}/comments

Boards are where you collect, curate, collaborate on and manage photo and video assets in one place. More information on the Boards FAQ. Use this endpoint to retrieve all comments for a specific board.

You'll need an API key and a Resource Owner Grant access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

Request

Path

Name	Data Type	Description
`board_id`	string

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Responses

200OK

Body

Name	Data Type	Description
`CommentsList`	object

Properties

permissions BoardCommentPermissions

BoardCommentPermissions object

Properties

can_add_comment boolean

comments array [Comment]

Comment object

Properties

text string

permissions CommentPermissions

CommentPermissions object

Properties

can_delete_comment boolean

id string

date_created dateTime

created_by Collaborator

Collaborator object

Properties

`last_name`	string
`first_name`	string

400InvalidParameterValue

401Unauthorized

404BoardNotFound

POST

/v3/boards/{board_id}/comments

Boards are where you collect, curate, collaborate on and manage photo and video assets in one place. More information on the Boards FAQ. Use this endpoint to add a comment to a board.

You'll need an API key and a Resource Owner Grant access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

Request

Path

Name	Data Type	Description
`board_id`	string

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Body

Name	Data Type	Description
`CommentRequest`	object

Properties

text string

Responses

201Created

Body

Name	Data Type	Description
`CommentCreated`	object

Properties

id string

400InvalidParameterValue

401Unauthorized

403InsufficientAccess

404BoardNotFound

DELETE

/v3/boards/{board_id}

Boards are where you collect, curate, collaborate on and manage photo and video assets in one place. More information on the Boards FAQ. Use this endpoint to delete a Board by a specific id.

You'll need an API key and a Resource Owner Grant access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

Request

Path

Name	Data Type	Description
`board_id`	string

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Responses

204No Content

400InvalidParameterValue

401Unauthorized

403InsufficientAccess

404BoardNotFound

GET

/v3/boards/{board_id}

Boards are where you collect, curate, collaborate on and manage photo and video assets in one place. More information on the Boards FAQ. Use this endpoint to retrieve a Board by a specific id.

You'll need an API key and a Resource Owner Grant access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

Request

Path

Name	Data Type	Description
`board_id`	string

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Responses

200OK

Body

Name	Data Type	Description
`BoardDetail`	object

Properties

permissions BoardPermissions

BoardPermissions object

Properties

`can_update_name`	boolean
`can_update_description`	boolean
`can_remove_assets`	boolean
`can_invite_to_board`	boolean
`can_delete_board`	boolean
`can_add_assets`	boolean

name string

links Links

Links object

Properties

`share`	string
`invitation`	string

id string

description string

date_last_updated dateTime

date_created dateTime

comment_count integer

assets array [Asset]

Asset object

Properties

id string

display_sizes array [DisplaySize]

DisplaySize object

Properties

`uri`	string
`name`	string

date_added dateTime

asset_type string

asset_count integer

400InvalidParameterValue

401Unauthorized

404BoardNotFound

PUT

/v3/boards/{board_id}

Boards are where you collect, curate, collaborate on and manage photo and video assets in one place. More information on the Boards FAQ. Use this endpoint to update a Board by a specific id.

You'll need an API key and a Resource Owner Grant access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

NOTE: The input to this endpoint is not sanitized in any way, so it is the responsibility of the client to ensure that it is properly formatted and guards against malicious data (for example cross-site scripting attacks or HTML injection) when accessing the data.

Request

Path

Name	Data Type	Description
`board_id`	string

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Body

Name	Data Type	Description
`BoardInfo`	object

Properties

`name`	string
`description`	string

Responses

204Updated

400InvalidParameterValue

401Unauthorized

403InsufficientAccess

404BoardNotFound

GET

/v3/boards

Boards are where you collect, curate, collaborate on and manage photo and video assets in one place. More information on the Boards FAQ. Use this endpoint to retrieve all Boards available for a user.

You'll need an API key and a Resource Owner Grant access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

Request

Query

Name	Data Type	Description
`sort_order`	string Allowed values: - `date_last_updated_descending` - `date_last_updated_ascending` - `name_ascending` - `name_decending`	Sort the list of boards by last update date or name. Defaults to date_last_updated_descending.
`pageSize`	integer	Request number of boards to return in each page. (default is 30).
`page`	integer	Request results starting at a page number (default is 1).
`board_relationship`	string Allowed values: - `owned` - `invited`	Search for boards the user owns or has been invited to as an editor.

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Responses

200OK

Body

Name	Data Type	Description
`BoardList`	object

Properties

boards array [BoardListBoard]

BoardListBoard object

Properties

name string

id string

hero_asset Asset

Asset object

Properties

`id`	string
`display_sizes`	array [DisplaySize]
`date_added`	dateTime
`asset_type`	string

description string

date_last_updated dateTime

date_created dateTime

board_relationship string

asset_count integer

board_count integer

400InvalidParameterValue

401Unauthorized

POST

/v3/boards

Boards are where you collect, curate, collaborate on and manage photo and video assets in one place. More information on the Boards FAQ. Use this endpoint to create a Board by a specific id.

You'll need an API key and a Resource Owner Grant access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

NOTE: The input to this endpoint is not sanitized in any way, so it is the responsibility of the client to ensure that it is properly formatted and guards against malicious data (for example cross-site scripting attacks or HTML injection) when accessing the data.

Request

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Body

Name	Data Type	Description
`BoardInfo`	object

Properties

`name`	string
`description`	string

Responses

201Created

Body

Name	Data Type	Description
`BoardCreated`	object

Properties

id string

400InvalidParameterValue

401Unauthorized

GET

/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. Please see our Getting Started page for more information on how to sign up for an API key.

Request

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsCollectionsCollectionsList`	object

Properties

collections array [GettyImagesModelsCollectionsCollection]

GettyImagesModelsCollectionsCollection object

Properties

`product_types`	array [string]
`name`	string
`license_model`	string
`id`	integer
`code`	string
`asset_family`	string

401Unauthorized

GET

/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. Please see our Getting Started page for more information on how to sign up for an API key.

Request

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.
`Accept-Language`	string	Provide a header to specify the language of result values.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsCountriesCountriesList`	object

Properties

countries array [GettyImagesModelsCountriesCountry]

GettyImagesModelsCountriesCountry object

Properties

`name`	string
`iso_alpha_3`	string
`iso_alpha_2`	string

401Unauthorized

POST

/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. Please see our Getting Started page for more information on how to sign up for an API key.

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:

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

Request

Path

Name	Data Type	Description
`id`	string	Id of image to download.

Query

Name	Data Type	Description
`use_team_credits`	boolean	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.
`product_type`	string Allowed values: - `easyaccess` - `editorialsubscription` - `imagepack` - `premiumaccess` - `royaltyfreesubscription`	Product type.
`product_id`	integer	Identifier of the instance for the selected product offering type.
`height`	string	Specifies the pixel height of the particular image to download. Available heights can be found in the images/{ids} response for the specific image. If left blank, it will return the largest available size.
`file_type`	string Allowed values: - `eps` - `jpg`	File Type expressed with three character file extension.
`auto_download`	boolean	Specifies whether to auto-download the image. If true is specified, a 303 SeeOther status is returned with a Location header set to the location of the image. If false is specified, the download URI will be returned in the response message.

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Body

Name	Data Type	Description
`GettyImagesModelsDownloadsPremiumAccessDownloadData`	object

Properties

`project_code`	string
`download_notes`	string

Responses

200OK

Body

Name	Data Type	Description
`SystemObject`	object

303See Other

400MissingRequiredQueryParameters

401AuthorizationTokenRequired

404ImageNotFound

POST

/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. Please see our Getting Started page for more information on how to sign up for an API key.

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:

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

Request

Path

Name	Data Type	Description
`id`	string	Id of video to download.

Query

Name	Data Type	Description
`use_team_credits`	boolean	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.
`size`	string	Specifies the size to be downloaded.
`product_id`	integer	Identifier of the instance for the selected product offering type.
`auto_download`	boolean	Specifies whether to auto-download the video. If true is specified, a 303 SeeOther status is returned with a Location header set to the location of the video. If false is specified, the download URI will be returned in the response message.

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Body

Name	Data Type	Description
`GettyImagesModelsDownloadsPremiumAccessDownloadData`	object

Properties

`project_code`	string
`download_notes`	string

Responses

200OK

Body

Name	Data Type	Description
`SystemObject`	object

303See Other

400MissingRequiredQueryParameters

401AuthorizationTokenRequired

404VideoNotFound

GET

/v3/downloads

Returns information about a customer's previously downloaded assets.

You'll need an API key and access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

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.

Request

Query

Name	Data Type	Description
`product_type`	string Allowed values: - `easyaccess` - `editorialsubscription` - `imagepack` - `premiumaccess` - `royaltyfreesubscription`	Specifies product type to be included in the previous download results. To get previous iStockPhoto credit downloads, credit_pack must be selected.
`page_size`	integer	Specifies page size. Default is 30, maximum page_size is 100.
`page`	integer	Identifies page to return. Default is 1.
`date_to`	dateTime	If specified, select assets downloaded on or before this date. Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD). Any hour, minute, second values in the request are not used at this time. Date/times in the response are UTC. Default is current date.
`date_from`	dateTime	If specified, select assets downloaded on or before this date. Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD). Any hour, minute, second values in the request are not used at this time. Date/times in the response are UTC. Default is 30 days prior to date_to.
`company_downloads`	boolean	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.

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsDownloadsGetDownloadsResponse`	object

Properties

result_count integer

downloads array [GettyImagesModelsDownloadsGetDownloadsResponseDownload]

GettyImagesModelsDownloadsGetDownloadsResponseDownload object

Properties

user GettyImagesModelsDownloadsUser

GettyImagesModelsDownloadsUser object

Properties

`username`	string
`middle_name`	string
`last_name`	string
`first_name`	string

thumb_uri string

size_name string

product_type string

id string

download_details GettyImagesModelsDownloadsGetDownloadsResponseDownloadDetails

GettyImagesModelsDownloadsGetDownloadsResponseDownloadDetails object

Properties

`project_code`	string
`download_notes`	string

date_downloaded dateTime

asset_type string

agreement_name string

400Bad request

401AuthorizationTokenRequired

403Forbidden

GET

/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. Please see our Getting Started page for more information on how to sign up for an API key.

Request

Path

Name	Data Type	Description
`id`	integer	An event id.

Query

Name	Data Type	Description
`fields`	array	A comma separated list of fields to return in the response.

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.
`Accept-Language`	string	Provide a header to specify the language of result values.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsEventsEvent`	object

Properties

start_date dateTime

name string

location GettyImagesModelsLocationEvent

GettyImagesModelsLocationEvent object

Properties

`venue`	string
`state_province`	string
`country`	string
`city`	string

image_count integer

id integer

hero_image GettyImagesModelsHeroImage

GettyImagesModelsHeroImage object

Properties

id string

display_sizes array [GettyImagesModelsHeroImageDisplaySize]

GettyImagesModelsHeroImageDisplaySize object

Properties

`uri`	string
`name`	string
`is_watermarked`	boolean

editorial_segments array [string]

child_event_count integer

400InvalidParameterValue

401Unauthorized

404EventNotFound

GET

/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. Please see our Getting Started page for more information on how to sign up for an API key.

Request

Query

Name	Data Type	Description
`ids`	array	A comma separated list of event ids.
`fields`	array	A comma separated list of fields to return in the response.

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.
`Accept-Language`	string	Provide a header to specify the language of result values.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsEventsEventsResult`	object

Properties

events_not_found array [integer]

events array [GettyImagesModelsEventsEvent]

GettyImagesModelsEventsEvent object

Properties

start_date dateTime

name string

location GettyImagesModelsLocationEvent

GettyImagesModelsLocationEvent object

Properties

`venue`	string
`state_province`	string
`country`	string
`city`	string

image_count integer

id integer

hero_image GettyImagesModelsHeroImage

GettyImagesModelsHeroImage object

Properties

`id`	string
`display_sizes`	array [GettyImagesModelsHeroImageDisplaySize]

editorial_segments array [string]

child_event_count integer

400InvalidParameterValue

401Unauthorized

404EventNotFound

GET

/v3/images/{id}/similar

This endpoint will search our asset database for images similar to the specified asset id. Due to a wide variety of available image resolutions, the images are grouped into a handful of size categories for simplicity.

You'll need an API key and access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

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.

{
    "images":
    [
        "display_sizes": 
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ]
    ]
}

Request

Path

Name	Data Type	Description
`id`	string	Identifies an existing image

Query

Name	Data Type	Description
`page_size`	integer	Specifies page size. Default is 30, maximum page_size is 100.
`page`	integer	Identifies page to return. Default is 1.
`fields`	array	Specifies fields to return. Defaults to 'summary_set'.

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.
`Accept-Language`	string	Provide a header to specify the language of result values.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsSearchSearchResultsGettyImagesModelsSearchImageSearchItem`	object

Properties

result_count integer

images array [GettyImagesModelsSearchImageSearchItem]

GettyImagesModelsSearchImageSearchItem object

Properties

uri_oembed string

title string

referral_destinations array [GettyImagesModelsReferralDestination]

GettyImagesModelsReferralDestination object

Properties

`uri`	string
`site_name`	string

quality_rank integer

product_types array [string]

people array [string]

orientation string

max_dimensions GettyImagesModelsMaxDimensions

GettyImagesModelsMaxDimensions object

Properties

`width`	integer
`height`	integer

license_model string

largest_downloads array [GettyImagesModelsDownload]

GettyImagesModelsDownload object

Properties

`uri`	string
`product_type`	string
`product_id`	string
`agreement_name`	string

keywords array [GettyImagesModelsKeyword]

GettyImagesModelsKeyword object

Properties

`type`	string
`text`	string
`relevance`	integer
`keyword_id`	string
`entity_uris`	array [string]
`entity_types`	array [string]

istock_licenses array [GettyImagesModelsIStockLicense]

GettyImagesModelsIStockLicense object

Properties

`license_type`	string Allowed values: - `Standard` - `Multiseat` - `Unlimited` - `Resale` - `Indemnification`
`credits`	integer

id string

graphical_style string

event_ids array [integer]

editorial_segments array [string]

display_sizes array [GettyImagesModelsSearchImageSearchItemDisplaySize]

GettyImagesModelsSearchImageSearchItemDisplaySize object

Properties

`uri`	string
`name`	string
`is_watermarked`	boolean

date_created dateTime

date_camera_shot dateTime

copyright string

color_type string

collection_name string

collection_id integer

collection_code string

caption string

call_for_image boolean

asset_family string

artist string

alternative_ids object

allowed_use GettyImagesModelsAllowedUse

GettyImagesModelsAllowedUse object

Properties

`usage_restrictions`	array [string]	Indicates asset usage restriction, if any
`release_info`	string	Indicates release status
`how_can_i_use_it`	string	Indicates how the asset can be used

400InvalidParameterValue

401AuthorizationTokenRequired

403UnauthorizedDisplaySize

404ImageNotFound

500InvalidIStockCollection

GET

/v3/images/{id}

This endpoint returns the detailed image metadata for a specified image. Due to a wide variety of available image resolutions, the images are grouped into a handful of size categories for simplicity.

You'll need an API key and access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

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.

{
    "images":
    [
        "display_sizes": 
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ]
    ]
}

Request Usage Considerations

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

Request

Path

Name	Data Type	Description
`id`	string	An image id. For more than one image please use the /v3/images endpoint.

Query

Name	Data Type	Description
`fields`	array	Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field are estimates.

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.
`Accept-Language`	string	Provide a header to specify the language of result values.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsImagesImagesDetail`	object

Properties

images_not_found array [string]

images array [GettyImagesModelsImagesImageDetail]

GettyImagesModelsImagesImageDetail object

Properties

uri_oembed string

title string

state_province string

referral_destinations array [GettyImagesModelsReferralDestination]

GettyImagesModelsReferralDestination object

Properties

`uri`	string
`site_name`	string

quality_rank integer

product_types array [string]

people array [string]

orientation string

max_dimensions GettyImagesModelsMaxDimensions

GettyImagesModelsMaxDimensions object

Properties

`width`	integer
`height`	integer

links array [GettyImagesModelsImagesLink]

GettyImagesModelsImagesLink object

Properties

`uri`	string
`rel`	string

license_model string

largest_downloads array [GettyImagesModelsImagesImageDownloadSize]

GettyImagesModelsImagesImageDownloadSize object

Properties

`width`	integer
`name`	string Allowed values: - `x_small` - `small` - `medium` - `large` - `x_large` - `xx_large` - `vector`
`media_type`	string
`height`	integer
`downloads`	array [GettyImagesModelsImagesImageDownloadAuthorization]
`bytes`	integer

keywords array [GettyImagesModelsKeyword]

GettyImagesModelsKeyword object

Properties

`type`	string
`text`	string
`relevance`	integer
`keyword_id`	string
`entity_uris`	array [string]
`entity_types`	array [string]

istock_licenses array [GettyImagesModelsIStockLicense]

GettyImagesModelsIStockLicense object

Properties

`license_type`	string Allowed values: - `Standard` - `Multiseat` - `Unlimited` - `Resale` - `Indemnification`
`credits`	integer

id string

graphical_style string

event_ids array [integer]

editorial_source GettyImagesModelsImagesEditorialSource

GettyImagesModelsImagesEditorialSource object

Properties

`name`	string
`id`	integer

editorial_segments array [string]

download_sizes array [GettyImagesModelsImagesImageDownloadSize]

GettyImagesModelsImagesImageDownloadSize object

Properties

`width`	integer
`name`	string Allowed values: - `x_small` - `small` - `medium` - `large` - `x_large` - `xx_large` - `vector`
`media_type`	string
`height`	integer
`downloads`	array [GettyImagesModelsImagesImageDownloadAuthorization]
`bytes`	integer

display_sizes array [GettyImagesModelsImagesImageDetailDisplaySize]

GettyImagesModelsImagesImageDetailDisplaySize object

Properties

`width`	integer	Indicates the width in pixels
`uri`	string	Identifies the URI for the image
`name`	string	Identifies the name of the display size
`is_watermarked`	boolean	Indicates whether the image is watermarked.
`height`	integer	Indicates the height in pixels

date_submitted dateTime

date_created dateTime

date_camera_shot dateTime

credit_line string

country string

copyright string

color_type string

collection_name string

collection_id integer

collection_code string

city string

caption string

call_for_image boolean

asset_family string

artist_title string

artist string

alternative_ids object

allowed_use GettyImagesModelsAllowedUse

GettyImagesModelsAllowedUse object

Properties

`usage_restrictions`	array [string]	Indicates asset usage restriction, if any
`release_info`	string	Indicates release status
`how_can_i_use_it`	string	Indicates how the asset can be used

400InvalidParameterValue

401AuthorizationTokenRequired

403UnauthorizedDisplaySize

404ImageNotFound

500InvalidIStockCollection

GET

/v3/images

This endpoint returns the detailed image metadata for all specified images. Due to a wide variety of available image resolutions, the images are grouped into a handful of size categories for simplicity.

You'll need an API key and access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

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.

{
    "images":
    [
        "display_sizes": 
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ]
    ]
}

Request Usage Considerations

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

Request

Query

Name	Data Type	Description
`fields`	array	Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field are estimates.
`ids`	array	Specifies one or more image ids to return. Use comma delimiter when requesting multiple ids.

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.
`Accept-Language`	string	Provide a header to specify the language of result values.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsImagesImagesDetail`	object

Properties

images_not_found array [string]

images array [GettyImagesModelsImagesImageDetail]

GettyImagesModelsImagesImageDetail object

Properties

uri_oembed string

title string

state_province string

referral_destinations array [GettyImagesModelsReferralDestination]

GettyImagesModelsReferralDestination object

Properties

`uri`	string
`site_name`	string

quality_rank integer

product_types array [string]

people array [string]

orientation string

max_dimensions GettyImagesModelsMaxDimensions

GettyImagesModelsMaxDimensions object

Properties

`width`	integer
`height`	integer

links array [GettyImagesModelsImagesLink]

GettyImagesModelsImagesLink object

Properties

`uri`	string
`rel`	string

license_model string

largest_downloads array [GettyImagesModelsImagesImageDownloadSize]

GettyImagesModelsImagesImageDownloadSize object

Properties

`width`	integer
`name`	string Allowed values: - `x_small` - `small` - `medium` - `large` - `x_large` - `xx_large` - `vector`
`media_type`	string
`height`	integer
`downloads`	array [GettyImagesModelsImagesImageDownloadAuthorization]
`bytes`	integer

keywords array [GettyImagesModelsKeyword]

GettyImagesModelsKeyword object

Properties

`type`	string
`text`	string
`relevance`	integer
`keyword_id`	string
`entity_uris`	array [string]
`entity_types`	array [string]

istock_licenses array [GettyImagesModelsIStockLicense]

GettyImagesModelsIStockLicense object

Properties

`license_type`	string Allowed values: - `Standard` - `Multiseat` - `Unlimited` - `Resale` - `Indemnification`
`credits`	integer

id string

graphical_style string

event_ids array [integer]

editorial_source GettyImagesModelsImagesEditorialSource

GettyImagesModelsImagesEditorialSource object

Properties

`name`	string
`id`	integer

editorial_segments array [string]

download_sizes array [GettyImagesModelsImagesImageDownloadSize]

GettyImagesModelsImagesImageDownloadSize object

Properties

`width`	integer
`name`	string Allowed values: - `x_small` - `small` - `medium` - `large` - `x_large` - `xx_large` - `vector`
`media_type`	string
`height`	integer
`downloads`	array [GettyImagesModelsImagesImageDownloadAuthorization]
`bytes`	integer

display_sizes array [GettyImagesModelsImagesImageDetailDisplaySize]

GettyImagesModelsImagesImageDetailDisplaySize object

Properties

`width`	integer	Indicates the width in pixels
`uri`	string	Identifies the URI for the image
`name`	string	Identifies the name of the display size
`is_watermarked`	boolean	Indicates whether the image is watermarked.
`height`	integer	Indicates the height in pixels

date_submitted dateTime

date_created dateTime

date_camera_shot dateTime

credit_line string

country string

copyright string

color_type string

collection_name string

collection_id integer

collection_code string

city string

caption string

call_for_image boolean

asset_family string

artist_title string

artist string

alternative_ids object

allowed_use GettyImagesModelsAllowedUse

GettyImagesModelsAllowedUse object

Properties

`usage_restrictions`	array [string]	Indicates asset usage restriction, if any
`release_info`	string	Indicates release status
`how_can_i_use_it`	string	Indicates how the asset can be used

400InvalidParameterValue

401AuthorizationTokenRequired

403UnauthorizedDisplaySize

404ImageNotFound

500InvalidIStockCollection

GET

/v3/orders/{id}

This endpoint returns detailed order metadata for a specified order. Use of this endpoint requires configuration changes to your API key. Please contact developersupport@gettyimages.com to learn more.

You'll need an API key and access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

Request

Path

Name	Data Type	Description
`id`	integer	An order id.

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsOrdersOrderDetail`	object

Properties

order_date dateTime

notes GettyImagesModelsOrdersOrderNotes

GettyImagesModelsOrdersOrderNotes object

Properties

`purchase_order_number`	string
`project_title`	string
`ordered_by`	string
`licensee_name`	string

id string

end_client string

assets array [GettyImagesModelsOrdersAssetIdFromOrder]

GettyImagesModelsOrdersAssetIdFromOrder object

Properties

id string

401Unauthorized

403NoAccessToOrderMetadata

404OrderNotFound

GET

/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. Please see our Getting Started page for more information on how to sign up for an API key.

Request

Query

Name	Data Type	Description
`fields`	array	Comma separated list of fields. Allows product download requirements to be returned.

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsProductsProductsResult`	object

Properties

products array [GettyImagesModelsProductsProduct]

GettyImagesModelsProductsProduct object

Properties

type string
Allowed values:
- easyaccess
- editorialsubscription
- imagepack
- premiumaccess
- royaltyfreesubscription
- creditpack

team_credits integer

status string
Allowed values:
- active
- inactive

overage GettyImagesModelsProductsOverageDetails

GettyImagesModelsProductsOverageDetails object

Properties

`remaining`	integer
`overages_reached`	boolean
`limit`	integer
`count`	integer

name string

imagepack_resolution string

id integer

expiration_utc_date dateTime

downloads_remaining integer

download_requirements GettyImagesModelsProductsDownloadRequirements

GettyImagesModelsProductsDownloadRequirements object

Properties

`project_codes`	array [string]
`is_project_code_required`	boolean
`is_note_required`	boolean

download_limit_reset_utc_date dateTime

download_limit_duration string

download_limit integer

credits_remaining integer

application_website string

agreement_name string

400InvalidParameterValue

401Unauthorized

500CreditPack

GET

/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 developersupport@gettyimages.com to learn more.

You'll need an API key and access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

Request

Query

Name	Data Type	Description
`page_size`	integer	Specifies page size. Default is 75, maximum page_size is 100.
`page`	integer	Identifies page to return. Default is 1.
`date_to`	dateTime	If specified, retrieves previous purchases on or before this date. Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD).
`date_from`	dateTime	If specified, retrieves previous purchases on or after this date. Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD).

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsPurchasesPreviousAssetPurchases`	object

Properties

result_count integer

previous_purchases array [GettyImagesModelsPurchasesPreviousAssetPurchase]

GettyImagesModelsPurchasesPreviousAssetPurchase object

Properties

`thumb_uri`	string
`size_name`	string
`order_id`	string
`license_model`	string
`file_size_in_bytes`	string
`download_uri`	string
`date_purchased`	dateTime
`asset_type`	string
`asset_id`	string

400PageNumberLessThanOne

401Unauthorized

GET

/v3/purchased-images

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

You'll need an API key and access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

Request

Query

Name	Data Type	Description
`page_size`	integer	Specifies page size. Default is 75, maximum page_size is 100.
`page`	integer	Identifies page to return. Default is 1.
`date_to`	dateTime	If specified, retrieves previous purchases on or before this date. Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD).
`date_from`	dateTime	If specified, retrieves previous purchases on or after this date. Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD).

Header

Name	Data Type	Description
`Accept-Language`	string	Provide a header to specify the language of result values.
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsPurchasesPreviousPurchases`	object

Properties

result_count integer

previous_purchases array [GettyImagesModelsPurchasesPreviousPurchase]

GettyImagesModelsPurchasesPreviousPurchase object

Properties

`thumb_uri`	string
`order_id`	string
`license_model`	string
`image_id`	string
`date_purchased`	dateTime

400PageNumberLessThanOne

401Unauthorized

GET

/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 an event, are assigned the same EventID. EventIDs are part of the meta-data 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 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. Please see our Getting Started page for more information on how to sign up for an API key.

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.

Request

Query

Name	Data Type	Description
`phrase`	string	Filters to events related to this phrase
`page_size`	integer	Request number of images to return in each page.
`page`	integer	Request results starting at a page number (default is 1, maximum is 50).
`fields`	array	Specifies fields to return. Default set is 'id','name','start_date'.
`editorial_segment`	string Allowed values: - `archival` - `entertainment` - `news` - `publicity` - `royalty` - `sport`	Filters to events with a matching editorial segment.
`date_to`	dateTime	Filters to events that start on or before this date. Use ISO 8601 format (e.g., 1999-12-31).
`date_from`	dateTime	Filters to events that start on or after this date. Use ISO 8601 format (e.g., 1999-12-31).

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.
`Accept-Language`	string	Provide a header to specify the language of result values.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsSearchEventsSearchResult`	object

Properties

result_count integer

events array [GettyImagesModelsEventsEvent]

GettyImagesModelsEventsEvent object

Properties

start_date dateTime

name string

location GettyImagesModelsLocationEvent

GettyImagesModelsLocationEvent object

Properties

`venue`	string
`state_province`	string
`country`	string
`city`	string

image_count integer

id integer

hero_image GettyImagesModelsHeroImage

GettyImagesModelsHeroImage object

Properties

`id`	string
`display_sizes`	array [GettyImagesModelsHeroImageDisplaySize]

editorial_segments array [string]

child_event_count integer

400InvalidParameterValue

401AuthorizationTokenRequired

403UnauthorizedDisplaySize

GET

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

Allows searching for similar creative images by passing the URL to an existing image.

Before calling the search by image endpoint, an image must be uploaded to a specific AWS S3 bucket. The bucket name is search-by-image.s3.amazonaws.com. For example, using cURL:

curl -i -X PUT https://search-by-image.s3.amazonaws.com/my-test-image.jpg -H "Content-Type: image/jpeg" --data-binary "@testimage.jpg"

Uploads can be overwritten if the names are the same, so using a prefix like the API Key, application name or company name would help keep that from happening.

Once the image has been uploaded, use the full URL in the image_url parameter, e.g. image_url=https://search-by-image.s3.amazonaws.com/my-test-image.jpg.

Subsequent searches for the same image can be executed using the image_fingerprint that is returned by the inital search.

Request

Query

Name	Data Type	Description
`product_types`	array	Filter images to those from one of your product types. Allowed values are easyaccess, imagepack, premiumaccess and royaltyfreesubscription. If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. For example, some users may have more than one premiumaccess product, so the product_types value would be premiumaccess:1234. Product ID can be obtained from the GET /products response.
`page_size`	integer	Request number of images to return in each page.
`page`	integer	Request results starting at a page number (default is 1).
`include_facets`	boolean	Specifies whether or not to include facets in the result set. Default is "false".
`image_url`	string	Specifies the location of the image to use in the search.
`image_fingerprint`	string	Specifies the fingerprint of the image to use in the search.
`fields`	array	Specifies fields to return. Defaults to 'summary_set'.
`facet_max_count`	integer	Specifies the maximum number of facets to return per type. Default is 300.
`facet_fields`	array	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.

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.
`Accept-Language`	string	Provide a header to specify the language of result values.

Responses

200OK

Body

Name	Data Type	Description
`SystemObject`	object

400InvalidParameterValue

401AuthorizationTokenRequired

403UnauthorizedDisplaySize

500InvalidIStockCollection

GET

/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. Please see our Getting Started page for more information on how to sign up for an API key.

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

{
    "images": 
    [
        "display_sizes": 
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ]
    ]
}

Request

Query

Name	Data Type	Description
`sort_order`	string Allowed values: - `best_match` - `most_popular` - `newest` - `random`	Select sort order of results.
`product_types`	array	Filter images to those from one of your product types. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription. If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. For example, some users may have more than one premiumaccess product, so the product_types value would be premiumaccess:1234. Product ID can be obtained from the GET /products response.
`phrase`	string	Search images using a search phrase.
`page_size`	integer	Request number of images to return in each page.
`page`	integer	Request results starting at a page number (default is 1).
`orientations`	array	Return only images with selected aspect ratios.
`number_of_people`	array	Filter based on the number of people in the image.
`minimum_size`	string Allowed values: - `x_small` - `small` - `medium` - `large` - `x_large` - `xx_large` - `vector`	Filter based on minimum size requested.
`license_models`	array	Specifies the image licensing model(s).
`keyword_ids`	array	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.
`include_facets`	boolean	Specifies whether or not to include facets in the result set. Default is "false".
`graphical_styles_filter_type`	string Allowed values: - `include` - `exclude`	Provides searching based on specified graphical style(s).
`graphical_styles`	array	Filter based on graphical style of the image.
`file_types`	array	Return only images having a specific file type.
`fields`	array	Specifies fields to return. Defaults to 'summary_set'.
`facet_max_count`	integer	Specifies the maximum number of facets to return per type. Default is 300.
`facet_fields`	array	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.
`exclude_nudity`	boolean	Excludes images containing nudity. The default is false.
`exclude_editorial_use_only`	boolean	Exclude images that are only available for editorial (non-commercial) use. Default value is false.
`ethnicity`	array	Filter search results based on the ethnicity of individuals in an image.
`embed_content_only`	boolean	Restrict search results to embeddable images. The default is false.
`compositions`	array	Filter based on image composition.
`color`	string	Filter based on predominant color in an image. Use 6 character hexidecimal format (e.g., #002244).
`collections_filter_type`	string Allowed values: - `include` - `exclude`	Use to include or exclude collections from search.
`collection_codes`	array	Filter by collection codes (comma-separated list). Include or exclude based on collections_filter_type.
`artists`	string	Search for images by specific artists (free-text, comma-separated list of artists).
`age_of_people`	array	Filter based on the age of individuals in an image.

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.
`Accept-Language`	string	Provide a header to specify the language of result values.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsSearchCreativeImageSearchResults`	object

Properties

result_count integer

images array [GettyImagesModelsSearchImageSearchItemCreative]

GettyImagesModelsSearchImageSearchItemCreative object

Properties

uri_oembed string

title string

referral_destinations array [GettyImagesModelsReferralDestination]

GettyImagesModelsReferralDestination object

Properties

`uri`	string
`site_name`	string

quality_rank integer

orientation string

max_dimensions GettyImagesModelsMaxDimensions

GettyImagesModelsMaxDimensions object

Properties

`width`	integer
`height`	integer

license_model string

largest_downloads array [GettyImagesModelsDownload]

GettyImagesModelsDownload object

Properties

`uri`	string
`product_type`	string
`product_id`	string
`agreement_name`	string

keywords array [GettyImagesModelsKeyword]

GettyImagesModelsKeyword object

Properties

`type`	string
`text`	string
`relevance`	integer
`keyword_id`	string
`entity_uris`	array [string]
`entity_types`	array [string]

id string

graphical_style string

display_sizes array [GettyImagesModelsSearchImageSearchItemDisplaySize]

GettyImagesModelsSearchImageSearchItemDisplaySize object

Properties

`uri`	string
`name`	string
`is_watermarked`	boolean

date_created dateTime

date_camera_shot dateTime

copyright string

color_type string

collection_name string

collection_id integer

collection_code string

caption string

call_for_image boolean

asset_family string

artist string

alternative_ids object

allowed_use GettyImagesModelsAllowedUse

GettyImagesModelsAllowedUse object

Properties

`usage_restrictions`	array [string]	Indicates asset usage restriction, if any
`release_info`	string	Indicates release status
`how_can_i_use_it`	string	Indicates how the asset can be used

400InvalidParameterValue

401AuthorizationTokenRequired

403UnauthorizedDisplaySize

500InvalidIStockCollection

GET

/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. Please see our Getting Started page for more information on how to sign up for an API key.

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

{
    "images": 
    [
        "display_sizes": 
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ]
    ]
}

Request Usage Considerations

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

Request

Query

Name	Data Type	Description
`specific_people`	array	Return only images associated with specific people (using a comma-delimited list).
`sort_order`	string Allowed values: - `best_match` - `most_popular` - `newest` - `oldest` - `random`	Select sort order of results.
`product_types`	array	Filter images to those from one of your product types. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription. If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. For example, some users may have more than one premiumaccess product, so the product_types value would be premiumaccess:1234. Product ID can be obtained from the GET /products response.
`phrase`	string	Search images using a search phrase.
`page_size`	integer	Request number of images to return in each page.
`page`	integer	Request results starting at a page number (default is 1).
`orientations`	array	Return only images with selected aspect ratios.
`number_of_people`	array	Filter based on the number of people in the image.
`minimum_size`	string Allowed values: - `x_small` - `small` - `medium` - `large` - `x_large` - `xx_large` - `vector`	Filter based on minimum size requested.
`minimum_quality_rank`	integer	Filter search results based on minimum quality ranking. Possible values 1, 2, 3 with 1 being best.
`keyword_ids`	array	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.
`include_facets`	boolean	Specifies whether or not to include facets in the result set. Default is "false".
`graphical_styles_filter_type`	string Allowed values: - `include` - `exclude`	Provides searching based on specified graphical style(s).
`graphical_styles`	array	Filter based on graphical style of the image.
`file_types`	array	Return only images having a specific file type.
`fields`	array	Specifies fields to return. Defaults to 'summary_set'.
`facet_max_count`	integer	Specifies the maximum number of facets to return per type. Default is 300.
`facet_fields`	array	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.
`event_ids`	array	Filter based on specific events
`ethnicity`	array	Filter search results based on the ethnicity of individuals in an image.
`entity_uris`	array	specify linked data entity uri.
`embed_content_only`	boolean	Restrict search results to embeddable images. The default is false.
`editorial_segments`	array	Return only events with a matching editorial segment.
`date_to`	dateTime	Return only images that are created on or before this date. Use ISO 8601 format (e.g., 1999-12-31).
`date_from`	dateTime	Return only images that are created on or after this date. Use ISO 8601 format (e.g., 1999-12-31).
`compositions`	array	Filter based on image composition.
`collections_filter_type`	string Allowed values: - `include` - `exclude`	Use to include or exclude collections from search.
`collection_codes`	array	Filter by collections (comma-separated list of collection codes). Include or exclude based on collections_filter_type.
`artists`	string	Search for images by specific artists (free-text, comma-separated list of artists).
`age_of_people`	array	Filter based on the age of individuals in an image.

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.
`Accept-Language`	string	Provide a header to specify the language of result values.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsSearchEditorialImageSearchResults`	object

Properties

result_count integer

images array [GettyImagesModelsSearchImageSearchItemEditorial]

GettyImagesModelsSearchImageSearchItemEditorial object

Properties

uri_oembed string

title string

referral_destinations array [GettyImagesModelsReferralDestination]

GettyImagesModelsReferralDestination object

Properties

`uri`	string
`site_name`	string

quality_rank integer

product_types array [string]

people array [string]

orientation string

max_dimensions GettyImagesModelsMaxDimensions

GettyImagesModelsMaxDimensions object

Properties

`width`	integer
`height`	integer

license_model string

largest_downloads array [GettyImagesModelsDownload]

GettyImagesModelsDownload object

Properties

`uri`	string
`product_type`	string
`product_id`	string
`agreement_name`	string

keywords array [GettyImagesModelsKeyword]

GettyImagesModelsKeyword object

Properties

`type`	string
`text`	string
`relevance`	integer
`keyword_id`	string
`entity_uris`	array [string]
`entity_types`	array [string]

id string

graphical_style string

event_ids array [integer]

editorial_source GettyImagesModelsSearchEditorialSource

GettyImagesModelsSearchEditorialSource object

Properties

id integer

editorial_segments array [string]

display_sizes array [GettyImagesModelsSearchImageSearchItemDisplaySize]

GettyImagesModelsSearchImageSearchItemDisplaySize object

Properties

`uri`	string
`name`	string
`is_watermarked`	boolean

date_created dateTime

date_camera_shot dateTime

copyright string

color_type string

collection_name string

collection_id integer

collection_code string

caption string

call_for_image boolean

asset_family string

artist string

alternative_ids object

allowed_use GettyImagesModelsAllowedUse

GettyImagesModelsAllowedUse object

Properties

`usage_restrictions`	array [string]	Indicates asset usage restriction, if any
`release_info`	string	Indicates release status
`how_can_i_use_it`	string	Indicates how the asset can be used

400InvalidParameterValue

401AuthorizationTokenRequired

403UnauthorizedDisplaySize

GET

/v3/search/images

Use this endpoint to search over a blend of our contemporary stock photos, illustrations, archival images, editorial photos, illustrations and archival images.

You'll need an API key and access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

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

{
    "images": 
    [
        "display_sizes": 
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ]
    ]
}

Request Usage Considerations

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

Request

Query

Name	Data Type	Description
`specific_people`	array	Return only images associated with specific people (using a comma-delimited list).
`sort_order`	string Allowed values: - `best_match` - `most_popular` - `newest` - `random`	Select sort order of results.
`product_types`	array	Filter images to those from one of your product types. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription. If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. For example, some users may have more than one premiumaccess product, so the product_types value would be premiumaccess:1234. Product ID can be obtained from the GET /products response.
`phrase`	string	Search images using a search phrase.
`page_size`	integer	Request number of images to return in each page.
`page`	integer	Request results starting at a page number (default is 1).
`orientations`	array	Return only images with selected aspect ratios.
`number_of_people`	array	Filter based on the number of people in the image.
`minimum_size`	string Allowed values: - `x_small` - `small` - `medium` - `large` - `x_large` - `xx_large` - `vector`	Filter based on minimum size requested.
`license_models`	array	Specifies the image licensing model(s).
`keyword_ids`	array	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.
`graphical_styles_filter_type`	string Allowed values: - `include` - `exclude`	Provides searching based on specified graphical style(s).
`graphical_styles`	array	Filter based on graphical style of the image.
`file_types`	array	Return only images having a specific file type.
`fields`	array	Specifies fields to return. Defaults to 'summary_set'.
`exclude_nudity`	boolean	Excludes images containing nudity. The default is false.
`event_ids`	array	Filter based on specific events
`ethnicity`	array	Filter search results based on the ethnicity of individuals in an image.
`embed_content_only`	boolean	Restrict search results to embeddable images. The default is false.
`compositions`	array	Filter based on image composition.
`color`	string	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.
`collections_filter_type`	string Allowed values: - `include` - `exclude`	Provides searching based on specified collection(s).
`collection_codes`	array	Filter by collection codes (comma-separated list). Include or exclude based on collections_filter_type.
`artists`	string	Search for images by specific artists (free-text, comma-separated list of artists).
`age_of_people`	array	Filter based on the age of individuals in an image.

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.
`Accept-Language`	string	Provide a header to specify the language of result values.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsSearchSearchResultsGettyImagesModelsSearchImageSearchItem`	object

Properties

result_count integer

images array [GettyImagesModelsSearchImageSearchItem]

GettyImagesModelsSearchImageSearchItem object

Properties

uri_oembed string

title string

referral_destinations array [GettyImagesModelsReferralDestination]

GettyImagesModelsReferralDestination object

Properties

`uri`	string
`site_name`	string

quality_rank integer

product_types array [string]

people array [string]

orientation string

max_dimensions GettyImagesModelsMaxDimensions

GettyImagesModelsMaxDimensions object

Properties

`width`	integer
`height`	integer

license_model string

largest_downloads array [GettyImagesModelsDownload]

GettyImagesModelsDownload object

Properties

`uri`	string
`product_type`	string
`product_id`	string
`agreement_name`	string

keywords array [GettyImagesModelsKeyword]

GettyImagesModelsKeyword object

Properties

`type`	string
`text`	string
`relevance`	integer
`keyword_id`	string
`entity_uris`	array [string]
`entity_types`	array [string]

istock_licenses array [GettyImagesModelsIStockLicense]

GettyImagesModelsIStockLicense object

Properties

`license_type`	string Allowed values: - `Standard` - `Multiseat` - `Unlimited` - `Resale` - `Indemnification`
`credits`	integer

id string

graphical_style string

event_ids array [integer]

editorial_segments array [string]

display_sizes array [GettyImagesModelsSearchImageSearchItemDisplaySize]

GettyImagesModelsSearchImageSearchItemDisplaySize object

Properties

`uri`	string
`name`	string
`is_watermarked`	boolean

date_created dateTime

date_camera_shot dateTime

copyright string

color_type string

collection_name string

collection_id integer

collection_code string

caption string

call_for_image boolean

asset_family string

artist string

alternative_ids object

allowed_use GettyImagesModelsAllowedUse

GettyImagesModelsAllowedUse object

Properties

`usage_restrictions`	array [string]	Indicates asset usage restriction, if any
`release_info`	string	Indicates release status
`how_can_i_use_it`	string	Indicates how the asset can be used

400InvalidParameterValue

401AuthorizationTokenRequired

403UnauthorizedDisplaySize

GET

/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. Please see our Getting Started page for more information on how to sign up for an API key.

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.

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",
        "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.

{
    "videos":
    [
        "display_sizes":
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ]
    ]
}

Request

Query

Name	Data Type	Description
`sort_order`	string Allowed values: - `best_match` - `most_popular` - `newest` - `random`	Allows sorting of results.
`release_status`	string Allowed values: - `release_not_important` - `fully_released`	Allows filtering by type of model release.
`product_types`	array	Filter images to those from one of your product types. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription. If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. For example, some users may have more than one premiumaccess product, so the product_types value would be premiumaccess:1234. Product ID can be obtained from the GET /products response.
`phrase`	string	Free-text search query.
`page_size`	integer	Specifies page size. Default is 30, maximum page_size is 100.
`page`	integer	Identifies page to return. Default is 1.
`license_models`	array	Specifies the video licensing model(s).
`keyword_ids`	array	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.
`include_facets`	boolean	Specifies whether or not to include facets in the result set. Default is "false".
`frame_rates`	array	Provides filtering by video frame rate (frames/second).
`format_available`	string Allowed values: - `sd` - `hd` - `4k`	Filters according to the digital video format available on a film asset.
`fields`	array	Specifies fields to return. Defaults to 'summary_set'.
`facet_max_count`	integer	Specifies the maximum number of facets to return per type. Default is 300.
`facet_fields`	array	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.
`collections_filter_type`	string Allowed values: - `include` - `exclude`	Provides searching based on specified collection(s).
`collection_codes`	array	Provides filtering by collection code.
`age_of_people`	array	Provides filtering according to the age of individuals in a video.

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.
`Accept-Language`	string	Provide a header to specify the language of result values.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsSearchCreativeVideoSearchResults`	object

Properties

videos array [GettyImagesModelsSearchVideoSearchItem]

GettyImagesModelsSearchVideoSearchItem object

Properties

title string

source string

shot_speed string

referral_destinations array [GettyImagesModelsReferralDestination]

GettyImagesModelsReferralDestination object

Properties

`uri`	string
`site_name`	string

product_types array [string]

originally_shot_on string

mastered_to string

license_model string

largest_downloads array [GettyImagesModelsDownload]

GettyImagesModelsDownload object

Properties

`uri`	string
`product_type`	string
`product_id`	string
`agreement_name`	string

keywords array [GettyImagesModelsKeyword]

GettyImagesModelsKeyword object

Properties

`type`	string
`text`	string
`relevance`	integer
`keyword_id`	string
`entity_uris`	array [string]
`entity_types`	array [string]

istock_licenses array [GettyImagesModelsIStockLicense]

GettyImagesModelsIStockLicense object

Properties

`license_type`	string Allowed values: - `Standard` - `Multiseat` - `Unlimited` - `Resale` - `Indemnification`
`credits`	integer

id string

era string

display_sizes array [GettyImagesModelsSearchVideoSearchItemDisplaySize]

GettyImagesModelsSearchVideoSearchItemDisplaySize object

Properties

`uri`	string
`name`	string
`is_watermarked`	boolean
`aspect_ratio`	string

date_created dateTime

copyright string

color_type string

collection_name string

collection_id integer

collection_code string

clip_length string

caption string

asset_family string

artist string

allowed_use GettyImagesModelsAllowedUse

GettyImagesModelsAllowedUse object

Properties

`usage_restrictions`	array [string]	Indicates asset usage restriction, if any
`release_info`	string	Indicates release status
`how_can_i_use_it`	string	Indicates how the asset can be used

result_count integer

facets EnterpriseProxiesPublicV3ControllersSearchFacetsSearchFacetsResponse

EnterpriseProxiesPublicV3ControllersSearchFacetsSearchFacetsResponse object

Properties

specific_people array [EnterpriseProxiesPublicV3ControllersSearchFacetsSpecificPeople]

EnterpriseProxiesPublicV3ControllersSearchFacetsSpecificPeople object

Properties

`name`	string
`id`	integer

locations array [EnterpriseProxiesPublicV3ControllersSearchFacetsLocation]

EnterpriseProxiesPublicV3ControllersSearchFacetsLocation object

Properties

`name`	string
`id`	integer

events array [EnterpriseProxiesPublicV3ControllersSearchFacetsEvent]

EnterpriseProxiesPublicV3ControllersSearchFacetsEvent object

Properties

`name`	string
`id`	integer
`date`	dateTime

entertainment array [EnterpriseProxiesPublicV3ControllersSearchFacetsEntertainment]

EnterpriseProxiesPublicV3ControllersSearchFacetsEntertainment object

Properties

`name`	string
`id`	integer

artists array [EnterpriseProxiesPublicV3ControllersSearchFacetsArtist]

EnterpriseProxiesPublicV3ControllersSearchFacetsArtist object

Properties

name string

400InvalidParameterValue

401AuthorizationTokenRequired

403UnauthorizedDisplaySize

500InvalidIStockCollection

GET

/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. Please see our Getting Started page for more information on how to sign up for an API key.

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"
            }
        ],
        "era",
        "license_model",
        "mastered_to",
        "originally_shot_on",
        "product_types",
        "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.

{
    "videos":
    [
        "display_sizes":
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ]
    ]
}

Request Usage Considerations

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

Request

Query

Name	Data Type	Description
`specific_people`	array	Allows filtering by specific peoples' names.
`sort_order`	string Allowed values: - `best_match` - `most_popular` - `newest` - `oldest` - `random`	Allows sorting of results.
`release_status`	string Allowed values: - `release_not_important` - `fully_released`	Allows filtering by type of model release.
`product_types`	array	Filter images to those from one of your product types. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription. If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. For example, some users may have more than one premiumaccess product, so the product_types value would be premiumaccess:1234. Product ID can be obtained from the GET /products response.
`phrase`	string	Free-text search query.
`page_size`	integer	Specifies page size. Default is 30, maximum page_size is 100.
`page`	integer	Identifies page to return. Default is 1.
`keyword_ids`	array	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.
`include_facets`	boolean	Specifies whether or not to include facets in the result set. Default is "false".
`frame_rates`	array	Provides filtering by video frame rate (frames/second).
`format_available`	string Allowed values: - `sd` - `hd` - `4k`	Filters according to the digital video format available on a film asset.
`fields`	array	Specifies fields to return. Defaults to 'summary_set'.
`facet_max_count`	integer	Specifies the maximum number of facets to return per type. Default is 300.
`facet_fields`	array	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.
`entity_uris`	array	specify link data entity uri.
`editorial_video_types`	array	Allows filtering by types of video.
`collections_filter_type`	string Allowed values: - `include` - `exclude`	Provides searching based on specified collection(s).
`collection_codes`	array	Provides filtering by collection code.
`age_of_people`	array	Provides filtering according to the age of individuals in a video.

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.
`Accept-Language`	string	Provide a header to specify the language of result values.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsSearchEditorialVideoSearchResults`	object

Properties

videos array [GettyImagesModelsSearchVideoSearchItem]

GettyImagesModelsSearchVideoSearchItem object

Properties

title string

source string

shot_speed string

referral_destinations array [GettyImagesModelsReferralDestination]

GettyImagesModelsReferralDestination object

Properties

`uri`	string
`site_name`	string

product_types array [string]

originally_shot_on string

mastered_to string

license_model string

largest_downloads array [GettyImagesModelsDownload]

GettyImagesModelsDownload object

Properties

`uri`	string
`product_type`	string
`product_id`	string
`agreement_name`	string

keywords array [GettyImagesModelsKeyword]

GettyImagesModelsKeyword object

Properties

`type`	string
`text`	string
`relevance`	integer
`keyword_id`	string
`entity_uris`	array [string]
`entity_types`	array [string]

istock_licenses array [GettyImagesModelsIStockLicense]

GettyImagesModelsIStockLicense object

Properties

`license_type`	string Allowed values: - `Standard` - `Multiseat` - `Unlimited` - `Resale` - `Indemnification`
`credits`	integer

id string

era string

display_sizes array [GettyImagesModelsSearchVideoSearchItemDisplaySize]

GettyImagesModelsSearchVideoSearchItemDisplaySize object

Properties

`uri`	string
`name`	string
`is_watermarked`	boolean
`aspect_ratio`	string

date_created dateTime

copyright string

color_type string

collection_name string

collection_id integer

collection_code string

clip_length string

caption string

asset_family string

artist string

allowed_use GettyImagesModelsAllowedUse

GettyImagesModelsAllowedUse object

Properties

`usage_restrictions`	array [string]	Indicates asset usage restriction, if any
`release_info`	string	Indicates release status
`how_can_i_use_it`	string	Indicates how the asset can be used

result_count integer

facets EnterpriseProxiesPublicV3ControllersSearchFacetsSearchFacetsResponse

EnterpriseProxiesPublicV3ControllersSearchFacetsSearchFacetsResponse object

Properties

specific_people array [EnterpriseProxiesPublicV3ControllersSearchFacetsSpecificPeople]

EnterpriseProxiesPublicV3ControllersSearchFacetsSpecificPeople object

Properties

`name`	string
`id`	integer

locations array [EnterpriseProxiesPublicV3ControllersSearchFacetsLocation]

EnterpriseProxiesPublicV3ControllersSearchFacetsLocation object

Properties

`name`	string
`id`	integer

events array [EnterpriseProxiesPublicV3ControllersSearchFacetsEvent]

EnterpriseProxiesPublicV3ControllersSearchFacetsEvent object

Properties

`name`	string
`id`	integer
`date`	dateTime

entertainment array [EnterpriseProxiesPublicV3ControllersSearchFacetsEntertainment]

EnterpriseProxiesPublicV3ControllersSearchFacetsEntertainment object

Properties

`name`	string
`id`	integer

artists array [EnterpriseProxiesPublicV3ControllersSearchFacetsArtist]

EnterpriseProxiesPublicV3ControllersSearchFacetsArtist object

Properties

name string

400InvalidParameterValue

401AuthorizationTokenRequired

403UnauthorizedDisplaySize

GET

/v3/search/videos

Use this endpoint to search over a blend of our premium stock, contemporary 4K and HD footage, celebrities, news, newsmakers, entertainment, events and archival videos.

You'll need an API key and access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

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"
            }
        ],
        "era",
        "license_model",
        "mastered_to",
        "originally_shot_on",
        "product_types",
        "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.

{
    "videos":
    [
        "display_sizes":
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ]
    ]
}

Request Usage Considerations

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

Request

Query

Name	Data Type	Description
`specific_people`	array	Provides filtering by specific peoples' names.
`sort_order`	string Allowed values: - `best_match` - `most_popular` - `newest` - `oldest` - `random`	Allows sorting of results.
`release_status`	string Allowed values: - `release_not_important` - `fully_released`	Allows filtering by type of model release.
`product_types`	array	Filter images to those from one of your product types. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription. If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. For example, some users may have more than one premiumaccess product, so the product_types value would be premiumaccess:1234. Product ID can be obtained from the GET /products response.
`phrase`	string	Free-text search query.
`page_size`	integer	Specifies page size. Default is 30, maximum page_size is 100.
`page`	integer	Identifies page to return. Default is 1.
`license_models`	array	Specifies the video licensing model(s).
`keyword_ids`	array	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.
`frame_rates`	array	Provides filtering by video frame rate (frames/second).
`format_available`	string Allowed values: - `sd` - `hd` - `4k`	Filters according to the digital video format available on a film asset.
`fields`	array	Specifies fields to return. Defaults to 'summary_set'.
`editorial_video_types`	array	Allows filtering by types of video.
`collections_filter_type`	string Allowed values: - `include` - `exclude`	Provides searching based on specified collection(s).
`collection_codes`	array	Provides filtering by collection code.
`age_of_people`	array	Provides filtering according to the age of individuals in a video.

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.
`Accept-Language`	string	Provide a header to specify the language of result values.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsSearchVideoSearchResultsGettyImagesModelsArtistsVideoSearchItem`	object

Properties

videos array [GettyImagesModelsArtistsVideoSearchItem]

GettyImagesModelsArtistsVideoSearchItem object

Properties

title string

license_model string

keywords array [GettyImagesModelsArtistsKeyword]

GettyImagesModelsArtistsKeyword object

Properties

`type`	string
`text`	string
`keyword_id`	string

id string

display_sizes array [GettyImagesModelsArtistsDisplaySize]

GettyImagesModelsArtistsDisplaySize object

Properties

`uri`	string
`name`	string
`is_watermarked`	boolean
`aspect_ratio`	string

date_submitted dateTime

collection_name string

collection_code string

caption string

asset_type string
Allowed values:
- Image
- Film

asset_family string

alternative_ids object

result_count integer

facets EnterpriseProxiesPublicV3ControllersSearchFacetsSearchFacetsResponse

EnterpriseProxiesPublicV3ControllersSearchFacetsSearchFacetsResponse object

Properties

specific_people array [EnterpriseProxiesPublicV3ControllersSearchFacetsSpecificPeople]

EnterpriseProxiesPublicV3ControllersSearchFacetsSpecificPeople object

Properties

`name`	string
`id`	integer

locations array [EnterpriseProxiesPublicV3ControllersSearchFacetsLocation]

EnterpriseProxiesPublicV3ControllersSearchFacetsLocation object

Properties

`name`	string
`id`	integer

events array [EnterpriseProxiesPublicV3ControllersSearchFacetsEvent]

EnterpriseProxiesPublicV3ControllersSearchFacetsEvent object

Properties

`name`	string
`id`	integer
`date`	dateTime

entertainment array [EnterpriseProxiesPublicV3ControllersSearchFacetsEntertainment]

EnterpriseProxiesPublicV3ControllersSearchFacetsEntertainment object

Properties

`name`	string
`id`	integer

artists array [EnterpriseProxiesPublicV3ControllersSearchFacetsArtist]

EnterpriseProxiesPublicV3ControllersSearchFacetsArtist object

Properties

name string

400InvalidParameterValue

401AuthorizationTokenRequired

403UnauthorizedDisplaySize

PUT

/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 a Resource Owner Grant access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

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

Request

Path

Name	Data Type	Description
`id`	string	Specifies a unique batch transaction id to identify the report.

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.

Body

Name	Data Type	Description
`report_usage_batch_request`	object	Specifies the request information for the Batch Usages endpoint.

Properties


                        asset_usages

array [asset_usage]

Identifies the list of asset id, usage count and date of usage combinations to record.


                        asset_usage

object

Specifies the id, usage Quantity, and date of when an asset was used.

Properties

`usage_date`	dateTime	Identifies the date the asset was used, in ISO 8601 format (e.g., YYYY-MM-DD), time is not needed.
`quantity`	integer	Specifies the number of times the asset was used.
`asset_id`	string	Specifies the Id of the asset that was used.

Responses

201Success - All usages reported were successfully recorded.

Body

Name	Data Type	Description
`report_usage_batch_response`	object	Specifies the response from the Batch Usages endpoint.

Properties

`total_asset_usages_processed`	integer	Specifies the number of asset usage records that were successfully recorded.
`invalid_assets`	array [string]	Identifies a list of asset ids submitted that did not match known Getty asset ids.

400InvalidRequest - The content of the request was invalid. Most commonly this is due to either too many assets specified, no assets or invalid JSON.

401AuthorizationTokenRequired - Authorization token was missing or not valid.

403UnauthorizedToReportUsage

409TransactionIdDuplicated

GET

/v3/videos/{id}/similar

Get videos similar to a video by supplying one video id

Request

Path

Name	Data Type	Description
`id`	string	A video id.

Query

Name	Data Type	Description
`page_size`	integer	Specifies page size. Default is 30, maximum page_size is 100.
`page`	integer	Identifies page to return. Default is 1.
`fields`	array	comma delimited list of fields to retrive for the videos

Header

Name	Data Type	Description
`Authorization`	string	Provide access token in the format of 'Bearer {token}'.
`Accept-Language`	string	Provide a header to specify the language of result values.

Responses

200OK

Body

Name	Data Type	Description
`GettyImagesModelsArtistsVideoSearchResults`	object

Properties

videos array [GettyImagesModelsArtistsVideoSearchItem]

GettyImagesModelsArtistsVideoSearchItem object

Properties

title string

license_model string

keywords array [GettyImagesModelsArtistsKeyword]

GettyImagesModelsArtistsKeyword object

Properties

`type`	string
`text`	string
`keyword_id`	string

id string

display_sizes array [GettyImagesModelsArtistsDisplaySize]

GettyImagesModelsArtistsDisplaySize object

Properties

`uri`	string
`name`	string
`is_watermarked`	boolean
`aspect_ratio`	string

date_submitted dateTime

collection_name string

collection_code string

caption string

asset_type string
Allowed values:
- Image
- Film

asset_family string

alternative_ids object

result_count integer

400InvalidParameterValue

401AuthorizationTokenRequired

403UnauthorizedDisplaySize

404VideosNotFound

500InvalidIStockCollection

GET

/v3/videos/{id}

Getty Images

Resources

Artists

Request

Query

Header

Responses

Body

Properties

Properties

Properties

Properties

Properties

Request

Query

Header

Responses

Body

Properties

Properties

Properties

Properties

AssetChanges

Delete Asset Changes

Quickstart

Request

Path

Header

Responses

Asset Changes

Quickstart

Request

Query

Header

Responses

Body

Properties

Properties

Get Partner Channels

Quickstart

Request

Header

Responses

Body

Properties

Properties

AssetLicensing

Request

Path

Header

Body

Properties

Responses

Body

Properties

Boards

Request

Path

Header

Responses

Request

Path

Header

Responses

Body

Request

Path

Query

Header

Responses

Request

Path

Header

Body

Properties

Responses

Body

Properties

Properties

Request