Overview

Version 2 of the Shutterstock API is a complete rewrite of version 1 with a simpler, cleaner, and more intuitive REST interface and JSON response structure. Below are the key differences between V1 and V2, as well as, examples on how to perform fundamental tasks.


Authentication

While V1 of the API only supported Basic authentication, V2 supports both Basic and OAuth2 auth strategies. Basic auth may be used for routes that do not require a user, such as search and media details; where as OAuth2 is required when performing an action on behalf of a user, such as licensing a piece of media, or retrieving earnings information. For more information about authentication please see the following guide.


Route Changes

V1 V2
GET /resources GET /v2/api-docs or /v2/api-docs/all
GET /test/echo GET /v2/test/validate
GET /images/search GET /v2/images/search
GET /images/[id] GET /v2/images/[id]
GET /images/[id]/similar GET /v2/images/[id]/similar
GET /images/search GET /v2/images/search
GET /categories GET /v2/images/categories
GET /videos/search GET /v2/videos/search
GET /videos/[id] GET /v2/videos/[id]
GET /videos/[id]/similar GET /v2/videos/[id]/similar
GET /videos/search GET /v2/videos/search
GET /categories GET /v2/videos/categories
POST /auth/customer
GET /customer/[username] GET /v2/user
POST /customer/[username] POST /v2/user
GET /customers/[username]/images/subscriptions GET /v2/user/subscriptions
GET /customers/[username]/images/downloads GET /v2/images/licenses
POST /subscriptions/[subscription_id]/images/[image_id]/sizes/[size] POST /v2/images/licenses
POST /subscriptions/[subscription_id]/videos/[image_id]/sizes/[size] POST /v2/videos/licenses
GET /customer/[id]/lightboxes GET /v2/images/collections
GET /customer/[id]/lightboxes/extended GET /v2/images/collections
GET /lightboxes/[id] GET /v2/images/collections[id]
GET /lightboxes/[id]/extended GET /v2/images/collections[id]
GET /lightboxes/[id]/images/[id] GET /v2/images/collections[id]/items/[id]

Searching For Media

The URIs for searching for media have remained the same, however, various query params have been simplified and additional filtering options have been added.

Below are the V1 query params and what they map to in V2.

V1 V2
all [empty query]
commercial_only license=commercial
editorial_only license=editorial
enhanced_only license=enhanced
model_released people_model_released
photographer_name contributor=[name]
pagenumber page
results_per_page per_page
safesearch safe
searchterm query
search_group image_type
sort_method sort
submitter_id contributor=[id]

For more information on searching, including an example request and response, check out the various media search endpoints:


Fetching Media Details

Along with getting individual media details one is now able to fetch multiple items at the same time via the media list endpoints.

For example:

$ curl "https://${client_id}:${client_secret}@api.shutterstock.com/v2/images/123456"
$ curl "https://${client_id}:${client_secret}@api.shutterstock.com/v2/images/567890"

can be combined into a single call:

$ curl "https://${client_id}:${client_secret}@api.shutterstock.com/v2/images?id=123456&id=567890"

For the complete set of media details add the view=full query param.

$ curl "https://${client_id}:${client_secret}@api.shutterstock.com/v2/images?id=123456&id=567890&view=full"

For more information on media details, including an example request and response, check out the various media list endpoints:


Media Licenses

Viewing and licensing media has been greatly simplified in V2.

Viewing Licenses

V1 V2
GET /customers/[username]/images/downloads GET /v2/images/licenses

For more information on viewing existing licenses, including an example request and response, check out the various media licenses endpoints:

Licensing Media

V1 V2
POST /subscriptions/[subscription_id]/images/[image_id]/sizes/[size] POST /v2/images/licenses

For more information on licensing, including an example request and response, check out the various media license endpoints:

Re-Downloading Media

By providing a license ID one can easily re-download a piece media without having to remember the file type and size.

For more information on downloading, including an example request and response, check out the various media download endpoints: