Getty Images Videos API
The Videos API from Getty Images — 11 operation(s) for videos.
OpenAPI Specification
openapi: 3.0.1
info:
title: Getty Images Videos API
version: '3'
description: '
Developer resources for the Getty Images API including SDK, documentation,
release notes, status, notifications and sample code.'
security:
- Api-Key: []
- OAuth2: []
tags:
- name: Videos
paths:
/v3/affiliates/search/videos:
get:
tags:
- Videos
parameters:
- name: Accept-Language
in: header
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).'
schema:
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).'
- name: GI-Country-Code
in: header
description: Receive regionally relevant search results based on the value specified. Accepts only ISO Alpha-3 country codes. The Countries operation can be used to retrieve the codes.
schema:
type: string
description: Use of this parameter requires configuration changes to your API key. Please contact your sales representative to learn more.
- name: phrase
in: query
schema:
type: string
nullable: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/AffiliateVideoSearchResponse'
/v3/artists/videos:
get:
tags:
- Videos
summary: Search for videos by a photographer
parameters:
- name: Accept-Language
in: header
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).'
schema:
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).'
- name: artist_name
in: query
description: Name of artist for desired images
schema:
type: string
description: Name of artist for desired images
nullable: true
- name: fields
in: query
description: Comma separated list of fields. Allows restricting which fields are returned. If no fields are selected, the summary_set of fields are returned.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ArtistsVideoSearchFieldValues'
description: Comma separated list of fields. Allows restricting which fields are returned. If no fields are selected, the summary_set of fields are returned.
nullable: true
- name: page
in: query
description: Identifies page to return. Default page is 1.
schema:
type: integer
description: Identifies page to return. Default page is 1.
format: int32
default: 1
- name: page_size
in: query
description: Specifies page size. Default page_size is 10, maximum page_size is 100.
schema:
type: integer
description: Specifies page size. Default page_size is 10, maximum page_size is 100.
format: int32
default: 10
responses:
'200':
description: OK
'400':
description: InvalidParameterValue
'401':
description: Unauthorized
/v3/downloads/videos/{id}:
post:
tags:
- Videos
summary: Download a video
description: "Use this endpoint to generate download URLs and related data for videos you are authorized to download.\n\nMost 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.\n\nThe download limit for a given download period is covered in your product agreement established with Getty Images.\n\nYou'll need an API key and a [Resource Owner Grant or Implicit Grant](http://developers.gettyimages.com/en/authorization-faq.html) access token to use this resource.\n\n## Auto Downloads\nThe `auto_download` request query parameter specifies whether to automatically download the video.\n\nIf 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 [HTTP 1.1 protocol](https://tools.ietf.org/html/rfc7231#section-6.4.4).\n\nClient Request:\n\n```\nhttps://api.gettyimages.com/v3/downloads/videos/[asset_id]?auto_download=true\n```\n\nServer Response:\n\nYour client code should follow redirect (3xx) status codes returned from the URI in the response Location header. More information here: [HTTP 1.1 protocol](https://tools.ietf.org/html/rfc7231#section-6.4).\n\n```\nHTTP/1.1 303 See Other\nLocation: https://delivery.gettyimages.com/...\n```\n\nIf 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. \n\nClient Request:\n\n```\nhttps://api.gettyimages.com/v3/downloads/videos/[asset_id]?auto_download=false\n```\n\nServer Response:\n\n```\nHTTP/1.1 200 OK\n{\n\t\"uri\": \"https://delivery.gettyimages.com/...\"\n}\n```\n\n## Downloading Via the Returned URI\n\nYour client code should follow redirect (3xx) status codes returned from the URI in the response. More information here: [HTTP 1.1 protocol](https://tools.ietf.org/html/rfc7231#section-6.4).\n\nThe URI returned by this call should be considered opaque and the format could change at any time.\nIn order to get the filename, length or file type, the response headers must be inspected. An example\nresponse follows:\n\n```\ncontent-length: 283925783\ncontent-type: video/quicktime\ncontent-disposition: attachment; filename=GettyImages-690773579.mov\n```\n\nThe `content-disposition` header must be parsed to get a usable filename.\n\n## Download URI expiration\n\nDownload URIs are _**only valid for 24 hours**_, starting from the moment they are returned from this call.\n"
parameters:
- name: Accept-Language
in: header
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).'
schema:
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).'
- name: id
in: path
description: "<remarks>\r\n Id of video to download.\r\n </remarks>"
required: true
schema:
type: string
description: "<remarks>\r\n Id of video to download.\r\n </remarks>"
nullable: true
- name: auto_download
in: query
description: "<remarks>\r\n Specifies whether to auto-download the video. If true is specified, a 303 SeeOther status is returned with a\r\n Location header set to the location of the video.\r\n If false is specified, the download URI will be returned in the response message. Default is false.\r\n </remarks>"
schema:
type: boolean
description: "<remarks>\r\n Specifies whether to auto-download the video. If true is specified, a 303 SeeOther status is returned with a\r\n Location header set to the location of the video.\r\n If false is specified, the download URI will be returned in the response message. Default is false.\r\n </remarks>"
default: false
- name: size
in: query
description: Specifies the size to be downloaded.
schema:
type: string
description: Specifies the size to be downloaded.
nullable: true
- name: product_id
in: query
description: "<remarks>\r\n Identifier of the instance for the selected product offering type.\r\n </remarks>"
schema:
type: integer
description: "<remarks>\r\n Identifier of the instance for the selected product offering type.\r\n </remarks>"
format: int32
nullable: true
- name: product_type
in: query
description: "<remarks>\r\n Product types easyaccess, editorialsubscription, imagepack, and premiumaccess are for GettyImages API keys. Product types royaltyfreesubscription and creditpack are for iStock API keys. Default product type for iStock API keys is creditpack.\r\n </remarks>"
schema:
$ref: '#/components/schemas/ProductTypeForDownloads'
- name: use_team_credits
in: query
description: Specifies whether to download the image with iStock Team Credits. Only applicable to iStock API keys authenticated with a user that has Team Credits. Blank is the same as False.
schema:
type: boolean
description: Specifies whether to download the image with iStock Team Credits. Only applicable to iStock API keys authenticated with a user that has Team Credits. Blank is the same as False.
nullable: true
requestBody:
description: "<remarks>\r\n Additional information required from specific customers when downloading. \r\n Only users who have been set up with a project code by Getty Images Sales need to use this field.\r\n </remarks>"
content:
application/json:
schema:
$ref: '#/components/schemas/PremiumAccessDownloadData'
responses:
'200':
description: OK
'303':
description: See Other
'400':
description: MissingRequiredQueryParameters
'401':
description: AuthorizationTokenRequired
'403':
description: OverageLimitReached
'404':
description: VideoNotFound
/v3/search/videos/creative:
get:
tags:
- Videos
summary: Search for creative videos
description: "Use this endpoint to search premium stock video, from archival film to contemporary 4K and HD footage.\n\nYou'll need an API key and access token to use this resource.\n\nYou can show different information in the response by specifying values on the \"fields\" parameter (see details below).\nYou 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\nbeing logged in (anonymous search). If you are a Getty Images API customer and would like to ensure that your API searches return only \nassets that you have a license to use, you need to also include an authorization token in the header of your request.\nPlease consult our [Authorization FAQ](http://developers.gettyimages.com/en/authorization-faq.html) for more information on authorization tokens.\n\nSearch requests without a phrase parameter are not supported and may not always work.\n\n## Working with Fields Sets\n\nFields sets are used in the **fields** request parameter to receive a suite of metadata fields. The following fields sets are available:\n\n#### Summary Fields Set\n\nThe **summary_set** query string parameter fields value represents a small batch of metadata fields that are often used to build search\nresponse results. The following fields are provided for every video in your result set when you include **summary_set** in your request.\n\n```\n{\n \"videos\": \n [\n \"asset_family\", \n \"caption\",\n \"collection_code\",\n \"collection_name\",\n \"display_sizes\":\n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"license_model\",\n \"title\"\n ]\n}\n```\n\n#### Detail Fields Set\n\nThe **detail_set** query string parameter fields value represents a large batch of metadata fields that are often used to build a \ndetailed view of videos. The following fields are provided for every video in your result set when you include **detail_set** in your request.\n\n```\n{\n \"videos\": \n [\n \"allowed_use\",\n \"artist\",\n \"asset_family\", \n\t\t\"call_for_image\",\n \"caption\", \n \"clip_length\",\n \"collection_code\",\n \"collection_id\",\n \"collection_name\", \n \"color_type\",\n \"copyright\",\n \"date_created\",\n \"display_sizes\":\n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"era\",\n \"license_model\",\n \"mastered_to\",\n \"originally_shot_on\",\n \"product_types\",\n \"quality_rank\",\n \"shot_speed\",\n \"source\",\n \"title\"\n ]\n}\n```\n\n#### Display Fields Set\n\nThe **display_set** query string parameter fields value represents the fields that provide you with URLs for the low resolution files \nthat are most frequently used to build a UI displaying search results. The following fields are provided for every video in your result \nset when you include **display_set** in your request.\n\nThe URI provided is subject to change at any time and must be used as-is with no modification.\n\n```\n{\n \"videos\":\n [\n \"display_sizes\": \n [\n {\n \"is_watermarked\": <boolean>,\n \"name\": \"comp\",\n \"uri\": \"<link>\"\n },\n {\n \"is_watermarked\": <boolean>,\n \"name\": \"preview\",\n \"uri\": \"<link>\"\n },\n {\n \"is_watermarked\": <boolean>,\n \"name\": \"thumb\",\n \"uri\": \"<link>\"\n }\n ]\n ]\n}\n```\n\n## Enhanced Search\n\nOur enhanced search uses machine-learning models to understand natural, conversational language. Meaning you can search for longer phrases and get more relevant results from our creative image and creative video libraries. Default is `true`. Set `enhanced_search` to `false` if you require a precise result set and not one expanded through enhanced search."
parameters:
- name: Accept-Language
in: header
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).'
schema:
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).'
- name: GI-Country-Code
in: header
description: Receive regionally relevant search results based on the value specified. Accepts only ISO Alpha-3 country codes. The Countries operation can be used to retrieve the codes.
schema:
type: string
description: Use of this parameter requires configuration changes to your API key. Please contact your sales representative to learn more.
- name: age_of_people
in: query
description: Provides filtering according to the age of individuals in a video.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/AgeOfPeopleFilterType'
description: Provides filtering according to the age of individuals in a video.
nullable: true
- name: artists
in: query
description: Search for videos by specific artists (free-text, comma-separated list of artists).
schema:
type: string
description: Search for videos by specific artists (free-text, comma-separated list of artists).
nullable: true
- name: aspect_ratios
in: query
description: Search for videos by specific aspect ratios.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/VideoAspectRatioFilterType'
description: Search for videos by specific aspect ratios.
nullable: true
- name: collection_codes
in: query
description: Provides filtering by collection code.
style: form
explode: false
schema:
type: array
items:
type: string
description: Provides filtering by collection code.
nullable: true
- name: collections_filter_type
in: query
description: Use to include or exclude collections from search. The default is include
schema:
$ref: '#/components/schemas/CollectionsFilterType'
- name: compositions
in: query
description: Filter based on video composition.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/CompositionsFilterType'
description: Filter based on video composition.
nullable: true
- name: download_product
in: query
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."
schema:
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."
nullable: true
- name: enhanced_search
in: query
description: If set to {false}, your search will not use enhanced search. Defaults to {true}.
schema:
type: boolean
description: If set to {false}, your search will not use enhanced search. Defaults to {true}.
default: true
nullable: true
- name: ethnicity
in: query
description: Filter search results based on the ethnicity of individuals.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EthnicityFilterType'
description: Filter search results based on the ethnicity of individuals.
nullable: true
- name: exclude_editorial_use_only
in: query
description: Exclude videos that are only available for editorial (non-commercial) use. Default value is false.
schema:
type: boolean
description: Exclude videos that are only available for editorial (non-commercial) use. Default value is false.
nullable: true
- name: exclude_keyword_ids
in: query
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.
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
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.
nullable: true
- name: exclude_nudity
in: query
description: Excludes videos containing nudity. The default is false.
schema:
type: boolean
description: Excludes videos containing nudity. The default is false.
default: false
- name: facet_fields
in: query
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."
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/CreateVideoSearchFacetsFields'
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."
nullable: true
- name: facet_max_count
in: query
description: Specifies the maximum number of facets to return per type. Default is 300.
schema:
type: integer
description: Specifies the maximum number of facets to return per type. Default is 300.
format: int32
default: 300
- name: fields
in: query
description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes returned by ''download_sizes'' field is an estimate.'
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/CreativeVideosFieldValues'
description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes returned by ''download_sizes'' field is an estimate.'
nullable: true
- name: format_available
in: query
description: Filters according to the digital video format available on a film asset.
schema:
$ref: '#/components/schemas/VideoFormatsRequest'
- name: frame_rates
in: query
description: Provides filtering by video frame rate (frames/second).
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/VideoFrameRates'
description: Provides filtering by video frame rate (frames/second).
nullable: true
- name: image_techniques
in: query
description: Filter based on image technique.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ImageTechniquesFilterType'
description: Filter based on image technique.
nullable: true
- name: include_facets
in: query
description: Specifies whether or not to include facets in the result set. Default is "false".
schema:
type: boolean
description: Specifies whether or not to include facets in the result set. Default is "false".
nullable: true
- name: include_related_searches
in: query
description: Specifies whether or not to include related searches in the response. The default is false.
schema:
type: boolean
description: Specifies whether or not to include related searches in the response. The default is false.
default: false
- name: keyword_ids
in: query
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.
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
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.
nullable: true
- name: license_models
in: query
description: Specifies the video licensing model(s).
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/LicenseModelVideoRequest'
description: Specifies the video licensing model(s).
nullable: true
- name: min_clip_length
in: query
description: Provides filtering by minimum length of video clip, in seconds
schema:
type: integer
description: Provides filtering by minimum length of video clip, in seconds
format: int32
default: 0
- name: max_clip_length
in: query
description: Provides filtering by maximum length of video, in seconds
schema:
type: integer
description: Provides filtering by maximum length of video, in seconds
format: int32
default: 0
- name: number_of_people
in: query
description: Filter based on the number of people.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/NumberOfPeopleFilterType'
description: Filter based on the number of people.
nullable: true
- name: orientations
in: query
description: Return only videos with selected orientations.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/VideoOrientationRequest'
description: Return only videos with selected orientations.
nullable: true
- name: page
in: query
description: Identifies page to return. Default is 1.
schema:
type: integer
description: Identifies page to return. Default is 1.
format: int32
default: 1
- name: page_size
in: query
description: Specifies page size. Default is 30, maximum page_size is 100.
schema:
type: integer
description: Specifies page size. Default is 30, maximum page_size is 100.
format: int32
default: 30
- name: phrase
in: query
description: Free-text search query.
schema:
type: string
description: Free-text search query.
default: ''
nullable: true
- name: safe_search
in: query
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.
schema:
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.
default: false
- name: sort_order
in: query
description: Select sort order of results. The default is best_match
schema:
$ref: '#/components/schemas/CreativeVideoSortOrder'
- name: release_status
in: query
description: Allows filtering by type of model release.
schema:
$ref: '#/components/schemas/ReleaseStatus'
- name: viewpoints
in: query
description: Filter based on viewpoint.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ViewpointsFilterType'
description: Filter based on viewpoint.
nullable: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreativeVideoSearchResults'
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
'500':
description: InvalidIStockCollection
/v3/search/videos/creative/by-image:
get:
tags:
- Videos
summary: Search for creative videos based on url
description: '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 defin
# --- truncated at 32 KB (105 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/getty-images/refs/heads/main/openapi/getty-images-videos-api-openapi.yml