Experiment with this API

Search for Creative Videos

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

Quickstart

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. There are several SDKs available for popular programming languages to help you get started.

Use the following endpoint to search for creative videos:

GET https://api.gettyimages.com/v3/search/videos/creative?phrase=<query term>

Add your API key to the request header:

Api-Key: <your api key>

Your request would look like this using curl:

curl -X GET -H "Api-Key: <your api key>" https://api.gettyimages.com/v3/search/videos/creative?phrase=<query term>

The response body will look like the following example:

{
"result_count": 1,
"videos": [{
      "id": "<creative video id>",
      "asset_family": "creative",
      "caption": "<video description>",
      "collection_code": "<collection code>",
      "collection_id": <collectionid>,
      "collection_name": "<collection name>",
      "display_sizes": [{
          "is_watermarked": true,
          "name": "preview",
          "uri": "<display url>"
      },
      {
          "is_watermarked": false,
          "name": "thumb",
          "uri": "<display url>"
      }],
      "license_model": "rightsmanaged",
      "title": "<video title>"
}]
}

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

Your request would look like this using curl:

curl -X GET -H "Api-Key: <your api key>" -H "Authorization: Bearer <your-token>" https://api.gettyimages.com/v3/search/videos/creative?phrase=<query term>

The response body will look similar to the previous response example.

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

Api-Key string Provide your API key. Required.
Accept-Language string Specifies the language of result values.
Authorization string Provide access token in the format of 'Bearer {token}'.

Querystring Parameters

age_of_people array Provides filtering according to the age of individuals in a video. Possible values: newborn baby child teenager young_adult adult adults_only mature_adult senior_adult 0-1_months 2-5_months 6-11_months 12-17_months 18-23_months 2-3_years 4-5_years 6-7_years 8-9_years 10-11_years 12-13_years 14-15_years 16-17_years 18-19_years 20-24_years 20-29_years 25-29_years 30-34_years 30-39_years 35-39_years 40-44_years 40-49_years 45-49_years 50-54_years 50-59_years 55-59_years 60-64_years 60-69_years 65-69_years 70-79_years 80-89_years 90_plus_years 100_over
collection_codes array Provides filtering by collection code.
collections_filter_type string Provides searching based on specified collection(s). Possible values: include exclude
exclude_nudity boolean Excludes images containing nudity. The default is false.
fields array Specifies fields to return. Defaults to 'summary_set'. Possible values: allowed_use artist asset_family caption clip_length collection_code collection_id collection_name color_type comp copyright date_created detail_set display_set era id keywords largest_downloads license_model mastered_to originally_shot_on preview product_types referral_destinations shot_speed source summary_set thumb title
format_available string Filters according to the digital video format available on a film asset. Possible values: sd hd 4k
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.
license_models array Specifies the video licensing model(s). Possible values: rightsready royaltyfree
phrase string Free-text search query.
product_types array Allows filtering by a list of product types. Possible values: easyaccess editorialsubscription imagepack premiumaccess royaltyfreesubscription creditpack

Sorting and Pagination

page integer Identifies page to return. Default is 1.
page_size integer Specifies page size. Default is 30, maximum page_size is 100.
sort_order string Allows sorting of results. Possible values: best_match newest

Response Body Fields

creative_video_search_results

result_count integer Specifies the count of matching assets returned.
videos array [ video_search_item ] List of video search results.

video_search_item

id string Specifies the unique identifier of the asset.
allowed_use Specifies how customers are allowed to use the asset.
artist string Specifies video creator.
asset_family string Indicates the asset family classification. Possible values are: creative, editorial.
caption string Gives a brief description of the video.
clip_length string Specifies the length of the film clip (Example: "00:00:12:08").
collection_id integer Specifies the id of the collection to which the video belongs.
collection_code string Specifies the code of the collection to which the video belongs.
collection_name string Specifies the name of the collection to which the video belongs.
color_type string Specifies whether the image or video is color or black and white. Possible values are color, black_and_white, and null.
copyright string Specifies the copyright of the video.
date_created string Specifies the date the video was created, in ISO 8601 format (e.g., 1999-12-31T00:00:00-00:00).
display_sizes array [ display_size ] Lists the display size information for this video.
era string The era of the video. Possible values are: archival, contemporary, and null.
keywords array [ keywords ] Lists the keyword entries associated with image/asset.
largest_downloads array [ download ] Lists the available largest download sizes.
license_model string Specifies the licensing model for the video. Possible values are: royaltyfree, rightsready.
mastered_to string Specifies the mastered to media.
originally_shot_on string Specifies the film stock originally shot on.
product_types array [ string ] Lists the product types for the video. Possible values are: premiumaccess, easyaccess, editorialsubscription, imagepack, royaltyfreesubscription, creditpack.
referral_destinations array [ referral_destination ] Lists the referral destinations for Getty Images assets.
shot_speed string Specifies the speed the at which the video was shot. Possible values are: real_time, slow_motion, time_lapse, and null.
source string Specifies the editorial source.
title string Specifies the title given by the artist.
istock_licenses array [ istock_license ] Contains the cost in iStock credits for all available license types.

allowed_use

how_can_i_use_it string Specifies how the asset can be used.
release_info string Specifies the release status.
usage_restrictions array [ string ] Specifies the asset usage restriction.

display_size

is_watermarked boolean Specifies whether the image is watermarked.
name string Specifies the name of the display size.
uri string GET this URI to retrieve the display size image.

keywords

keyword_id string Specifies the unique identifier for the keyword.
text string Provides localized text of the keyword.
type string Specifies the keyword type.
relevance integer Specifies the relevancy of the keyword to the asset. 0-5 or null, 5 being most relevant.
entity_uris array [ string ] Lists the URIs where detailed information can be found for a specific person.
entity_types array [ string ] Lists the person types for a specific person. E.g., 'Musician', 'Politician'.

download

product_id string Specifies the given product based on a company agreement. Applies only to royaltyfreesubscription and imagepack.
product_type string Specifies the license agreement applied to this download. Possible values are: premiumaccess, easyaccess, editorialsubscription, imagepack, royaltyfreesubscription, creditpack, sandbox.
uri string POST this URI to download the asset.
agreement_name string Specifies the customer-defined name of the Premium Access agreement

referral_destination

site_name string Specifies the asset domain name.
uri string GET this URI to retrieve appropriate referral destination data.

istock_license

license_type string name of the license_type
credits integer Cost in iStock Credits

Response Status Codes

200 OK
400 InvalidParameterValue
400 InvalidPage
400 InvalidPageSize
400 UnknownProviderUri
400 IncorrectlyFormedUri
400 MalformedRequest
401 AuthorizationTokenRequired
401 Unauthorized
403 UnauthorizedDisplaySize
403 NoAccessToProductType

Some response items contain hyperlinks which you can use to take you directly to the next steps in your workflow, when appropriate. The following URIs are provided in the response for this request.

display_size.uri string GET this URI to retrieve the display size image.
keywords.entity_uris array Lists the URIs where detailed information can be found for a specific person.
download.uri string POST this URI to download the asset.
referral_destination.uri string GET this URI to retrieve appropriate referral destination data.