Search for creative videos

v1.0.0

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

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)."
    },
    "GI-Country-Code": {
      "type": "string",
      "description": "Use of this parameter requires configuration changes to your API key. Please contact your sales representative to learn more."
    },
    "age_of_people": {
      "type": "array",
      "description": "Provides filtering according to the age of individuals in a video.",
      "items": {
        "type": "string",
        "enum": [
          "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"
        ]
      }
    },
    "artists": {
      "type": "string",
      "description": "Search for videos by specific artists (free-text, comma-separated list of artists)."
    },
    "aspect_ratios": {
      "type": "array",
      "description": "Search for videos by specific aspect ratios.",
      "items": {
        "type": "string",
        "enum": [
          "16:9",
          "9:16",
          "3:4",
          "4:3",
          "4:5",
          "2:1",
          "17:9",
          "9:17"
        ]
      }
    },
    "collection_codes": {
      "type": "array",
      "description": "Provides filtering by collection code.",
      "items": {
        "type": "string"
      }
    },
    "collections_filter_type": {
      "type": "string",
      "enum": [
        "include",
        "exclude"
      ]
    },
    "compositions": {
      "type": "array",
      "description": "Filter based on video composition.",
      "items": {
        "type": "string",
        "enum": [
          "abstract",
          "candid",
          "close_up",
          "copy_space",
          "cut_out",
          "full_frame",
          "full_length",
          "headshot",
          "looking_at_camera",
          "macro",
          "portrait",
          "sparse",
          "still_life",
          "three_quarter_length",
          "waist_up"
        ]
      }
    },
    "download_product": {
      "type": "string",
      "description": "Filters based on which product the asset will download against.\r\n                    Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription.\r\n                    If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. \r\n                    For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. \r\n                    Product ID can be obtained from the GET /products response."
    },
    "exclude_editorial_use_only": {
      "type": "boolean",
      "description": "Exclude videos that are only available for editorial (non-commercial) use. Default value is false."
    },
    "exclude_keyword_ids": {
      "type": "array",
      "description": "Return only videos not tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those videos matching the query phrase which also do not contain the requested keyword(s) are returned.",
      "items": {
        "type": "integer",
        "format": "int32"
      }
    },
    "exclude_nudity": {
      "type": "boolean",
      "description": "Excludes videos containing nudity. The default is false."
    },
    "facet_fields": {
      "type": "array",
      "description": "Specifies the facets to return in the response. Facets provide additional search parameters to refine your results.\r\n                   The include_facets parameter must be set to \"true\" for facets to be returned.",
      "items": {
        "type": "string",
        "enum": [
          "artists",
          "locations"
        ]
      }
    },
    "facet_max_count": {
      "type": "integer",
      "format": "int32",
      "description": "Specifies the maximum number of facets to return per type. Default is 300."
    },
    "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": [
          "allowed_use",
          "artist",
          "aspect_ratio",
          "asset_family",
          "call_for_image",
          "caption",
          "clip_length",
          "collection_code",
          "collection_id",
          "collection_name",
          "color_type",
          "comp",
          "copyright",
          "date_created",
          "date_submitted",
          "detail_set",
          "display_set",
          "download_product",
          "download_sizes",
          "era",
          "id",
          "istock_collection",
          "keywords",
          "largest_downloads",
          "license_model",
          "mastered_to",
          "object_name",
          "orientation",
          "originally_shot_on",
          "preview",
          "product_types",
          "quality_rank",
          "referral_destinations",
          "shot_speed",
          "summary_set",
          "thumb",
          "title"
        ]
      }
    },
    "format_available": {
      "type": "string",
      "enum": [
        "sd",
        "hd",
        "4k",
        "hd_web"
      ]
    },
    "frame_rates": {
      "type": "array",
      "description": "Provides filtering by video frame rate (frames/second).",
      "items": {
        "type": "string",
        "enum": [
          "23.98",
          "24",
          "25",
          "29.97",
          "30",
          "50",
          "59.94",
          "60"
        ]
      }
    },
    "image_techniques": {
      "type": "array",
      "description": "Filter based on image technique.",
      "items": {
        "type": "string",
        "enum": [
          "realtime",
          "time_lapse",
          "slow_motion",
          "color",
          "black_and_white",
          "animation",
          "selective_focus"
        ]
      }
    },
    "include_facets": {
      "type": "boolean",
      "description": "Specifies whether or not to include facets in the result set. Default is \"false\"."
    },
    "include_related_searches": {
      "type": "boolean",
      "description": "Specifies whether or not to include related searches in the response. The default is false."
    },
    "keyword_ids": {
      "type": "array",
      "description": "Return only videos tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those videos matching the query phrase which also contain the requested keyword(s) are returned.",
      "items": {
        "type": "integer",
        "format": "int32"
      }
    },
    "license_models": {
      "type": "array",
      "description": "Specifies the video licensing model(s).",
      "items": {
        "type": "string",
        "enum": [
          "rightsready",
          "royaltyfree"
        ]
      }
    },
    "max_clip_length": {
      "type": "integer",
      "format": "int32",
      "description": "Provides filtering by maximum length of video, in seconds"
    },
    "min_clip_length": {
      "type": "integer",
      "format": "int32",
      "description": "Provides filtering by minimum length of video clip, in seconds"
    },
    "orientations": {
      "type": "array",
      "description": "Return only videos with selected orientations.",
      "items": {
        "type": "string",
        "enum": [
          "horizontal",
          "vertical"
        ]
      }
    },
    "page": {
      "type": "integer",
      "format": "int32",
      "description": "Identifies page to return. Default is 1."
    },
    "page_size": {
      "type": "integer",
      "format": "int32",
      "description": "Specifies page size. Default is 30, maximum page_size is 100."
    },
    "phrase": {
      "type": "string",
      "description": "Free-text search query."
    },
    "release_status": {
      "type": "string",
      "enum": [
        "release_not_important",
        "fully_released"
      ]
    },
    "safe_search": {
      "type": "boolean",
      "description": "Setting safe_search to \"true\" excludes images containing nudity, death, profanity, drugs and alcohol, suggestive content, and graphic content from the result set. The default is false. Because this is a keyword-based filter, it's possible that a small number of unsafe images may not be caught by the filter. Please direct feedback to your Getty Images Account or API support representative."
    },
    "sort_order": {
      "type": "string",
      "enum": [
        "best_match",
        "most_popular",
        "newest",
        "random"
      ]
    },
    "viewpoints": {
      "type": "array",
      "description": "Filter based on viewpoint.",
      "items": {
        "type": "string",
        "enum": [
          "lockdown",
          "panning",
          "tracking_shot",
          "aerial_view",
          "high_angle_view",
          "low_angle_view",
          "tilt",
          "point_of_view"
        ]
      }
    }
  },
  "additionalProperties": false
}

Output

{
  "type": "object",
  "properties": {
    "auto_corrections": {
      "type": "object",
      "properties": {
        "phrase": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "facets": {
      "type": "object",
      "properties": {
        "artists": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              }
            },
            "additionalProperties": false
          }
        },
        "entertainment": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "format": "int32"
              },
              "name": {
                "type": "string"
              }
            },
            "additionalProperties": false
          }
        },
        "events": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "date": {
                "type": "string",
                "format": "date-time"
              },
              "id": {
                "type": "integer",
                "format": "int32"
              },
              "name": {
                "type": "string"
              }
            },
            "additionalProperties": false
          }
        },
        "locations": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "format": "int32"
              },
              "name": {
                "type": "string"
              }
            },
            "additionalProperties": false
          }
        },
        "specific_people": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "format": "int32"
              },
              "name": {
                "type": "string"
              }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
    "related_searches": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "phrase": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    },
    "result_count": {
      "type": "integer",
      "format": "int32"
    },
    "videos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "allowed_use": {
            "type": "object",
            "properties": {
              "how_can_i_use_it": {
                "type": "string",
                "description": "Indicates how the asset can be used"
              },
              "release_info": {
                "type": "string",
                "description": "Indicates release status"
              },
              "usage_restrictions": {
                "type": "array",
                "description": "Indicates asset usage restriction, if any",
                "items": {
                  "type": "string"
                }
              }
            },
            "additionalProperties": false
          },
          "artist": {
            "type": "string"
          },
          "asset_family": {
            "type": "string"
          },
          "caption": {
            "type": "string"
          },
          "clip_length": {
            "type": "string"
          },
          "collection_code": {
            "type": "string"
          },
          "collection_id": {
            "type": "integer",
            "format": "int32"
          },
          "collection_name": {
            "type": "string"
          },
          "color_type": {
            "type": "string"
          },
          "copyright": {
            "type": "string"
          },
          "date_created": {
            "type": "string",
            "format": "date-time"
          },
          "display_sizes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "aspect_ratio": {
                  "type": "string"
                },
                "is_watermarked": {
                  "type": "boolean"
                },
                "name": {
                  "type": "string"
                },
                "uri": {
                  "type": "string"
                }
              },
              "additionalProperties": false
            }
          },
          "download_product": {
            "type": "string"
          },
          "era": {
            "type": "string"
          },
          "event_ids": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "int32"
            }
          },
          "id": {
            "type": "string"
          },
          "istock_licenses": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "credits": {
                  "type": "integer",
                  "format": "int32"
                },
                "license_type": {
                  "type": "string",
                  "enum": [
                    "Standard",
                    "Multiseat",
                    "Unlimited",
                    "Resale",
                    "Indemnification"
                  ]
                }
              },
              "additionalProperties": false
            }
          },
          "keywords": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "entity_types": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "entity_uris": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "keyword_id": {
                  "type": "string"
                },
                "relevance": {
                  "type": "integer",
                  "format": "int32"
                },
                "text": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              },
              "additionalProperties": false
            }
          },
          "largest_downloads": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "agreement_name": {
                  "type": "string"
                },
                "product_id": {
                  "type": "string"
                },
                "product_type": {
                  "type": "string"
                },
                "uri": {
                  "type": "string"
                }
              },
              "additionalProperties": false
            }
          },
          "license_model": {
            "type": "string"
          },
          "mastered_to": {
            "type": "string"
          },
          "originally_shot_on": {
            "type": "string"
          },
          "product_types": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "referral_destinations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "site_name": {
                  "type": "string"
                },
                "uri": {
                  "type": "string"
                }
              },
              "additionalProperties": false
            }
          },
          "shot_speed": {
            "type": "string"
          },
          "title": {
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}