Get metadata for multiple videos by supplying multiple video ids

v1.0.0

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.

Input

{
  "type": "object",
  "properties": {
    "Accept-Language": {
      "type": "string",
      "description": "Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th (iStock only), tr, uk (iStock only), vi (iStock only), zh-HK (creative assets only)."
    },
    "fields": {
      "type": "array",
      "description": "Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate.",
      "items": {
        "type": "string",
        "enum": [
          "id",
          "allowed_use",
          "artist",
          "asset_family",
          "call_for_image",
          "caption",
          "city",
          "clip_length",
          "collection_code",
          "collection_id",
          "collection_name",
          "color_type",
          "comp",
          "copyright",
          "country",
          "date_created",
          "date_submitted",
          "detail_set",
          "display_set",
          "download_sizes",
          "download_product",
          "downloads",
          "editorial_segments",
          "entity_details",
          "era",
          "event_ids",
          "istock_collection",
          "istock_licenses",
          "key_frames",
          "keywords",
          "license_model",
          "mastered_to",
          "object_name",
          "orientation",
          "originally_shot_on",
          "preview",
          "product_types",
          "quality_rank",
          "referral_destinations",
          "shot_speed",
          "source",
          "state_province",
          "summary_set",
          "thumb",
          "title"
        ]
      }
    },
    "ids": {
      "type": "array",
      "description": "Specifies one or more video ids to return. Use comma delimiter when requesting multiple ids.  Maximum of 100 ids.",
      "items": {
        "type": "string"
      }
    }
  },
  "additionalProperties": false
}

Output

{
  "type": "object",
  "additionalProperties": true
}