openapi: 3.0.1
info:
  title: Getty Images Editorial 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: Editorial
paths:
  /v3/search/images/editorial:
    get:
      tags:
      - Editorial
      summary: Search for editorial images only
      description: "Use this endpoint to search our editorial stock photos, illustrations and archival images.  Editorial images represent newsworthy events or illustrate matters of general interest, such as news, sport and entertainment and are generally intended for editorial use.\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.\nTo include your API token in the search request, add it to the headers as a Bearer token (example in curl):\n\n\t-H \"Authorization: Bearer <your-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 image in your result set when you include **summary_set** in your request.\n\n```\n{\n    \"images\": \n    [\n        \"asset_family\",\n        \"caption\",\n        \"collection_code\",\n        \"collection_id\",\n        \"collection_name\",\n        \"display_sizes\": \n        [\n            {\n                \"name\": \"thumb\"\n            }\n        ],\n        \"license_model\",\n        \"max_dimensions\",\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 images. The following fields are provided for every image in your result set when you include **detail_set** in your request.\n\n```\n{\n    \"images\": \n    [\n        \"allowed_use\",\n        \"artist\",\n        \"asset_family\",\n        \"call_for_image\",\n        \"caption\",\n        \"collection_code\",\n        \"collection_id\",\n        \"collection_name\",\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        \"editorial_segments\",\n        \"event_ids\",\n        \"graphical_style\",\n        \"license_model\",\n        \"max_dimensions\",\n        \"orientation\",\n        \"product_types\",\n        \"quality_rank\",\n        \"referral_destinations\",\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 image 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    \"images\":\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```"
      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: Filter based on the age of individuals in an image.
        style: form
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/AgeOfPeopleFilterType'
          description: Filter based on the age of individuals in an image.
          nullable: true
      - name: artists
        in: query
        description: Search for images by specific artists (free-text, comma-separated list of artists).
        schema:
          type: string
          description: Search for images by specific artists (free-text, comma-separated list of artists).
          nullable: true
      - name: collection_codes
        in: query
        description: Filter by collections (comma-separated list of collection codes). Include or exclude based on collections_filter_type.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
          description: Filter by collections (comma-separated list of collection codes). Include or exclude based on collections_filter_type.
          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 image composition.
        style: form
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/CompositionsFilterType'
          description: Filter based on image 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_segments
        in: query
        description: Return only events with a matching editorial segment.
        style: form
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/EditorialSegmentContract'
          description: Return only events with a matching editorial segment.
          nullable: true
      - name: embed_content_only
        in: query
        description: Restrict search results to embeddable images. The default is false.
        schema:
          type: boolean
          description: Restrict search results to embeddable images. The default is false.
          default: false
      - name: ethnicity
        in: query
        description: Filter search results based on the ethnicity of individuals in an image.
        style: form
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/EthnicityFilterType'
          description: Filter search results based on the ethnicity of individuals in an image.
          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: exclude_keyword_ids
        in: query
        description: Return only images 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 images 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 images 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 images matching the query phrase which also do not contain the requested keyword(s) are returned.
          nullable: true
      - name: fields
        in: query
        description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes, height, and width returned by ''download_sizes'' field are estimates.'
        style: form
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/EditorialImagesFieldValues'
          description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes, height, and width returned by ''download_sizes'' field are estimates.'
          nullable: true
      - name: file_types
        in: query
        description: Return only images having a specific file type.
        style: form
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/SearchFileType'
          description: Return only images having a specific file type.
          nullable: true
      - name: graphical_styles
        in: query
        description: Filter based on graphical style of the image.
        style: form
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/EditorialGraphicalStyle'
          description: Filter based on graphical style of the image.
          nullable: true
      - name: graphical_styles_filter_type
        in: query
        description: Provides searching based on specified graphical style(s). The default is include.
        schema:
          $ref: '#/components/schemas/GraphicalStylesFilterType'
      - 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 images tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those images 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 images tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those images matching the query phrase which also contain the requested keyword(s) are returned.
          nullable: true
      - name: minimum_size
        in: query
        description: Filter based on minimum size requested. The default is x-small.
        schema:
          $ref: '#/components/schemas/TeeShirtSize'
      - name: number_of_people
        in: query
        description: Filter based on the number of people in the image.
        style: form
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/NumberOfPeopleFilterType'
          description: Filter based on the number of people in the image.
          nullable: true
      - name: orientations
        in: query
        description: Return only images with selected aspect ratios.
        style: form
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/ImageOrientationRequest'
          description: Return only images with selected aspect ratios.
          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: Search images using a search phrase.
        schema:
          type: string
          description: Search images using a search phrase.
          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: Return only images associated with specific people (using a comma-delimited list).
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
          description: Return only images associated with specific people (using a comma-delimited list).
          nullable: true
      - name: minimum_quality_rank
        in: query
        description: Filter search results based on minimum quality ranking. Possible values 1, 2, 3 with 1 being best.
        schema:
          type: integer
          description: Filter search results based on minimum quality ranking. Possible values 1, 2, 3 with 1 being best.
          format: int32
          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/EditorialImageSearchFacetsFields'
          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
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EditorialImageSearchResults'
        '400':
          description: InvalidParameterValue
        '401':
          description: AuthorizationTokenRequired
        '403':
          description: UnauthorizedDisplaySize
  /v3/search/videos/editorial:
    get:
      tags:
      - Editorial
      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\": <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```"
      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
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
    ImageOrientationRequest:
      enum:
      - horizontal
      - vertical
      - square
      - panoramic_horizontal
      - panoramic_vertical
      type: string
    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
    EditorialImageSearchResults:
      type: object
      properties:
        result_count:
          type: integer
          format: int32
        images:
          type: array
          items:
            $ref: '#/components/schemas/ImageSearchItemEditorial'
          nullable: true
        related_searches:
          type: array
          items:
            $ref: '#/components/schemas/RelatedSearch'
          nullable: true
      additionalProperties: false
    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
    EditorialSegmentContract:
      enum:
      - archival
      - entertainment
      - news
      - publicity
      - royalty
      - sport
      type: string
    ImageSearchItemDisplaySize:
      type: object
      properties:
        is_watermarked:
          type: boolean
        name:
          type: string
          nullable: true
        uri:
          type: string
          nullable: true
      additionalProperties: false
    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
    MaxDimensions:
      type: object
      properties:
        height:
          type: integer
          format: int32
        width:
          type: integer
          format: int32
      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
    EditorialSource:
      type: object
      properties:
        id:
          type: integer
          format: int32
      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
    GraphicalStylesFilterType:
      enum:
      - include
      - exclude
      type: string
    EditorialImagesFieldValues:
      enum:
      - allowed_use
      - alternative_ids
      - artist
      - asset_family
      - call_for_image
      - caption
      - collection_code
      - collection_id
      - collection_name
      - color_type
      - comp
      - comp_webp
      - copyright
      - date_camera_shot
      - date_created
      - date_submitted
      - detail_set
      - display_set
      - download_product
      - download_sizes
      - editorial_segments
      - editorial_source
      - event_ids
      - graphical_style
      - id
      - keywords
      - largest_downloads
      - license_model
      - max_dimensions
      - orientation
      - people
      - preview
      - product_types
      - quality_rank
      - referral_destinations
      - summary_set
      - thumb
      - title
      - uri_oembed
      type: string
    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
    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
    IStockLicense:
      type: object
      properties:
        license_type:
          $ref: '#/components/schemas/AssetLicenseName'
        credits:
          type: integer
          format: int32
      additionalProperties: false
    EditorialImageSearchFacetsFields:
      enum:
      - artists
      - events
      - locations
      - specific_people
      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
    TeeShirtSize:
      enum:
      - x_small
      - small
      - medium
      - large
      - x_large
      - xx_large
      - vector
      type: string
    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
    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
    ImageSearchItemEditorial:
      type: object
      properties:
        allowed_use:
          $ref: '#/components/schemas/AllowedUse'
        alternative_ids:
          type: object
          additionalProperties:
            type: string
          nullable: true
        artist:
          type: string
          nullable: true
        asset_family:
          type: string
          nullable: true
        call_for_image:
          type: boolean
        caption:
          type: string
          nullable: true
        collection_code:
          type: string
          nullable: true
        collection_id:
          type: integer
          format: int32
          nullable: true
        collection_name:
          type: string
          nullable: true
        color_type:
          type: string
          nullable: true
        copyright:
          type: string
          nullable: true
        date_camera_shot:
          type: string
          format: date-time
          nullable: true
        date_created:
          type: string
          format: date-time
          nullable: true
        display_sizes:
          type: array
          items:
            $ref: '#/components/schemas/ImageSearchItemDisplaySize'
          nullable: true
        download_product:
          type: string
          nullable: true
        editorial_segments:
          type: array
          items:
            type: string
          nullable: true
        editorial_source:
          $ref: '#/components/schemas/EditorialSource'
        event_ids:
          type: array
          items:
            type: integer
            format: int32
          nullable: true
        graphical_style:
          type: string
          nullable: true
        id:
          type: string
          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
        max_dimensions:
          $ref: '#/components/schemas/MaxDimensions'
        orientation:
          type: string
          nullable: true
        people:
          type: array
          items:
            type: string
          nullable: true
        product_types:
          type: array
          items:
            type: string
          nullable: true
        quality_rank:
          type: integer
          format: int32
        referral_destinations:
          type: array
          items:
            $ref: '#/components/schemas/ReferralDestination'
          nullable: true
        title:
          type: string
          nullable: true
        uri_oembed:
          type: string
          nullable: true
      additionalProperties: false
    EditorialGraphicalStyle:
      enum:
      - photography
      - illustration
      - vector
      type: string
    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
    EditorialVideoSearchFacetsFields:
      enum:
      - artists
      - events
      - locations
      - specific_people
      type: string
    SearchFileType:
      enum:
      - eps
      type: string
    Artist:
      type: object
      properties:
        name:
          type: string
          nullable: true
      additionalProperties: false
    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: {}