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: "\r\n Id of video to download.\r\n " required: true schema: type: string description: "\r\n Id of video to download.\r\n " nullable: true - name: auto_download in: query description: "\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 " schema: type: boolean description: "\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 " 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: "\r\n Identifier of the instance for the selected product offering type.\r\n " schema: type: integer description: "\r\n Identifier of the instance for the selected product offering type.\r\n " format: int32 nullable: true - name: product_type in: query description: "\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 " 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: "\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 " 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\": ,\n \"name\": \"comp\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"preview\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"thumb\",\n \"uri\": \"\"\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 defines the `{CLIENT_IMAGE.jpg}` portion of the URL. For example, using cURL: ``` sh curl -i -X PUT https://api.gettyimages.com/v3/search/by-image/uploads/my-test-image.jpg -H ''Content-Type: image/jpeg'' -H ''Api-Key: API_KEY'' --data-binary "@testimage.jpg" ``` Once the image has been uploaded, use the full URL in the `image_url` parameter, e.g. `image_url=https://api.gettyimages.com/v3/search/by-image/uploads/my-test-image.jpg`. - Uploaded files must be 10MB or smaller - Uploads to the same URL will overwrite each other, so ensure that the client application is handling naming uniqueness appropriately. - Uploads expire after 24 hours. - Uploads and searches must be performed using the _same_ API Key. ## Searching by asset id When searching by `asset_id`, any image or video asset id in the Getty/iStock catalog can be used as the source for similar 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: asset_id in: query description: Specifies the Getty video id to use in the search. schema: type: string description: Specifies the Getty video id to use in the search. 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: 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: image_url in: query description: Specifies the location of the image to use in the search. schema: type: string description: Specifies the location of the image to use in the search. 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: page in: query description: Request results starting at a page number (default is 1). schema: type: integer description: Request results starting at a page number (default is 1). format: int32 default: 1 - name: page_size in: query description: Request number of images to return in each page. Default is 30, maximum page_size is 100. schema: type: integer description: Request number of images to return in each page. 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: product_types in: query description: "Filter images to those from one of your product types. \r\n Allowed values are easyaccess, 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 product_types value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response." style: form explode: false schema: type: array items: type: string description: "Filter images to those from one of your product types. \r\n Allowed values are easyaccess, 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 product_types value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response." nullable: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CreativeVideoSearchResults' '400': description: InvalidParameterValue '401': description: AuthorizationTokenRequired '403': description: UnauthorizedDisplaySize '404': description: AssetNotFound '500': description: InvalidIStockCollection /v3/search/videos/editorial: get: tags: - Videos summary: Search for editorial videos description: "Use this endpoint to search current and archival video clips of celebrities, newsmakers, and events.\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 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](http://developers.gettyimages.com/en/authorization-faq.html) for more information on authorization tokens, and our [Authorization Workflows](https://github.com/gettyimages/gettyimages-api/blob/master/OAuth2Workflow.md) for code examples of getting a token.\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 response 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 detailed 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 \"event_ids\",\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 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.\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\": ,\n \"name\": \"comp\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"preview\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"thumb\",\n \"uri\": \"\"\n }\n ]\n ]\n}\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: 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: date_from in: query description: Return only images that are created on or after this date. Use ISO 8601 format (e.g., 1999-12-31). schema: type: string description: Return only images that are created on or after this date. Use ISO 8601 format (e.g., 1999-12-31). format: date-time nullable: true - name: date_to in: query description: Return only images that are created on or before this date. Use ISO 8601 format (e.g., 1999-12-31). schema: type: string description: Return only images that are created on or before this date. Use ISO 8601 format (e.g., 1999-12-31). format: date-time 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: editorial_video_types in: query description: Allows filtering by types of video. style: form explode: false schema: type: array items: $ref: '#/components/schemas/EditorialVideoType' description: Allows filtering by types of video. nullable: true - name: event_ids in: query description: Filter based on specific events style: form explode: false schema: type: array items: type: integer format: int32 description: Filter based on specific events nullable: true - 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/EditorialVideosFieldValues' 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_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: 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 clip, in seconds schema: type: integer description: Provides filtering by maximum length of video clip, in seconds format: int32 default: 0 - 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: sort_order in: query description: Select sort order of results. The default is best_match schema: $ref: '#/components/schemas/SortOrder' - name: specific_people in: query description: Allows filtering by specific peoples' names. style: form explode: false schema: type: array items: type: string description: Allows filtering by specific peoples' names. nullable: true - name: release_status in: query description: Allows filtering by type of model release. schema: $ref: '#/components/schemas/ReleaseStatus' - 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/EditorialVideoSearchFacetsFields' 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: 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: 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: 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/EditorialVideoSearchResults' '400': description: InvalidParameterValue '401': description: AuthorizationTokenRequired '403': description: UnauthorizedDisplaySize /v3/videos: get: tags: - Videos summary: Get metadata for multiple videos by supplying multiple video ids description: "Use this endpoint to return detailed video metadata for all the specified video ids.\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 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](http://developers.gettyimages.com/en/authorization-faq.html) for more information on authorization tokens, and our [Authorization Workflows](https://github.com/gettyimages/gettyimages-api/blob/master/OAuth2Workflow.md) for code examples of getting a token.\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 response 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 detailed 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 \"download_sizes\",\n \"era\",\n \"event_ids\",\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 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.\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 {\n \"display_sizes\": \n [\n {\n \"is_watermarked\": ,\n \"name\": \"comp\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"preview\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"thumb\",\n \"uri\": \"\"\n }\n ],\n \"key_frames\": [\n {\n \"uri\": \"\"\n },\n {\n \"uri\": \"\"\n },\n {\n \"uri\": \"\"\n },\n {\n \"uri\": \"\"\n },\n {\n \"uri\": \"\"\n }\n ]\n }\n ]\n}\n```\n\n## Request Usage Considerations\n\n- Specifying the \"entity_details\" response field can have significant performance implications. The field should be used only when necessary.\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: ids in: query description: Specifies one or more video ids to return. Use comma delimiter when requesting multiple ids. Maximum of 100 ids. style: form explode: false schema: type: array items: type: string description: Specifies one or more video ids to return. Use comma delimiter when requesting multiple ids. Maximum of 100 ids. nullable: true - 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/VideoDetailFieldValues' description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes returned by ''download_sizes'' field is an estimate.' nullable: true responses: '200': description: OK '400': description: InvalidParameterValue '401': description: AuthorizationTokenRequired '403': description: UnauthorizedDisplaySize '404': description: VideosNotFound '500': description: InvalidIStockCollection /v3/videos/{id}: get: tags: - Videos summary: Get metadata for a single video by supplying one video id description: "Use this endpoint to return detailed video metadata for the specified video id.\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 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](http://developers.gettyimages.com/en/authorization-faq.html) for more information on authorization tokens, and our [Authorization Workflows](https://github.com/gettyimages/gettyimages-api/blob/master/OAuth2Workflow.md) for code examples of getting a token.\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 response 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 detailed 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 \"download_sizes\",\n \"era\",\n \"event_ids\",\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 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.\n\nThe URI provided is subject to change at any time and must be used as-is with no modification.\n\n```\n{\n \"display_sizes\": [\n {\n \"is_watermarked\": ,\n \"name\": \"comp\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"preview\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"thumb\",\n \"uri\": \"\"\n }\n ],\n \"key_frames\": [\n {\n \"uri\": \"\"\n },\n {\n \"uri\": \"\"\n },\n {\n \"uri\": \"\"\n },\n {\n \"uri\": \"\"\n },\n {\n \"uri\": \"\"\n }\n ]\n}\n```\n\n## Request Usage Considerations\n\n- Specifying the \"entity_details\" response field can have significant performance implications. The field should be used only when necessary.\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: A video id. For more than one video please use the /v3/video endpoint. required: true schema: type: string description: A video id. For more than one video please use the /v3/video endpoint. nullable: true - 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/VideoDetailFieldValues' description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes returned by ''download_sizes'' field is an estimate.' nullable: true responses: '200': description: OK '400': description: InvalidParameterValue '401': description: AuthorizationTokenRequired '403': description: UnauthorizedDisplaySize '404': description: VideosNotFound '500': description: InvalidIStockCollection /v3/videos/{id}/downloadhistory: get: tags: - Videos summary: Returns information about a customer's download history for a specific asset description: '' 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: A video id. required: true schema: type: string description: A video id. nullable: true - name: company_downloads in: query description: "If specified, returns the list of previously downloaded videos for all users in your company.\r\n Your account must be enabled for this functionality. Contact your Getty Images account rep for more information. Default is false." schema: type: boolean description: "If specified, returns the list of previously downloaded videos for all users in your company.\r\n Your account must be enabled for this functionality. Contact your Getty Images account rep for more information. Default is false." responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AssetDownloadHistoryResults' '400': description: Bad request '401': description: AuthorizationTokenRequired '403': description: UnauthorizedDisplaySize '404': description: VideosNotFound '500': description: InvalidIStockCollection /v3/videos/{id}/same-series: get: tags: - Videos summary: Retrieve creative videos from the same series description: "This endpoint will provide the list of videos, if any exist, from the same series as the specified creative asset id. These images are typically from the same photo shoot. This functionality will not work for editorial assets.\n\nYou'll need an API key and access token to use this resource.\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 response 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 detailed 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 \"download_sizes\",\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 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.\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\": ,\n \"name\": \"comp\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"preview\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"thumb\",\n \"uri\": \"\"\n }\n ]\n ]\n}\n```\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: Identifies an existing video required: true schema: type: string description: Identifies an existing video nullable: true - 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/AssociatedVideoDetailFieldValues' description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes returned by ''download_sizes'' field is an estimate.' 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 responses: '200': description: OK '400': description: InvalidParameterValue '401': description: AuthorizationTokenRequired '403': description: UnauthorizedDisplaySize '404': description: VideosNotFound '500': description: InvalidIStockCollection /v3/videos/{id}/similar: get: tags: - Videos summary: Retrieve similar videos description: "This endpoint will provide a list of videos that are similar to the specified asset id.\n\nYou'll need an API key and access token to use this resource.\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 response 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 detailed 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 \"download_sizes\",\n \"era\",\n \"event_ids\",\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 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.\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\": ,\n \"name\": \"comp\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"preview\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"thumb\",\n \"uri\": \"\"\n }\n ]\n ]\n}\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: A video id. required: true schema: type: string description: A video id. nullable: true - 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/AssociatedVideoDetailFieldValues' description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes returned by ''download_sizes'' field is an estimate.' 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 responses: '200': description: OK '400': description: InvalidParameterValue '401': description: AuthorizationTokenRequired '403': description: UnauthorizedDisplaySize '404': description: VideosNotFound '500': description: InvalidIStockCollection components: schemas: SearchFacetsResponse: type: object properties: specific_people: type: array items: $ref: '#/components/schemas/SpecificPeople' nullable: true events: type: array items: $ref: '#/components/schemas/FacetEvent' nullable: true locations: type: array items: $ref: '#/components/schemas/Location' nullable: true artists: type: array items: $ref: '#/components/schemas/Artist' nullable: true entertainment: type: array items: $ref: '#/components/schemas/Entertainment' nullable: true additionalProperties: false FacetEvent: type: object properties: id: type: integer format: int32 name: type: string nullable: true date: type: string format: date-time additionalProperties: false VideoFrameRates: enum: - '23.98' - '24' - '25' - '29.97' - '30' - '50' - '59.94' - '60' type: string CompositionsFilterType: enum: - abstract - candid - close_up - copy_space - cut_out - full_frame - full_length - headshot - looking_at_camera - macro - medium_shot - part_of_a_series - portrait - sparse - still_life - three_quarter_length - waist_up - wide_shot type: string CreativeVideosFieldValues: 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 type: string ImageTechniquesFilterType: enum: - realtime - time_lapse - slow_motion - color - black_and_white - animation - selective_focus type: string ReferralDestination: type: object properties: site_name: type: string nullable: true uri: type: string nullable: true additionalProperties: false CreativeVideoSortOrder: enum: - best_match - most_popular - newest - random type: string ArtistsVideoSearchFieldValues: enum: - id - allowed_use - alternative_ids - artist - asset_family - asset_type - call_for_image - caption - clip_length - collection_id - collection_code - collection_name - comp - copyright - date_created - date_submitted - detail_set - display_set - editorial_segments - event_ids - graphical_style - keywords - license_model - max_dimensions - orientation - preview - product_types - quality_rank - referral_destinations - summary_set - thumb - title type: string VideoDetailFieldValues: 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 - is_ai_editable - istock_collection - istock_licenses - key_frames - keywords - license_model - mastered_to - max_dimensions - object_name - orientation - originally_shot_on - people - preview - product_types - quality_rank - referral_destinations - shot_speed - source - state_province - summary_set - thumb - title type: string VideoSearchItemDisplaySize: type: object properties: is_watermarked: type: boolean name: type: string nullable: true uri: type: string nullable: true aspect_ratio: type: string nullable: true additionalProperties: false ReleaseStatus: enum: - release_not_important - fully_released type: string EditorialVideoSearchResults: type: object properties: result_count: type: integer format: int32 videos: type: array items: $ref: '#/components/schemas/EditorialVideoSearchItem' nullable: true facets: $ref: '#/components/schemas/SearchFacetsResponse' related_searches: type: array items: $ref: '#/components/schemas/RelatedSearch' nullable: true additionalProperties: false VideoFormatsRequest: enum: - sd - hd - 4k - hd_web type: string CollectionsFilterType: enum: - include - exclude type: string RelatedSearch: type: object properties: phrase: type: string nullable: true url: type: string nullable: true additionalProperties: false CreativeVideoSearchItem: type: object properties: id: type: string nullable: true allowed_use: $ref: '#/components/schemas/AllowedUse' artist: type: string nullable: true asset_family: type: string nullable: true caption: type: string nullable: true clip_length: type: string nullable: true collection_id: type: integer format: int32 nullable: true collection_code: type: string nullable: true collection_name: type: string nullable: true color_type: type: string nullable: true copyright: type: string nullable: true date_created: type: string format: date-time nullable: true display_sizes: type: array items: $ref: '#/components/schemas/VideoSearchItemDisplaySize' nullable: true download_product: type: string nullable: true era: type: string nullable: true event_ids: type: array items: type: integer format: int32 nullable: true keywords: type: array items: $ref: '#/components/schemas/Keyword' nullable: true largest_downloads: type: array items: $ref: '#/components/schemas/Download' nullable: true license_model: type: string nullable: true mastered_to: type: string nullable: true originally_shot_on: type: string nullable: true product_types: type: array items: type: string nullable: true referral_destinations: type: array items: $ref: '#/components/schemas/ReferralDestination' nullable: true shot_speed: type: string nullable: true title: type: string nullable: true istock_licenses: type: array items: $ref: '#/components/schemas/IStockLicense' nullable: true additionalProperties: false AllowedUse: type: object properties: how_can_i_use_it: type: string description: Indicates how the asset can be used nullable: true release_info: type: string description: Indicates release status nullable: true usage_restrictions: type: array items: type: string description: Indicates asset usage restriction, if any nullable: true additionalProperties: false Location: type: object properties: id: type: integer format: int32 name: type: string nullable: true additionalProperties: false AssetDownloadHistoryResults: type: object properties: id: type: string nullable: true downloads: nullable: true additionalProperties: false VideoOrientationRequest: enum: - horizontal - vertical type: string VideoAspectRatioFilterType: enum: - '16:9' - '9:16' - '3:4' - '4:3' - '4:5' - '2:1' - '17:9' - '9:17' type: string PremiumAccessDownloadData: type: object properties: download_notes: type: string nullable: true project_code: type: string nullable: true additionalProperties: false Entertainment: type: object properties: id: type: integer format: int32 name: type: string nullable: true additionalProperties: false Download: type: object properties: product_id: type: string nullable: true product_type: type: string nullable: true uri: type: string nullable: true agreement_name: type: string nullable: true additionalProperties: false EditorialVideoType: enum: - raw - produced type: string AffiliateVideo: type: object properties: id: type: string nullable: true title: type: string nullable: true caption: type: string nullable: true preview_urls: $ref: '#/components/schemas/AffiliateVideoUrls' destination_url: type: string nullable: true clip_length: type: string nullable: true additionalProperties: false IStockLicense: type: object properties: license_type: $ref: '#/components/schemas/AssetLicenseName' credits: type: integer format: int32 additionalProperties: false AffiliateVideoSearchResponse: type: object properties: videos: type: array items: $ref: '#/components/schemas/AffiliateVideo' nullable: true auto_corrections: $ref: '#/components/schemas/AutoCorrections' additionalProperties: false CreateVideoSearchFacetsFields: enum: - artists - locations type: string LicenseModelVideoRequest: enum: - rightsready - royaltyfree type: string Keyword: type: object properties: keyword_id: type: string nullable: true text: type: string nullable: true type: type: string nullable: true relevance: type: integer format: int32 nullable: true entity_uris: type: array items: type: string nullable: true entity_types: type: array items: type: string nullable: true additionalProperties: false EditorialVideoSearchItem: type: object properties: source: type: string nullable: true id: type: string nullable: true allowed_use: $ref: '#/components/schemas/AllowedUse' artist: type: string nullable: true asset_family: type: string nullable: true caption: type: string nullable: true clip_length: type: string nullable: true collection_id: type: integer format: int32 nullable: true collection_code: type: string nullable: true collection_name: type: string nullable: true color_type: type: string nullable: true copyright: type: string nullable: true date_created: type: string format: date-time nullable: true display_sizes: type: array items: $ref: '#/components/schemas/VideoSearchItemDisplaySize' nullable: true download_product: type: string nullable: true era: type: string nullable: true event_ids: type: array items: type: integer format: int32 nullable: true keywords: type: array items: $ref: '#/components/schemas/Keyword' nullable: true largest_downloads: type: array items: $ref: '#/components/schemas/Download' nullable: true license_model: type: string nullable: true mastered_to: type: string nullable: true originally_shot_on: type: string nullable: true product_types: type: array items: type: string nullable: true referral_destinations: type: array items: $ref: '#/components/schemas/ReferralDestination' nullable: true shot_speed: type: string nullable: true title: type: string nullable: true istock_licenses: type: array items: $ref: '#/components/schemas/IStockLicense' nullable: true additionalProperties: false ViewpointsFilterType: enum: - lockdown - panning - tracking_shot - aerial_view - high_angle_view - low_angle_view - tilt - point_of_view type: string AutoCorrections: type: object properties: phrase: type: string nullable: true additionalProperties: false EthnicityFilterType: enum: - black - white - east_asian - hispanic_latinx - japanese - middle_eastern - multiracial_person - multiethnic_group - native_american_first_nations - pacific_islander - south_asian - southeast_asian type: string EditorialVideosFieldValues: 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 - editorial_segments - era - event_ids - 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 - source - summary_set - thumb - title - istock_licenses type: string SpecificPeople: type: object properties: id: type: integer format: int32 name: type: string nullable: true additionalProperties: false AffiliateVideoUrls: type: object properties: small_still: type: string nullable: true medium_still: type: string nullable: true large_still: type: string nullable: true small_motion: type: string nullable: true large_motion: type: string nullable: true additionalProperties: false CreativeVideoSearchResults: type: object properties: result_count: type: integer format: int32 videos: type: array items: $ref: '#/components/schemas/CreativeVideoSearchItem' nullable: true facets: $ref: '#/components/schemas/SearchFacetsResponse' auto_corrections: $ref: '#/components/schemas/AutoCorrections' related_searches: type: array items: $ref: '#/components/schemas/RelatedSearch' nullable: true additionalProperties: false EditorialVideoSearchFacetsFields: enum: - artists - events - locations - specific_people type: string ProductTypeForDownloads: enum: - easyaccess - editorialsubscription - imagepack - premiumaccess - royaltyfreesubscription - creditpack - aigen type: string Artist: type: object properties: name: type: string nullable: true additionalProperties: false AgeOfPeopleFilterType: 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 type: string AssociatedVideoDetailFieldValues: 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 - editorial_segments - entity_details - era - event_ids - id - istock_collection - keywords - largest_downloads - license_model - mastered_to - orientation - originally_shot_on - preview - product_types - quality_rank - referral_destinations - shot_speed - source - summary_set - thumb - title - istock_licenses type: string AssetLicenseName: enum: - Standard - Multiseat - Unlimited - Resale - Indemnification type: string NumberOfPeopleFilterType: enum: - none - one - two - group type: string SortOrder: enum: - best_match - most_popular - newest - oldest - random type: string securitySchemes: Api-Key: type: apiKey name: Api-Key in: header OAuth2: type: oauth2 flows: password: tokenUrl: https://api.gettyimages.com/v4/oauth2/token refreshUrl: https://api.gettyimages.com/v4/oauth2/token scopes: {} clientCredentials: tokenUrl: https://api.gettyimages.com/v4/oauth2/token scopes: {} authorizationCode: authorizationUrl: https://api.gettyimages.com/v4/oauth2/auth tokenUrl: https://api.gettyimages.com/v4/oauth2/token refreshUrl: https://api.gettyimages.com/v4/oauth2/token scopes: {}