shutterstock-api

Official JavaScript SDK client for the Shutterstock API

The Shutterstock public API provides access to Shutterstock's library of media, as well as information about customers' accounts and the contributors that provide the media. This SDK provides classes for JavaScript and Node.js that you can use to access the API from your applications. These classes call the API in the same way that direct REST calls do. You can use this SDK to search for media, get information about media and about collections, and (if your subscription permits) license and download media. This is the official SDK provided by Shutterstock for its API.

• API version: 1.1.41

References

• For more information about the Shutterstock public API, see https://www.shutterstock.com/developers/documentation.
• For reference information about the endpoints that this SDK calls, see the API reference.
• To provide feedback or bug reports about the API and this SDK, see https://api-feedback.shutterstock.com.
• For the status of the API, see API status.
• For the source code, see https://github.com/shutterstock/public-api-javascript-sdk.

Subscriptions

To access the API and license media with the SDK, you need an API subscription or a free API account.

API subscriptions are separate from the subscriptions that are available on shutterstock.com. You can use an API subscription to license and download media only with the API; API subscriptions don't work on shutterstock.com. To buy an API subscription or set up a free account, see the pricing page. If you have a subscription from shutterstock.com and want to use it with the API, contact us.

Applications

To access the REST API you need an application, which represents the application, program, or computer commands that are accessing the API. To use the API, you need the application's consumer key and consumer secret, which are shown on the https://www.shutterstock.com/account/developers/apps page.

When you have the application's consumer key and consumer secret, you can use them to access the API directly or to request a token that you can use to access the API. For more information on these methods of authentication, see Authentication.

To create an application:

1. Log in at shutterstock.com, go to your account page, and and click Developers.
2. On the Developers page, click Create new app.
3. On the Create New App popup, fill in these fields:
   • App name: Specify any name that describes your application.
   • Callback URL: Specify a comma-separated list of the host names (not full URLs) where your application is running. If you’ve got an application running on a server, use the host name of the server. Otherwise, leave the default host name localhost for testing purposes.
   • Referrer: If you are using referrer authentication, specify a comma-separated list of valid referrer domains. Each item in the list must match one of the callback host names. The API accepts only requests that have an HTTP Referrer header from this list. Otherwise, leave this field blank.
   • Included products: This list shows the API products that the application has access to. To get access to other products, contact your Shutterstock representative, visit the Pricing page or contact us.
   • Company name: The name of your company.
   • Website: Your company's web site.
   • Intended use: Select an option that describes how you will use the API.
   • Description: Describe in detail how the application will use the API.
   • Terms of service: Read an accept the Terms of Service.
4. Click Save.

The new application appears on the My apps page. Each application has a consumer key and a consumer secret. You use this consumer key and consumer secret either to use the API directly with basic authentication or to request a token for OAuth authentication; see Authentication. Do not share your key and secret, because they can be used to access your account through the API.

Products

Each application has access to one or more API products. These products control the level of access that the application has to the API and the Shutterstock media library. These products are separate from the subscriptions that control how many assets you can license and download.

If you create an application without buying an API subscription first, the application uses the free API product, which is labeled as the "Self Serve" product. Applications that use this free API product can search and view media but not license or download media. If you have a paid API subscription, your applications use an API product with additional access to license and download media, within the limitations of the subscription. Other products include access to computer vision and editorial endpoints.

To tell which API products your application is using, open your applications, expand your application, and go to its Details tab.

Installation

npm or yarn

To install the SDK as a module with npm or yarn, run one of the following commands:

npm install shutterstock-api --save

yarn add shutterstock-api

Authentication

Authentication in the SDK works the same way as in the API:

All endpoints in the Shutterstock API require authentication. The API accepts HTTP basic authentication for some endpoints and OAuth authentication for all endpoints.

In the reference information for each SDK method (see Documentation for methods or the API reference, each endpoint is labeled with the types of authentication it accepts and the OAuth scopes it requires, if any. In general, HTTP basic authentication is sufficient for search queries and for getting information about pieces of media. The API requires OAuth authentication for actions that require customers to log in to shutterstock.com, such as licensing and downloading media.

For more information about authenticating to the API, see Authentication in the API reference.

Basic authentication

In HTTP basic authentication (also known as basic authentication), you pass your application's consumer key and secret key to the SDK along with the request. To get the consumer key and secret key for your application, go to https://www.shutterstock.com/account/developers/apps and open the information for your application. The following example uses the variables applicationClientId and applicationClientSecret for the application's consumer key and secret.

const sstk = require('shutterstock-api');

sstk.setBasicAuth(applicationClientId, applicationClientSecret);

const api = new sstk.ImagesApi();

OAuth authentication

In this type of authentication, you use an application and an individual user's login credentials to obtain a token. For instructions on how to get a token, see OAuth authentication on the Shutterstock developer portal.

When you have the token, use it to configure the API client as in the following example, which assumes that your token is in the environment variable SHUTTERSTOCK_API_TOKEN:

const sstk = require('shutterstock-api');

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const api = new sstk.ImagesApi();

OAuth scopes

Most endpoints require an access token with one or more scopes, or permissions. You can see the scopes that each method requires in the reference information for each method.

The following list shows the available scopes.

• licenses.create: Grant the ability to download and license media on behalf of the user.
• purchases.view: Grant read-only access to a user's purchase history.
• licenses.view: Grant read-only access to a user's licenses.
• collections.edit: Grant the ability to create new collections, edit a collection, and modify the contents of a collection
• collections.view: Grant read-only access to a collection and its contents.

Languages

You can provide search keywords in languages other than English by specifying the two-character language code in the language query parameter. If you set this parameter or header, you can also pass category names in that language. The response includes categories and keywords in that language.

For the list of languages that the API accepts, see the Language schema.

Licensing sandbox

To use the licensing sandbox API instead of the main API, use the setSandbox method. For more information on the sandbox API, see Licensing sandbox in the API reference.

const sstk = require('shutterstock-api');

sstk.setSandbox(true);

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const api = new sstk.ImagesApi();

To go back to the main API, call the setSandbox method again and pass false.

sstk.setSandbox(false);

Examples

Follow the installation instructions and use the SDK in your JavaScript code as in these examples.

This example searches for images. The search parameters go in the queryParams variable. The API returns responses as JavaScript objects. The reference information for each method shows the class for the response. In this example, the callback function extracts the image ID, description, and preview link of each search result into an object.

const sstk = require('shutterstock-api');

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const api = new sstk.ImagesApi();

const queryParams = {
  query: 'New York',
  sort: 'popular',
  orientation: 'horizontal'
};

api.searchImages(queryParams)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

The next example requests a license for an image.

For POST requests like this one, you create an object of the appropriate class to pass as the request body. In this case, the shutterstock-api.ImagesApi.licenseImages method accepts a body parameter of the class shutterstock-api.LicenseImageRequest. This parameter is an array of objects of the class shutterstock-api.LicenseImage, each of which has the ID of an image to license. The reference information for each method shows the class for the body parameter.

const sstk = require('shutterstock-api');

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const api = new sstk.ImagesApi();

const imageId = '' // ID of image to license

const imageToLicense = new sstk.LicenseImage(imageId);

const body = new sstk.LicenseImageRequest([imageToLicense]);

const queryParams = {
  subscription_id: process.env.SUBSCRIPTION_ID,
  format: 'jpg',
  size: 'huge'
};

api.licenseImages(body, queryParams)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

Instead of using objects for the body, you can also pass a JavaScript object literal that has the data that the API expects in the body. For information about the body format, see the API reference for the related API endpoint. For example, this licensing request passes information about the images to license in a JavaScript object literal:

const sstk = require('shutterstock-api');

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const imagesApi = new sstk.ImagesApi();

const body = {
  images: [
    {
      image_id: '419235589',
      price: 12.50,
      metadata: {
        customer_id: '12345'
      }
    }
  ]
};

const queryParams = {
  format: 'jpg',
  size: 'huge',
  subscription_id: process.env.SUBSCRIPTION_ID
};

imagesApi.licenseImages(body, queryParams)
  .then(({ data }) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

Errors

The SDK returns the same errors as the API. For information about errors, see Errors in the API reference.

Handle errors in the catch() method following the SDK method. Each error includes a response object that includes an HTTP status field and a text field that has the description of the error.

For example, this example requests an image ID that does not exist. The API returns the HTTP status code 404:

const sstk = require("shutterstock-api");

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const imagesApi = new sstk.ImagesApi();

imagesApi.getImage("123456789")
  .then((data) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error.response.status, error.response.text);
    // 404 '{"message":"Not Found"}'
  });

Contributing

• This SDK is generated at shutterstock/public-api-sdk-generator, please make changes to SDK there.
• Changes to tests can be made directly here.

Tests

To run the tests, you must authenticate with the Shutterstock API, get a token, and put the token in the SHUTTERSTOCK_API_TOKEN environment variable. See Authentication.

$ SHUTTERSTOCK_API_TOKEN="Your API Key"
$ yarn run test

Linting

$ yarn run lint

Documentation for methods

All URIs are relative to https://api.shutterstock.com

Class	Method	HTTP request	Description
shutterstock-api.AudioApi	addTrackCollectionItems	POST /v2/audio/collections/{id}/items	Add audio tracks to collections
shutterstock-api.AudioApi	createTrackCollection	POST /v2/audio/collections	Create audio collections
shutterstock-api.AudioApi	deleteTrackCollection	DELETE /v2/audio/collections/{id}	Delete audio collections
shutterstock-api.AudioApi	deleteTrackCollectionItems	DELETE /v2/audio/collections/{id}/items	Remove audio tracks from collections
shutterstock-api.AudioApi	downloadTracks	POST /v2/audio/licenses/{id}/downloads	Download audio tracks
shutterstock-api.AudioApi	getTrack	GET /v2/audio/{id}	Get details about audio tracks
shutterstock-api.AudioApi	getTrackCollection	GET /v2/audio/collections/{id}	Get the details of audio collections
shutterstock-api.AudioApi	getTrackCollectionItems	GET /v2/audio/collections/{id}/items	Get the contents of audio collections
shutterstock-api.AudioApi	getTrackCollectionList	GET /v2/audio/collections	List audio collections
shutterstock-api.AudioApi	getTrackLicenseList	GET /v2/audio/licenses	List audio licenses
shutterstock-api.AudioApi	getTrackList	GET /v2/audio	List audio tracks
shutterstock-api.AudioApi	licenseTrack	POST /v2/audio/licenses	License audio tracks
shutterstock-api.AudioApi	listGenres	GET /v2/audio/genres	List audio genres
shutterstock-api.AudioApi	listInstruments	GET /v2/audio/instruments	List audio instruments
shutterstock-api.AudioApi	listMoods	GET /v2/audio/moods	List audio moods
shutterstock-api.AudioApi	renameTrackCollection	POST /v2/audio/collections/{id}	Rename audio collections
shutterstock-api.AudioApi	searchTracks	GET /v2/audio/search	Search for tracks
shutterstock-api.CatalogApi	addToCollection	POST /v2/catalog/collections/{collection_id}/items	Add items to catalog collections
shutterstock-api.CatalogApi	createCollection	POST /v2/catalog/collections	Create catalog collections
shutterstock-api.CatalogApi	deleteCollection	DELETE /v2/catalog/collections/{collection_id}	Delete catalog collections
shutterstock-api.CatalogApi	deleteFromCollection	DELETE /v2/catalog/collections/{collection_id}/items	Remove items from catalog collection
shutterstock-api.CatalogApi	getCollections	GET /v2/catalog/collections	List catalog collections
shutterstock-api.CatalogApi	searchCatalog	GET /v2/catalog/search	Search catalogs for assets
shutterstock-api.CatalogApi	updateCollection	PATCH /v2/catalog/collections/{collection_id}	Update collection metadata
shutterstock-api.ComputerVisionApi	getKeywords	GET /v2/cv/keywords	List suggested keywords
shutterstock-api.ComputerVisionApi	getSimilarImages	GET /v2/cv/similar/images	List similar images
shutterstock-api.ComputerVisionApi	getSimilarVideos	GET /v2/cv/similar/videos	List similar videos
shutterstock-api.ComputerVisionApi	uploadEphemeralImage	POST /v2/images	Upload ephemeral images
shutterstock-api.ComputerVisionApi	uploadImage	POST /v2/cv/images	Upload images
shutterstock-api.ContributorsApi	getContributor	GET /v2/contributors/{contributor_id}	Get details about a single contributor
shutterstock-api.ContributorsApi	getContributorCollectionItems	GET /v2/contributors/{contributor_id}/collections/{id}/items	Get the items in contributors' collections
shutterstock-api.ContributorsApi	getContributorCollections	GET /v2/contributors/{contributor_id}/collections/{id}	Get details about contributors' collections
shutterstock-api.ContributorsApi	getContributorCollectionsList	GET /v2/contributors/{contributor_id}/collections	List contributors' collections
shutterstock-api.ContributorsApi	getContributorList	GET /v2/contributors	Get details about multiple contributors
shutterstock-api.EditorialImagesApi	getEditorialCategories	GET /v2/editorial/categories	(Deprecated) List editorial categories
shutterstock-api.EditorialImagesApi	getEditorialImage	GET /v2/editorial/images/{id}	Get editorial content details
shutterstock-api.EditorialImagesApi	getEditorialImageLicenseList	GET /v2/editorial/images/licenses	List editorial image licenses
shutterstock-api.EditorialImagesApi	getEditorialImageLivefeed	GET /v2/editorial/images/livefeeds/{id}	Get editorial livefeed
shutterstock-api.EditorialImagesApi	getEditorialImageLivefeedItems	GET /v2/editorial/images/livefeeds/{id}/items	Get editorial livefeed items
shutterstock-api.EditorialImagesApi	getEditorialImageLivefeedList	GET /v2/editorial/images/livefeeds	Get editorial livefeed list
shutterstock-api.EditorialImagesApi	getEditorialImage_0	GET /v2/editorial/{id}	(Deprecated) Get editorial content details
shutterstock-api.EditorialImagesApi	getEditorialLivefeed	GET /v2/editorial/livefeeds/{id}	(Deprecated) Get editorial livefeed
shutterstock-api.EditorialImagesApi	getEditorialLivefeedItems	GET /v2/editorial/livefeeds/{id}/items	(Deprecated) Get editorial livefeed items
shutterstock-api.EditorialImagesApi	getEditorialLivefeedList	GET /v2/editorial/livefeeds	(Deprecated) Get editorial livefeed list
shutterstock-api.EditorialImagesApi	getUpdatedEditorialImage	GET /v2/editorial/updated	(Deprecated) List updated content
shutterstock-api.EditorialImagesApi	getUpdatedEditorialImages	GET /v2/editorial/images/updated	List updated content
shutterstock-api.EditorialImagesApi	licenseEditorialImage	POST /v2/editorial/licenses	(Deprecated) License editorial content
shutterstock-api.EditorialImagesApi	licenseEditorialImages	POST /v2/editorial/images/licenses	License editorial content
shutterstock-api.EditorialImagesApi	listEditorialImageCategories	GET /v2/editorial/images/categories	List editorial categories
shutterstock-api.EditorialImagesApi	listEditorialImages	GET /v2/editorial/images	list editorial image details
shutterstock-api.EditorialImagesApi	searchEditorial	GET /v2/editorial/search	(Deprecated) Search editorial content
shutterstock-api.EditorialImagesApi	searchEditorialImages	GET /v2/editorial/images/search	Search editorial images
shutterstock-api.EditorialVideoApi	getEditorialVideo	GET /v2/editorial/videos/{id}	Get editorial video content details
shutterstock-api.EditorialVideoApi	getEditorialVideoLicenseList	GET /v2/editorial/videos/licenses	List editorial video licenses
shutterstock-api.EditorialVideoApi	licenseEditorialVideo	POST /v2/editorial/videos/licenses	License editorial video content
shutterstock-api.EditorialVideoApi	listEditorialVideoCategories	GET /v2/editorial/videos/categories	List editorial video categories
shutterstock-api.EditorialVideoApi	listEditorialVideos	GET /v2/editorial/videos	List editorial videos details by ID list
shutterstock-api.EditorialVideoApi	searchEditorialVideos	GET /v2/editorial/videos/search	Search editorial video content
shutterstock-api.ImagesApi	addImageCollectionItems	POST /v2/images/collections/{id}/items	Add images to collections
shutterstock-api.ImagesApi	bulkSearchImages	POST /v2/bulk_search/images	Run multiple image searches
shutterstock-api.ImagesApi	createImageCollection	POST /v2/images/collections	Create image collections
shutterstock-api.ImagesApi	deleteImageCollection	DELETE /v2/images/collections/{id}	Delete image collections
shutterstock-api.ImagesApi	deleteImageCollectionItems	DELETE /v2/images/collections/{id}/items	Remove images from collections
shutterstock-api.ImagesApi	downloadImage	POST /v2/images/licenses/{id}/downloads	Download images
shutterstock-api.ImagesApi	getFeaturedImageCollection	GET /v2/images/collections/featured/{id}	Get the details of featured image collections
shutterstock-api.ImagesApi	getFeaturedImageCollectionItems	GET /v2/images/collections/featured/{id}/items	Get the contents of featured image collections
shutterstock-api.ImagesApi	getFeaturedImageCollectionList	GET /v2/images/collections/featured	List featured image collections
shutterstock-api.ImagesApi	getImage	GET /v2/images/{id}	Get details about images
shutterstock-api.ImagesApi	getImageCollection	GET /v2/images/collections/{id}	Get the details of image collections
shutterstock-api.ImagesApi	getImageCollectionItems	GET /v2/images/collections/{id}/items	Get the contents of image collections
shutterstock-api.ImagesApi	getImageCollectionList	GET /v2/images/collections	List image collections
shutterstock-api.ImagesApi	getImageKeywordSuggestions	POST /v2/images/search/suggestions	Get keywords from text
shutterstock-api.ImagesApi	getImageLicenseList	GET /v2/images/licenses	List image licenses
shutterstock-api.ImagesApi	getImageList	GET /v2/images	List images
shutterstock-api.ImagesApi	getImageRecommendations	GET /v2/images/recommendations	List recommended images
shutterstock-api.ImagesApi	getImageSuggestions	GET /v2/images/search/suggestions	Get suggestions for a search term
shutterstock-api.ImagesApi	getUpdatedImages	GET /v2/images/updated	List updated images
shutterstock-api.ImagesApi	licenseImages	POST /v2/images/licenses	License images
shutterstock-api.ImagesApi	listImageCategories	GET /v2/images/categories	List image categories
shutterstock-api.ImagesApi	listSimilarImages	GET /v2/images/{id}/similar	List similar images
shutterstock-api.ImagesApi	renameImageCollection	POST /v2/images/collections/{id}	Rename image collections
shutterstock-api.ImagesApi	searchImages	GET /v2/images/search	Search for images
shutterstock-api.SoundEffectsApi	downloadSfx	POST /v2/sfx/licenses/{id}/downloads	Download sound effects
shutterstock-api.SoundEffectsApi	getSfxDetails	GET /v2/sfx/{id}	Get details about sound effects
shutterstock-api.SoundEffectsApi	getSfxLicenseList	GET /v2/sfx/licenses	List sound effects licenses
shutterstock-api.SoundEffectsApi	getSfxListDetails	GET /v2/sfx	List details about sound effects
shutterstock-api.SoundEffectsApi	licensesSFX	POST /v2/sfx/licenses	License sound effects
shutterstock-api.SoundEffectsApi	searchSFX	GET /v2/sfx/search	Search for sound effects
shutterstock-api.TestApi	echo	GET /v2/test	Echo text
shutterstock-api.TestApi	validate	GET /v2/test/validate	Validate input
shutterstock-api.UsersApi	getAccessToken	GET /v2/user/access_token	Get access token details
shutterstock-api.UsersApi	getUser	GET /v2/user	Get user details
shutterstock-api.UsersApi	getUserSubscriptionList	GET /v2/user/subscriptions	List user subscriptions
shutterstock-api.VideosApi	addVideoCollectionItems	POST /v2/videos/collections/{id}/items	Add videos to collections
shutterstock-api.VideosApi	createVideoCollection	POST /v2/videos/collections	Create video collections
shutterstock-api.VideosApi	deleteVideoCollection	DELETE /v2/videos/collections/{id}	Delete video collections
shutterstock-api.VideosApi	deleteVideoCollectionItems	DELETE /v2/videos/collections/{id}/items	Remove videos from collections
shutterstock-api.VideosApi	downloadVideos	POST /v2/videos/licenses/{id}/downloads	Download videos
shutterstock-api.VideosApi	findSimilarVideos	GET /v2/videos/{id}/similar	List similar videos
shutterstock-api.VideosApi	getFeaturedVideoCollection	GET /v2/videos/collections/featured/{id}	Get the details of featured video collections
shutterstock-api.VideosApi	getFeaturedVideoCollectionItems	GET /v2/videos/collections/featured/{id}/items	Get the contents of featured video collections
shutterstock-api.VideosApi	getFeaturedVideoCollectionList	GET /v2/videos/collections/featured	List featured video collections
shutterstock-api.VideosApi	getUpdatedVideos	GET /v2/videos/updated	List updated videos
shutterstock-api.VideosApi	getVideo	GET /v2/videos/{id}	Get details about videos
shutterstock-api.VideosApi	getVideoCollection	GET /v2/videos/collections/{id}	Get the details of video collections
shutterstock-api.VideosApi	getVideoCollectionItems	GET /v2/videos/collections/{id}/items	Get the contents of video collections
shutterstock-api.VideosApi	getVideoCollectionList	GET /v2/videos/collections	List video collections
shutterstock-api.VideosApi	getVideoLicenseList	GET /v2/videos/licenses	List video licenses
shutterstock-api.VideosApi	getVideoList	GET /v2/videos	List videos
shutterstock-api.VideosApi	getVideoSuggestions	GET /v2/videos/search/suggestions	Get suggestions for a search term
shutterstock-api.VideosApi	licenseVideos	POST /v2/videos/licenses	License videos
shutterstock-api.VideosApi	listVideoCategories	GET /v2/videos/categories	List video categories
shutterstock-api.VideosApi	renameVideoCollection	POST /v2/videos/collections/{id}	Rename video collections
shutterstock-api.VideosApi	searchVideos	GET /v2/videos/search	Search for videos