Getty Images Series API

openapi: 3.0.1
info:
  title: Getty Images Series 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: Series
paths:
  /v3/images/{id}/same-series:
    get:
      tags:
      - Series
      summary: Retrieve creative images from the same series
      description: "This endpoint will provide the list of images, 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\nsearch 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 \ndetailed 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 \nthat are most frequently used to build a UI displaying search results. The following fields are provided for every image 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    \"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```\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 image
        required: true
        schema:
          type: string
          description: Identifies an existing image
          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/ImagesFieldValues'
          description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes, height, and width returned by ''download_sizes'' field are estimates.'
          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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageSearchItemSearchResults'
        '400':
          description: InvalidParameterValue
        '401':
          description: AuthorizationTokenRequired
        '403':
          description: UnauthorizedDisplaySize
        '404':
          description: ImageNotFound
        '500':
          description: InvalidIStockCollection
  /v3/videos/{id}/same-series:
    get:
      tags:
      - Series
      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\": <boolean>,\n                \"name\": \"comp\",\n                \"uri\": \"<link>\"\n            },\n            {\n                \"is_watermarked\": <boolean>,\n                \"name\": \"preview\",\n                \"uri\": \"<link>\"\n            },\n            {\n                \"is_watermarked\": <boolean>,\n                \"name\": \"thumb\",\n                \"uri\": \"<link>\"\n            }\n        ]\n    ]\n}\n```\n"
      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
components:
  schemas:
    MaxDimensions:
      type: object
      properties:
        height:
          type: integer
          format: int32
        width:
          type: integer
          format: int32
      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
    ImageSearchItem:
      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
        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
        istock_licenses:
          type: array
          items:
            $ref: '#/components/schemas/IStockLicense'
          nullable: true
      additionalProperties: false
    IStockLicense:
      type: object
      properties:
        license_type:
          $ref: '#/components/schemas/AssetLicenseName'
        credits:
          type: integer
          format: int32
      additionalProperties: false
    RelatedSearch:
      type: object
      properties:
        phrase:
          type: string
          nullable: true
        url:
          type: string
          nullable: true
      additionalProperties: false
    ReferralDestination:
      type: object
      properties:
        site_name:
          type: string
          nullable: true
        uri:
          type: string
          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
    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
    ImageSearchItemDisplaySize:
      type: object
      properties:
        is_watermarked:
          type: boolean
        name:
          type: string
          nullable: true
        uri:
          type: string
          nullable: true
      additionalProperties: false
    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
    ImageSearchItemSearchResults:
      type: object
      properties:
        result_count:
          type: integer
          format: int32
        images:
          type: array
          items:
            $ref: '#/components/schemas/ImageSearchItem'
          nullable: true
        related_searches:
          type: array
          items:
            $ref: '#/components/schemas/RelatedSearch'
          nullable: true
      additionalProperties: false
    AssetLicenseName:
      enum:
      - Standard
      - Multiseat
      - Unlimited
      - Resale
      - Indemnification
      type: string
    ImagesFieldValues:
      enum:
      - accessrestriction
      - 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
      - entity_details
      - event_ids
      - graphical_style
      - id
      - istock_collection
      - keywords
      - largest_downloads
      - license_model
      - max_dimensions
      - orientation
      - people
      - preview
      - product_types
      - quality_rank
      - referral_destinations
      - summary_set
      - thumb
      - title
      - uri_oembed
      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: {}