Shutterstock API Reference — images

naftiko: 1.0.0-alpha2
info:
  label: Shutterstock API Reference — images
  description: 'Shutterstock API Reference — images. 23 operations. Lead operation: List images. Self-contained Naftiko capability
    covering one Shutterstock business surface.'
  tags:
  - Shutterstock
  - images
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    SHUTTERSTOCK_API_KEY: SHUTTERSTOCK_API_KEY
capability:
  consumes:
  - type: http
    namespace: shutterstock-images
    baseUri: https://api.shutterstock.com
    description: Shutterstock API Reference — images business capability. Self-contained, no shared references.
    resources:
    - name: v2-images
      path: /v2/images
      operations:
      - name: getimagelist
        method: GET
        description: List images
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: query
          type: array
          description: One or more image IDs
          required: true
        - name: view
          in: query
          type: string
          description: Amount of detail to render in the response
    - name: v2-images-categories
      path: /v2/images/categories
      operations:
      - name: getimagecategories
        method: GET
        description: List image categories
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: language
          in: query
          type: string
          description: Language for the keywords and categories in the response
    - name: v2-images-collections
      path: /v2/images/collections
      operations:
      - name: createlightbox
        method: POST
        description: Create image collections
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: getlightboxlist
        method: GET
        description: List image collections
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: embed
          in: query
          type: array
          description: Which sharing information to include in the response, such as a URL to the collection
        - name: page
          in: query
          type: integer
          description: Page number
        - name: per_page
          in: query
          type: integer
          description: Number of results per page
    - name: v2-images-collections-featured
      path: /v2/images/collections/featured
      operations:
      - name: getfeaturedlightboxlist
        method: GET
        description: List featured image collections
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: embed
          in: query
          type: string
          description: Which sharing information to include in the response, such as a URL to the collection
        - name: type
          in: query
          type: array
          description: The types of collections to return
        - name: asset_hint
          in: query
          type: string
          description: Cover image size
    - name: v2-images-collections-featured-id
      path: /v2/images/collections/featured/{id}
      operations:
      - name: getfeaturedlightbox
        method: GET
        description: Get the details of featured image collections
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Collection ID
          required: true
        - name: embed
          in: query
          type: string
          description: Which sharing information to include in the response, such as a URL to the collection
        - name: asset_hint
          in: query
          type: string
          description: Cover image size
    - name: v2-images-collections-featured-id-items
      path: /v2/images/collections/featured/{id}/items
      operations:
      - name: getfeaturedlightboxitems
        method: GET
        description: Get the contents of featured image collections
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Collection ID
          required: true
        - name: page
          in: query
          type: integer
          description: Page number
        - name: per_page
          in: query
          type: integer
          description: Number of results per page
    - name: v2-images-collections-id
      path: /v2/images/collections/{id}
      operations:
      - name: getlightbox
        method: GET
        description: Get the details of image collections
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Collection ID
          required: true
        - name: embed
          in: query
          type: array
          description: Which sharing information to include in the response, such as a URL to the collection
        - name: share_code
          in: query
          type: string
          description: Code to retrieve a shared collection
      - name: renamelightbox
        method: POST
        description: Rename image collections
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Collection ID
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: deletelightbox
        method: DELETE
        description: Delete image collections
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Collection ID
          required: true
    - name: v2-images-collections-id-items
      path: /v2/images/collections/{id}/items
      operations:
      - name: addlightboxitems
        method: POST
        description: Add images to collections
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Collection ID
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: getlightboxitems
        method: GET
        description: Get the contents of image collections
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Collection ID
          required: true
        - name: share_code
          in: query
          type: string
          description: Code to retrieve the contents of a shared collection
        - name: page
          in: query
          type: integer
          description: Page number
        - name: per_page
          in: query
          type: integer
          description: Number of results per page
      - name: deletelightboxitems
        method: DELETE
        description: Remove images from collections
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Collection ID
          required: true
        - name: item_id
          in: query
          type: array
          description: One or more image IDs to remove from the collection
    - name: v2-images-licenses
      path: /v2/images/licenses
      operations:
      - name: licenseimages
        method: POST
        description: License images
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: subscription_id
          in: query
          type: string
          description: Subscription ID to use to license the image
        - name: format
          in: query
          type: string
          description: Image format
        - name: size
          in: query
          type: string
          description: Image size
        - name: search_id
          in: query
          type: string
          description: Search ID that was provided in the results of an image search
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: getimagelicenselist
        method: GET
        description: List image licenses
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: image_id
          in: query
          type: string
          description: Show licenses for the specified image ID
        - name: license
          in: query
          type: string
          description: Show images that are available with the specified license, such as `standard` or `enhanced`; prepending
            a `-` sign excludes results from that license
        - name: page
          in: query
          type: integer
          description: Page number
        - name: per_page
          in: query
          type: integer
          description: Number of results per page
        - name: sort
          in: query
          type: string
          description: Sort order
        - name: username
          in: query
          type: string
          description: Filter licenses by username of licensee
        - name: start_date
          in: query
          type: string
          description: Show licenses created on or after the specified date
        - name: end_date
          in: query
          type: string
          description: Show licenses created before the specified date
    - name: v2-images-licenses-id-downloads
      path: /v2/images/licenses/{id}/downloads
      operations:
      - name: downloadimage
        method: POST
        description: Download images
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: License ID
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: v2-images-recommendations
      path: /v2/images/recommendations
      operations:
      - name: getimagerecommendations
        method: GET
        description: List recommended images
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: query
          type: array
          description: Image IDs
          required: true
        - name: max_items
          in: query
          type: integer
          description: Maximum number of results returned in the response
        - name: safe
          in: query
          type: boolean
          description: Restrict results to safe images
    - name: v2-images-search
      path: /v2/images/search
      operations:
      - name: searchimages
        method: GET
        description: Search for images
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: added_date
          in: query
          type: string
          description: Show images added on the specified date
        - name: added_date_start
          in: query
          type: string
          description: Show images added on or after the specified date
        - name: aspect_ratio_min
          in: query
          type: number
          description: Show images with the specified aspect ratio or higher, using a positive decimal of the width divided
            by the height, such as 1.7778 for a 16:9 image
        - name: aspect_ratio_max
          in: query
          type: number
          description: Show images with the specified aspect ratio or lower, using a positive decimal of the width divided
            by the height, such as 1.7778 for a 16:9 image
        - name: aspect_ratio
          in: query
          type: number
          description: Show images with the specified aspect ratio, using a positive decimal of the width divided by the height,
            such as 1.7778 for a 16:9 image
        - name: added_date_end
          in: query
          type: string
          description: Show images added before the specified date
        - name: category
          in: query
          type: string
          description: Show images with the specified Shutterstock-defined category; specify a category name or ID
        - name: color
          in: query
          type: string
          description: Specify either a hexadecimal color in the format '4F21EA' or 'grayscale'; the API groups it into one
            of 15 color categories and returns images that primarily us
        - name: contributor
          in: query
          type: array
          description: Show images with the specified contributor names or IDs, allows multiple
        - name: contributor_country
          in: query
          type: array
          description: Show images from contributors in one or more specified countries
        - name: fields
          in: query
          type: string
          description: Fields to display in the response; see the documentation for the fields parameter in the overview section
        - name: height
          in: query
          type: integer
          description: (Deprecated; use height_from and height_to instead) Show images with the specified height
        - name: height_from
          in: query
          type: integer
          description: Show images with the specified height or larger, in pixels
        - name: height_to
          in: query
          type: integer
          description: Show images with the specified height or smaller, in pixels
        - name: image_type
          in: query
          type: array
          description: Show images of the specified type
        - name: keyword_safe_search
          in: query
          type: boolean
          description: Hide results with potentially unsafe keywords
        - name: language
          in: query
          type: string
          description: Set query and result language (uses Accept-Language header if not set)
        - name: license
          in: query
          type: array
          description: Show only images with the specified license
        - name: model
          in: query
          type: array
          description: Show image results with the specified model IDs
        - name: orientation
          in: query
          type: string
          description: Show image results with horizontal or vertical orientation
        - name: page
          in: query
          type: integer
          description: Page number
        - name: per_page
          in: query
          type: integer
          description: Number of results per page
        - name: people_model_released
          in: query
          type: boolean
          description: Show images of people with a signed model release
        - name: people_age
          in: query
          type: string
          description: Show images that feature people of the specified age category
        - name: people_ethnicity
          in: query
          type: array
          description: Show images with people of the specified ethnicities
        - name: people_gender
          in: query
          type: string
          description: Show images with people of the specified gender
        - name: people_number
          in: query
          type: integer
          description: Show images with the specified number of people
        - name: query
          in: query
          type: string
          description: One or more search terms separated by spaces; you can use NOT to filter out images that match a term
        - name: region
          in: query
          type: string
          description: 'Raise or lower search result rankings based on the result''s relevance to a specified region; you
            can provide a country code or an IP address from which the API '
        - name: safe
          in: query
          type: boolean
          description: Enable or disable safe search
        - name: sort
          in: query
          type: string
          description: Sort by
        - name: spellcheck_query
          in: query
          type: boolean
          description: Spellcheck the search query and return results on suggested spellings
        - name: view
          in: query
          type: string
          description: Amount of detail to render in the response
        - name: width
          in: query
          type: integer
          description: (Deprecated; use width_from and width_to instead) Show images with the specified width
        - name: width_from
          in: query
          type: integer
          description: Show images with the specified width or larger, in pixels
        - name: width_to
          in: query
          type: integer
          description: Show images with the specified width or smaller, in pixels
    - name: v2-images-search-suggestions
      path: /v2/images/search/suggestions
      operations:
      - name: getimagesuggestions
        method: GET
        description: Get suggestions for a search term
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: query
          in: query
          type: string
          description: Search term for which you want keyword suggestions
          required: true
        - name: limit
          in: query
          type: integer
          description: Limit the number of suggestions
      - name: postimageentities
        method: POST
        description: Get keywords from text
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: v2-images-updated
      path: /v2/images/updated
      operations:
      - name: getupdatedimages
        method: GET
        description: List updated images
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: type
          in: query
          type: array
          description: Show images that were added, deleted, or edited; by default, the endpoint returns images that were
            updated in any of these ways
        - name: start_date
          in: query
          type: string
          description: Show images updated on or after the specified date
        - name: end_date
          in: query
          type: string
          description: Show images updated before the specified date
        - name: interval
          in: query
          type: string
          description: Show images updated in the specified time period, where the time period is an interval (like SQL INTERVAL)
            such as 1 DAY, 6 HOUR, or 30 MINUTE; the default is 1
        - name: page
          in: query
          type: integer
          description: Page number
        - name: per_page
          in: query
          type: integer
          description: Number of results per page
        - name: sort
          in: query
          type: string
          description: Sort order
    - name: v2-images-id
      path: /v2/images/{id}
      operations:
      - name: getimage
        method: GET
        description: Get details about images
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Image ID
          required: true
        - name: language
          in: query
          type: string
          description: Language for the keywords and categories in the response
        - name: view
          in: query
          type: string
          description: Amount of detail to render in the response
    - name: v2-images-id-similar
      path: /v2/images/{id}/similar
      operations:
      - name: getsimilarimages
        method: GET
        description: List similar images
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Image ID
          required: true
        - name: language
          in: query
          type: string
          description: Language for the keywords and categories in the response
        - name: page
          in: query
          type: integer
          description: Page number
        - name: per_page
          in: query
          type: integer
          description: Number of results per page
        - name: view
          in: query
          type: string
          description: Amount of detail to render in the response
    authentication:
      type: bearer
      token: '{{env.SHUTTERSTOCK_API_KEY}}'
  exposes:
  - type: rest
    namespace: shutterstock-images-rest
    port: 8080
    description: REST adapter for Shutterstock API Reference — images. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/v2/images
      name: v2-images
      description: REST surface for v2-images.
      operations:
      - method: GET
        name: getimagelist
        description: List images
        call: shutterstock-images.getimagelist
        with:
          id: rest.id
          view: rest.view
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/images/categories
      name: v2-images-categories
      description: REST surface for v2-images-categories.
      operations:
      - method: GET
        name: getimagecategories
        description: List image categories
        call: shutterstock-images.getimagecategories
        with:
          language: rest.language
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/images/collections
      name: v2-images-collections
      description: REST surface for v2-images-collections.
      operations:
      - method: POST
        name: createlightbox
        description: Create image collections
        call: shutterstock-images.createlightbox
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: getlightboxlist
        description: List image collections
        call: shutterstock-images.getlightboxlist
        with:
          embed: rest.embed
          page: rest.page
          per_page: rest.per_page
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/images/collections/featured
      name: v2-images-collections-featured
      description: REST surface for v2-images-collections-featured.
      operations:
      - method: GET
        name: getfeaturedlightboxlist
        description: List featured image collections
        call: shutterstock-images.getfeaturedlightboxlist
        with:
          embed: rest.embed
          type: rest.type
          asset_hint: rest.asset_hint
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/images/collections/featured/{id}
      name: v2-images-collections-featured-id
      description: REST surface for v2-images-collections-featured-id.
      operations:
      - method: GET
        name: getfeaturedlightbox
        description: Get the details of featured image collections
        call: shutterstock-images.getfeaturedlightbox
        with:
          id: rest.id
          embed: rest.embed
          asset_hint: rest.asset_hint
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/images/collections/featured/{id}/items
      name: v2-images-collections-featured-id-items
      description: REST surface for v2-images-collections-featured-id-items.
      operations:
      - method: GET
        name: getfeaturedlightboxitems
        description: Get the contents of featured image collections
        call: shutterstock-images.getfeaturedlightboxitems
        with:
          id: rest.id
          page: rest.page
          per_page: rest.per_page
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/images/collections/{id}
      name: v2-images-collections-id
      description: REST surface for v2-images-collections-id.
      operations:
      - method: GET
        name: getlightbox
        description: Get the details of image collections
        call: shutterstock-images.getlightbox
        with:
          id: rest.id
          embed: rest.embed
          share_code: rest.share_code
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: renamelightbox
        description: Rename image collections
        call: shutterstock-images.renamelightbox
        with:
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: deletelightbox
        description: Delete image collections
        call: shutterstock-images.deletelightbox
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/images/collections/{id}/items
      name: v2-images-collections-id-items
      description: REST surface for v2-images-collections-id-items.
      operations:
      - method: POST
        name: addlightboxitems
        description: Add images to collections
        call: shutterstock-images.addlightboxitems
        with:
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: getlightboxitems
        description: Get the contents of image collections
        call: shutterstock-images.getlightboxitems
        with:
          id: rest.id
          share_code: rest.share_code
          page: rest.page
          per_page: rest.per_page
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: deletelightboxitems
        description: Remove images from collections
        call: shutterstock-images.deletelightboxitems
        with:
          id: rest.id
          item_id: rest.item_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/images/licenses
      name: v2-images-licenses
      description: REST surface for v2-images-licenses.
      operations:
      - method: POST
        name: licenseimages
        description: License images
        call: shutterstock-images.licenseimages
        with:
          subscription_id: rest.subscription_id
          format: rest.format
          size: rest.size
          search_id: rest.search_id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: getimagelicenselist
        description: List image licenses
        call: shutterstock-images.getimagelicenselist
        with:
          image_id: rest.image_id
          license: rest.license
          page: rest.page
          per_page: rest.per_page
          sort: rest.sort
          username: rest.username
          start_date: rest.start_date
          end_date: rest.end_date
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/images/licenses/{id}/downloads
      name: v2-images-licenses-id-downloads
      description: REST surface for v2-images-licenses-id-downloads.
      operations:
      - method: POST
        name: downloadimage
        description: Download images
        call: shutterstock-images.downloadimage
        with:
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/images/recommendations
      name: v2-images-recommendations
      description: REST surface for v2-images-recommendations.
      operations:
      - method: GET
        name: getimagerecommendations
        description: List recommended images
        call: shutterstock-images.getimagerecommendations
        with:
          id: rest.id
          max_items: rest.max_items
          safe: rest.safe
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/images/search
      name: v2-images-search
      description: REST surface for v2-images-search.
      operations:
      - method: GET
        name: searchimages
        description: Search for images
        call: shutterstock-images.searchimages
        with:
          added_date: rest.added_date
          added_date_start: rest.added_date_start
          aspect_ratio_min: rest.aspect_ratio_min
          aspect_ratio_max: rest.aspect_ratio_max
          aspect_ratio: rest.aspect_ratio
          added_date_end: rest.added_date_end
          category: rest.category
          color: rest.color
          contributor: rest.contributor
          contributor_country: rest.contributor_country
          fields: rest.fields
          height: rest.height
          height_from: rest.height_from
          height_to: rest.height_to
          image_type: rest.image_type
          keyword_safe_search: rest.keyword_safe_search
          language: rest.language
          license: rest.license
          model: rest.model
          orientation: rest.orientation
          page: rest.page
          per_page: rest.per_page
          people_model_released: rest.people_model_released
          people_age: rest.people_age
          people_ethnicity: rest.people_ethnicity
          people_gender: rest.people_gender
          people_number: rest.people_number
          query: rest.query
          region: rest.region
          safe: rest.safe
          sort: rest.sort
          spellcheck_query: rest.spellcheck_query
          view: rest.view
          width: rest.width
          width_from: rest.width_from
          width_to: rest.width_to
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/images/search/suggestions
      name: v2-images-search-suggestions
      description: REST surface for v2-images-search-suggestions.
      operations:
      - method: GET
        name: getimagesuggestions
        description: Get suggestions for a search term
        call: shutterstock-images.getimagesuggestions
        with:
          query: rest.query
          limit: rest.limit
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: postimageentities
        description: Get keywords from text
        call: shutterstock-images.postimageentities
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/images/updated
      name: v2-images-updated
      description: REST surface for v2-images-updated.
      operations:
      - method: GET
        name: getupdatedimages
        description: List updated images
      

# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/shutterstock/refs/heads/main/capabilities/shutterstock-images.yaml