Experiment with this API

Get Metadata for Single Video

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

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 return detailed video metadata for the specified video id:

GET https://api.gettyimages.com/v3/videos/<videoId>

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/videos/<videoId>

The response body will look like the following example:

{
          "id": "<video id>",
          "asset_family": "<asset_family>",
          "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/videos/<videoId>

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"
            }
        ],
        "download_sizes",
        "era",
        "license_model",
        "mastered_to",
        "originally_shot_on",
        "product_types",
        "shot_speed",
        "source",
        "title"
    ]
}

Display Fields Set

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

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

Request Usage Considerations

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

Request 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}'.

URI Path Parameters

id string A video id. For more than one video please use the /v3/video endpoint. Required.

Querystring Parameters

fields array comma delimited list of fields to retrive for the video Possible values: id allowed_use artist asset_family caption clip_length collection_code collection_id collection_name color_type copyright comp date_created detail_set display_set download_sizes downloads era editorial_segments entity_details keywords license_model mastered_to originally_shot_on preview product_types shot_speed source summary_set thumb title istock_licenses

Response Body Fields

video_detail

id string Specifies the unique identifier for the video.
allowed_use Specifies how customers are allowed to use the video.
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 id 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.
download_sizes array [ download_size ] Lists the available download size information.
editorial_segments array [ string ] Lists the editorial segments for this asset. Possible values are archival, entertainment, news, publicity, royalty, sport.
era string The era of the video. Possible values are: archival, contemporary, and null.
keywords array [ keywords ] Lists the keywords that are associated with this video.
license_model string Specifies the licensing model for the video. Possible values are: royaltyfree, rightsready.
mastered_to string Specifies the video format of the master.
originally_shot_on string Specifies the media the video was originally shot on.
product_types array [ string ] Lists the product types for the video. Possible values are: premiumaccess, easyaccess, editorialsubscription, imagepack, royaltyfreesubscription, creditpack.
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 of this video.
title string Specifies the title of this video.
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.

download_size

bit_depth string Specifies the bit depth of the video.
broadcast_video_standard string Indicates broadcast video standard of the video (e.g., NTSC, PAL).
compression string Specifies the video compression.
content_type string Specifies the content type of the video (e.g., "video/mp4").
description string Description of video.
downloads array [ download ] List of video download information.
format string Specifies the video format (e.g., SD, HD, 4K, Multimedia, or Web).
frame_rate number Specifies the video frame rate (e.g., 24, 25, 29.97).
frame_size string Specifies the video frame size (e.g., "640x360").
height number Specifies the height in pixels.
interlaced boolean Specifies whether the video is interlaced.
name string Specifies the name of the video size.
width integer Specifies the width.

download

product_id string Specifies the instance Id of the product.
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 video.
agreement_name string Specifies the customer-defined name of the Premium Access agreement

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

istock_license

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

Response Status Codes

200 OK
400 InvalidParameterValue
400 MalformedRequest
401 AuthorizationTokenRequired
401 Unauthorized
403 UnauthorizedDisplaySize
404 VideosNotFound

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.
download.uri string POST this URI to download the video.
keywords.entity_uris array Lists the URIs where detailed information can be found for a specific person.