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.0.18

References

• For more information about the Shutterstock public API, see https://developers.shutterstock.com/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

The REST API uses an access token or secret key that is tied to your account and to an application. This application represents the application, program, or computer commands that are accessing the API. To use the API, you must create an application at https://developers.shutterstock.com/applications and note the consumer key and 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.

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://developers.shutterstock.com/user/me/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.
• user.view: Grants read-only access to a user's basic account information (includes username, id, first and last name). If email is the same as username, it also implies user.email

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.

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	addSoundboxItems	POST /v2/audio/collections/{id}/items	Add audio tracks to collections
shutterstock-api.AudioApi	createSoundbox	POST /v2/audio/collections	Create audio collections
shutterstock-api.AudioApi	deleteSoundbox	DELETE /v2/audio/collections/{id}	Delete audio collections
shutterstock-api.AudioApi	deleteSoundboxItems	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	getAudioLicenseList	GET /v2/audio/licenses	List audio licenses
shutterstock-api.AudioApi	getGenres	GET /v2/audio/genres	List audio genres
shutterstock-api.AudioApi	getInstruments	GET /v2/audio/instruments	List audio instruments
shutterstock-api.AudioApi	getMoods	GET /v2/audio/moods	List audio moods
shutterstock-api.AudioApi	getSoundbox	GET /v2/audio/collections/{id}	Get the details of audio collections
shutterstock-api.AudioApi	getSoundboxItems	GET /v2/audio/collections/{id}/items	Get the contents of audio collections
shutterstock-api.AudioApi	getSoundboxList	GET /v2/audio/collections	List audio collections
shutterstock-api.AudioApi	getTrack	GET /v2/audio/{id}	Get details about audio tracks
shutterstock-api.AudioApi	getTrackList	GET /v2/audio	List audio tracks
shutterstock-api.AudioApi	licenseTrack	POST /v2/audio/licenses	License audio tracks
shutterstock-api.AudioApi	renameSoundbox	POST /v2/audio/collections/{id}	Rename audio collections
shutterstock-api.AudioApi	searchAudio	GET /v2/audio/search	Search for tracks
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.EditorialApi	getEditorialImage	GET /v2/editorial/{id}	Get editorial content details
shutterstock-api.EditorialApi	getEditorialLivefeed	GET /v2/editorial/livefeeds/{id}	Get editorial livefeed
shutterstock-api.EditorialApi	getEditorialLivefeedItems	GET /v2/editorial/livefeeds/{id}/items	Get editorial livefeed items
shutterstock-api.EditorialApi	getEditorialLivefeedList	GET /v2/editorial/livefeeds	Get editorial livefeed list
shutterstock-api.EditorialApi	licenseEditorialImage	POST /v2/editorial/licenses	License editorial content
shutterstock-api.EditorialApi	searchEditorial	GET /v2/editorial/search	Search editorial content
shutterstock-api.ImagesApi	addLightboxItems	POST /v2/images/collections/{id}/items	Add images to collections
shutterstock-api.ImagesApi	createLightbox	POST /v2/images/collections	Create image collections
shutterstock-api.ImagesApi	deleteLightbox	DELETE /v2/images/collections/{id}	Delete image collections
shutterstock-api.ImagesApi	deleteLightboxItems	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	getFeaturedLightbox	GET /v2/images/collections/featured/{id}	Get the details of featured image collections
shutterstock-api.ImagesApi	getFeaturedLightboxItems	GET /v2/images/collections/featured/{id}/items	Get the contents of featured image collections
shutterstock-api.ImagesApi	getFeaturedLightboxList	GET /v2/images/collections/featured	List featured image collections
shutterstock-api.ImagesApi	getImage	GET /v2/images/{id}	Get details about images
shutterstock-api.ImagesApi	getImageCategories	GET /v2/images/categories	List image categories
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	getLightbox	GET /v2/images/collections/{id}	Get the details of image collections
shutterstock-api.ImagesApi	getLightboxItems	GET /v2/images/collections/{id}/items	Get the contents of image collections
shutterstock-api.ImagesApi	getLightboxList	GET /v2/images/collections	List image collections
shutterstock-api.ImagesApi	getSimilarImages	GET /v2/images/{id}/similar	List similar images
shutterstock-api.ImagesApi	getUpdatedImages	GET /v2/images/updated	List updated images
shutterstock-api.ImagesApi	licenseImages	POST /v2/images/licenses	License images
shutterstock-api.ImagesApi	renameLightbox	POST /v2/images/collections/{id}	Rename image collections
shutterstock-api.ImagesApi	searchImages	GET /v2/images/search	Search for images
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	getUserSubsciptionList	GET /v2/user/subscriptions	List user subscriptions
shutterstock-api.VideosApi	addClipboxItems	POST /v2/videos/collections/{id}/items	Add videos to collections
shutterstock-api.VideosApi	createClipbox	POST /v2/videos/collections	Create video collections
shutterstock-api.VideosApi	deleteClipbox	DELETE /v2/videos/collections/{id}	Delete video collections
shutterstock-api.VideosApi	deleteClipboxItems	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	getClipbox	GET /v2/videos/collections/{id}	Get the details of video collections
shutterstock-api.VideosApi	getClipboxItems	GET /v2/videos/collections/{id}/items	Get the contents of video collections
shutterstock-api.VideosApi	getClipboxList	GET /v2/videos/collections	List video collections
shutterstock-api.VideosApi	getSimilarVideos	GET /v2/videos/{id}/similar	List similar videos
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	getVideoCategories	GET /v2/videos/categories	List video categories
shutterstock-api.VideosApi	getVideoLicenseList	GET /v2/videos/licenses	List video licenses
shutterstock-api.VideosApi	getVideoList	GET /v2/videos	List videos
shutterstock-api.VideosApi	licenseVideos	POST /v2/videos/licenses	License videos
shutterstock-api.VideosApi	renameClipbox	POST /v2/videos/collections/{id}	Rename video collections
shutterstock-api.VideosApi	searchVideos	GET /v2/videos/search	Search for videos