affiliateSearch.getV3AffiliatesSearchImages

affiliateSearch.getV3AffiliatesSearchVideos

GET /v3/affiliates/search/videos

artists.getV3ArtistsImages

Search for images by a photographer

artists.getV3ArtistsVideos

Search for videos by a photographer

assetChanges.deleteV3AssetChangesChangeSetsChangeSetId

Delete Asset Changes

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

Quickstart

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

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

assetChanges.getV3AssetChangesChannels

Get Partner Channels

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

Quickstart

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

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

assetChanges.putV3AssetChangesChangeSets

Asset Changes

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

Quickstart

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

Maximum batch size is 2200.

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

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

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

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

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

assetLicensing.postV3AssetLicensingAssetId

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

assetManagement.getV3AssetManagementAssetsSendEvents

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

boards.deleteV3BoardsBoardId

Delete a board

boards.deleteV3BoardsBoardIdAssets

Remove assets from a board

boards.deleteV3BoardsBoardIdAssetsAssetId

Remove an asset from a board

boards.deleteV3BoardsBoardIdCommentsCommentId

Delete a comment from a board

boards.getV3Boards

Get all boards that the user participates in

boards.getV3BoardsBoardId

Get assets and metadata for a specific board

boards.getV3BoardsBoardIdComments

Get comments from a board

boards.postV3Boards

Create a new board

boards.postV3BoardsBoardIdComments

Add a comment to a board

boards.putV3BoardsBoardId

Update a board

boards.putV3BoardsBoardIdAssets

Add assets to a board

boards.putV3BoardsBoardIdAssetsAssetId

Add an asset to a board

collections.getV3Collections

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

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

countries.getV3Countries

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.

customers.getV3CustomersCurrent

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

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

Please consult our for more information on authorization tokens.

downloads.getV3Downloads

Returns information about a customer's previously downloaded assets.

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

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

downloads.postV3DownloadsImagesId

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 access token to use this resource.

Auto Downloads

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

If the auto_download request query parameter is set to true, the API will return an HTTP status code 303 See Other. Your client code will need to process this response and redirect to the URI specified in the Location header to enable you to automatically download the file. The redirection workflow follows the .

Client Request:

Server Response:

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

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:

Server Response:

Downloading Via the Returned URI

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

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

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

Download URI expiration

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

downloads.postV3DownloadsVideosId

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 access token to use this resource.

Auto Downloads

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

If the auto_download request query parameter is set to true, the API will return an HTTP status code 303 See Other. Your client code will need to process this response and redirect to the URI specified in the Location header to enable you to automatically download the file. The redirection workflow follows the .

Client Request:

Server Response:

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

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:

Server Response:

Downloading Via the Returned URI

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

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

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

Download URI expiration

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

events.getV3Events

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.

events.getV3EventsId

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.

images.getV3Images

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

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

Working with Fields Sets

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

Summary Fields Set

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

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

Detail Fields Set

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

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

Display Fields Set

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

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

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

Request Usage Considerations

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

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

{    "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"    ]}

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

images.getV3ImagesId

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

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

Working with Fields Sets

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

Summary Fields Set

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

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

Detail Fields Set

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

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

Display Fields Set

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

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

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

Request Usage Considerations

Specifying the "entity_details" response field can have significant performance implications. The field should be used only when necessary.
```
    "name": "string",    "uri": "string"
```

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

{    "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"    ]}

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

images.getV3ImagesIdDownloadhistory

images.getV3ImagesIdSameSeries

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

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

Working with Fields Sets

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

Summary Fields Set

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

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

Detail Fields Set

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

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

Display Fields Set

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

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

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

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

{    "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"    ]}

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

images.getV3ImagesIdSimilar

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

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

Working with Fields Sets

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

Summary Fields Set

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

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

Detail Fields Set

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

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

Display Fields Set

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

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

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

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

{    "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"    ]}

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

orders.getV3OrdersId

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

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

products.getV3Products

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.

purchases.getV3PurchasedAssets

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

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

search.getV3SearchEvents

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.

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 for more information on authorization tokens, and our for code examples of getting a token.

search.getV3SearchImages

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

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

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

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

Working with Fields Sets

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

Summary Fields Set

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

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

Detail Fields Set

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

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

Display Fields Set

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

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

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

Request Usage Considerations

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

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

{    "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"    ]]

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

search.getV3SearchImagesCreative

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

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

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

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

Working with Fields Sets

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

Summary Fields Set

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

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

Detail Fields Set

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

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

Display Fields Set

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

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

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

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

{    "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"    ]]

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

search.getV3SearchImagesCreativeByImage

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

Searching by URL

Before calling the search by image endpoint, an image in JPEG format must be uploaded to https://api.gettyimages.com/v3/search/by-image/uploads/{CLIENT_IMAGE.jpg}, where the client defines the {CLIENT_IMAGE.jpg} portion of the URL.

For example, using cURL:

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

Uploaded files must be 10MB or smaller.
Uploads to the same URL will overwrite each other, so ensure that the client application is handling naming uniqueness appropriately.
Uploads expire after 24 hours.
Uploads and searches must be performed using the same API Key.

Searching by asset id

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

search.getV3SearchImagesEditorial

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

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

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

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

Working with Fields Sets

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

Summary Fields Set

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

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

Detail Fields Set

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

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

Display Fields Set

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

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

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

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

{    "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"    ]]

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

search.getV3SearchVideosCreative

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

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

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

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

Working with Fields Sets

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

Summary Fields Set

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

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

Detail Fields Set

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

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

Display Fields Set

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

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

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

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

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

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

search.getV3SearchVideosCreativeByImage

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

Searching by URL

Before calling the search by image endpoint, an image or frame grab in JPEG format must be uploaded to https://api.gettyimages.com/v3/search/by-image/uploads/{CLIENT_IMAGE.jpg}, where the client defines the {CLIENT_IMAGE.jpg} portion of the URL.

For example, using cURL:

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

Uploaded files must be 10MB or smaller
Uploads to the same URL will overwrite each other, so ensure that the client application is handling naming uniqueness appropriately.
Uploads expire after 24 hours.
Uploads and searches must be performed using the same API Key.

Searching by asset id

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

search.getV3SearchVideosEditorial

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

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

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

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

Working with Fields Sets

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

Summary Fields Set

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

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

Detail Fields Set

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

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

Display Fields Set

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

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

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

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

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

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

search.putV3SearchByImageUploadsFileName

Upload image for use by the search creative images/videos operations

usage.putV3UsageBatchesId

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

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

videos.getV3Videos

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

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

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

Working with Fields Sets

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

Summary Fields Set

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

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

Detail Fields Set

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

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

Display Fields Set

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

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

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

Request Usage Considerations

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

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

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

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

videos.getV3VideosId

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

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

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

Working with Fields Sets

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

Summary Fields Set

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

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

Detail Fields Set

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

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

Display Fields Set

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

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

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

Request Usage Considerations

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

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

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

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

videos.getV3VideosIdDownloadhistory

videos.getV3VideosIdSameSeries

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

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

Working with Fields Sets

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

Summary Fields Set

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

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

Detail Fields Set

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

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

Display Fields Set

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

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

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

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

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

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

videos.getV3VideosIdSimilar

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

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

Working with Fields Sets

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

Summary Fields Set

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

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

Detail Fields Set

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

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

Display Fields Set

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

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

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

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

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

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

openapi.previewSpec

Preview an OpenAPI document before adding it as a source

openapi.addSource

Add an OpenAPI source and register its operations as tools

Tools (54)

Delete Asset Changes

Quickstart

Get Partner Channels

Quickstart

Asset Changes

Quickstart

Auto Downloads

Downloading Via the Returned URI

Download URI expiration

Auto Downloads

Downloading Via the Returned URI

Download URI expiration

Working with Fields Sets

Summary Fields Set

Detail Fields Set

Display Fields Set

Request Usage Considerations

Working with Fields Sets

Summary Fields Set

Detail Fields Set

Display Fields Set

Request Usage Considerations

Working with Fields Sets

Summary Fields Set

Detail Fields Set

Display Fields Set

Working with Fields Sets

Summary Fields Set

Detail Fields Set

Display Fields Set

Working with Fields Sets

Summary Fields Set

Detail Fields Set

Display Fields Set

Request Usage Considerations

Working with Fields Sets

Summary Fields Set

Detail Fields Set

Display Fields Set

Searching by URL

Searching by asset id

Working with Fields Sets

Summary Fields Set

Detail Fields Set

Display Fields Set

Working with Fields Sets

Summary Fields Set

Detail Fields Set

Display Fields Set

Searching by URL

Searching by asset id

Working with Fields Sets

Summary Fields Set

Detail Fields Set

Display Fields Set

Report Usage

Quickstart

Working with Fields Sets

Summary Fields Set

Detail Fields Set

Display Fields Set

Request Usage Considerations

Working with Fields Sets

Summary Fields Set

Detail Fields Set

Display Fields Set

Request Usage Considerations

Working with Fields Sets

Summary Fields Set

Detail Fields Set

Display Fields Set

Working with Fields Sets

Summary Fields Set

Detail Fields Set

Display Fields Set