Shutterstock API tutorial: JavaScript

This version of the tutorial walks you through the steps using JavaScript and the Shutterstock JavaScript SDK. For other API clients, see the tutorial overview.

Part 1: Setting up a Shutterstock API account

Instead of using your shutterstock.com username and password, the API uses an access token that is tied to your account and to an application. This application represents the application or program that you're using to access the API. That application can be a big, complicated program, or some simple commands like the examples in this tutorial.

Here's how to get an application and a token:

Create an account at https://www.shutterstock.com if you don't already have one.
Create an application at https://www.shutterstock.com/account/developers/apps with these settings:
- App name: Specify a name for your application, such as "Shutterstock API tutorial app"
- Callback URL: Specify localhost
- Referrer: Leave this field blank
- Included products: Accept the default values; these products refer to the free image subscription and other access that you application has by default, including basic use of reverse image search and custom music generation
- Subscriptions: Select the check box labeled Start free image subscription
- Company name: Specify a name for your company or organization or your own name
- Website: Specify the name of a web site for you, your company, or your organization, such as example.com
- Intended use: Select Personal, academic, or hackathon project
- Description: Specify a description for the application, such as "Trying the API tutorial"
Read and agree to the Shutterstock terms of service. The application settings look like this:
Click Save. The new app appears on your Developers page. It looks like this:

Later, you can create other apps to keep different API projects separate.
On the application page, click Generate token.
On the Select Scopes page, select the check box next to every scope. These scopes are permissions that control what you can do with the token. In this case, you need the token to be able to license images, and you can also enable the Collections scope to work with your custom collections.
Click Continue.
In the popup window, sign in to your Shutterstock account and click Allow to allow applications with the token to access your account.
On the Token generated! page, copy the token and save it somewhere on your computer.

Note: This token is shown only once, so make sure to save a copy before closing the page. Keep the token private, because other people could use it to access your account. The token is valid until you change your Shutterstock account password.

Now that you have an application and a token, you can set up an API client to make API requests on your behalf.

Part 2: Setting up the JavaScript SDK

The Shutterstock JavaScript SDK includes JavaScript commands that correspond to each endpoint in the API. The SDK lets you make API requests from a Node.JS program without having to use an HTTPS request library and manage the requests and responses yourself.

To use set up the JavaScript SDK for use in the tutorial, follow these steps:

Install Node.JS and the npm program.

If you don't have a Node.JS project, in a command-line terminal, create a simple project with NPM or Yarn by running these commands:

mkdir api-tutorial

cd api-tutorial

npm init -y

Add the JavaScript SDK package to the project:

npm install shutterstock-api --save

In the project folder, create a JavaScript file named tutorialTest.js that contains this code:

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const usersApi = new sstk.UsersApi();

usersApi.getUser()
  .then((data) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

This code gets information about your account by using the API's GET /v2/user endpoint. It creates an object named usersApi that represents the user-related commands and then calls that object's getUser() method, which represents that endpoint.

Put your token in the SHUTTERSTOCK_API_TOKEN environment variable.

The way that you save the token in the environment variable is different based on your operating system. On MacOS and Linux, use the export terminal command, as in this example:

export SHUTTERSTOCK_API_TOKEN=v2/ODYwYmRlNzBiYjMzNTE2M2UyZTQvMTc4NzI2OTM4L2N1c3RvbWVyLzIvWEtXR01HQ1FaVHRLOG85a

On Windows, use the set terminal command, as in this example:

set SHUTTERSTOCK_API_TOKEN=v2/ODYwYmRlNzBiYjMzNTE2M2UyZTQvMTc4NzI2OTM4L2N1c3RvbWVyLzIvWEtXR01HQ1FaVHRLOG85a

When you set an environment variable like this, it persists until you close the terminal window. To make the token available long-term, you may want to configure your terminal to set this variable every time you open a terminal window, such as in your .bashrc or .zshrc file. See the documentation for your terminal or operating system for more information about configuring your shell.

In the JavaScript file, the sstk.setAccessToken method sets the authentication token to use with the SDK, so your program must include this command before the new sstk.UsersApi() command. The examples in this tutorial and the API reference assume that you put the token in the SHUTTERSTOCK_API_TOKEN environment variable. Each example uses the token to authenticate to the SDK with this command:

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

Run the JavaScript file with this command-line command:

node tutorialTest.js

The terminal window shows the response from the API, which includes information about your user account, as in this example:

{
  "username": "jsmith",
  "full_name": "John Smith",
  "first_name": "John",
  "last_name": "Smith",
  "language": "en",
  "email": "jsmith@example.com",
  "id": "123456789",
  "customer_id": "123456789",
  "is_premier": false,
  "only_sensitive_use": false,
  "only_enhanced_license": false
}

Now the JavaScript SDK is installed and you can use it to access the API in Node.JS projects.

Every endpoint in the Shutterstock API has a matching method in the JavaScript SDK. The SDK is organized into JavaScript objects for different areas of the API. For example, methods relating to searching or licensing images are in the ImagesApi() object and methods relating to searching or licensing videos are in the VideosApi() object.

To find the right objects and methods for your tasks, you can refer to the JavaScript SDK reference or go to the Shutterstock API reference and select the Node.JS tab for examples of each command.

Troubleshooting the installation

If you have installed the SDK with the command npm install shutterstock-api --save but when you run the JavaScript file you see the error Error: Cannot find module 'shutterstock-api', try these things to fix it:

Instead of running node tutorialTest.js, run npx node tutorialTest.js. If this command works, you can continue the tutorial prefixing each node command with npx.

Instead of running the JavaScript file directly, add it as an npm script in the package.json file. For example, in the scripts section of the file, you can add the JavaScript file as a script named tutorialScript like this:

"scripts": {
  "tutorialScript": "node tutorialTest.js"
}

Now you can run the JavaScript file from the command line with the command npm run tutorialScript.

Part 3: Searching for images

If you're familiar with searching for images on shutterstock.com, searching with the REST API is similar. The ImagesApi.searchImages() method, which uses the GET /v2/images/search endpoint, is the main way to find images based on keywords, categories, sizes, and other filters that you might use on the shutterstock.com search.

Search for one or more images with the ImagesApi.searchImages() command. Here's an example that searches for photos with kites in them:

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const imagesApi = new sstk.ImagesApi();

const queryParams = {
  query: 'kites',
  image_type: 'photo',
  page: 1,
  per_page: 5,
  sort: 'popular',
  view: 'minimal',
};

imagesApi.searchImages(queryParams)
  .then(({ data }) => {
    console.log(JSON.stringify(data, null, 2));
  })
  .catch((error) => {
    console.error(error);
  });

The search uses the keyword "kites" and selects the first 5 results, sorted by popularity. You can change the parameters in the queryParams object to adjust your search; you can add any of the parameters that are shown in the SDK reference for the ImagesAPI.searchImages() command.

The response from the API includes info about the search results, including links to thumbnail images and the dimensions of the full images. Most importantly, the results include the IDs of the images, which you'll need to download full images.

Here's an abbreviated example of what the search results look like:

{
  "page": 1,
  "per_page": 5,
  "total_count": 116,
  "search_id": "edc213ae-d968-47e5-8cb0-9b16f3a7fbae",
  "data": [
    {
      "id": "1851475780",
      "aspect": 1.5,
      "assets": {
        "small_thumb": {
          "height": 67,
          "url": "https://thumb1.shutterstock.com/thumb_small/250738318/1851475780/stock-photo-wide-shot-of-a-multi-generation-family-walking-with-a-kite-on-a-sunny-beach-with-a-yellow-van-in-1851475780.jpg",
          "width": 100
        },
        "large_thumb": {
          "height": 100,
          "url": "https://thumb1.shutterstock.com/thumb_large/250738318/1851475780/stock-photo-wide-shot-of-a-multi-generation-family-walking-with-a-kite-on-a-sunny-beach-with-a-yellow-van-in-1851475780.jpg",
          "width": 150
        },
        "preview_1000": {
          "url": "https://ak.picdn.net/shutterstock/photos/1851475780/watermark_1000/bb93b8277668a1c8c1e612bc3925e2b8/preview_1000-1851475780.jpg",
          "width": 1000,
          "height": 667
        }
      },
      "contributor": {
        "id": "250738318"
      },
      "description": "Wide shot of a multi-generation family walking with a kite on a sunny beach with a yellow van in background.",
      "image_type": "photo",
      "has_model_release": true,
      "media_type": "image"
    },
    {
      "id": "1851471952",
      "aspect": 1.5017,
      "assets": {
        "small_thumb": {
          "height": 67,
          "url": "https://thumb9.shutterstock.com/thumb_small/250738318/1851471952/stock-photo-full-shot-of-a-multi-generation-family-running-with-a-kite-on-a-sunny-beach-with-the-sea-in-1851471952.jpg",
          "width": 100
        },
        "large_thumb": {
          "height": 100,
          "url": "https://thumb9.shutterstock.com/thumb_large/250738318/1851471952/stock-photo-full-shot-of-a-multi-generation-family-running-with-a-kite-on-a-sunny-beach-with-the-sea-in-1851471952.jpg",
          "width": 150
        },
        "preview_1000": {
          "url": "https://ak.picdn.net/shutterstock/photos/1851471952/watermark_1000/b8aa144b31c26f4690aa16157ae6c65a/preview_1000-1851471952.jpg",
          "width": 1000,
          "height": 666
        }
      },
      "contributor": {
        "id": "250738318"
      },
      "description": "Full shot of a multi-generation family running with a kite on a sunny beach with the sea in background.",
      "image_type": "photo",
      "has_model_release": true,
      "media_type": "image"
    }
  ],
  "spellcheck_info": {}
}

You can work with this JSON response from the API just like any other JavaScript object. For example, this program filters the results to show a description, ID, and preview URL for each result:

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const imagesApi = new sstk.ImagesApi();

const queryParams = {
  query: 'kites',
  image_type: 'photo',
  page: 1,
  per_page: 5,
  sort: 'popular',
  view: 'minimal',
};

imagesApi.searchImages(queryParams)
  .then(({ data }) => {
    const simplifiedResults = data.map(({ id, description, assets }) => ({
      id,
      description,
      preview: assets.preview.url,
    }));
    console.log(simplifiedResults);
  })
  .catch((error) => {
    console.error(error);
  });

Here's a thumbnail image from the results:

Select an image that you want to try licensing with your account and note its ID number. Your application and token are using the free image subscription, so the results include only images in Shutterstock's free images collection. Therefore, you can use the free subscription to license and download any image in these search results.

Get information about the image, including the sizes that the image is available in, with the ImagesApi.getImage() command. For example, the image with the thumbnail in the previous step has the ID 1851471952. To get full information about the image, run this program:

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const imagesApi = new sstk.ImagesApi();

imagesApi.getImage('1851471952')
  .then((data) => {
    console.log(JSON.stringify(data, null, 2));
  })
  .catch((error) => {
    console.error(error);
  });

The full details contain links to thumbnails and previews of multiple sizes, information about the models in the image, and the dimensions and DPI of the different sizes that the image is available in. You'll need those sizes later to make sure that you download the size of the image that you want. In this case, the image is availale in the sizes small (500x333px), medium (1000x666), and huge (5172x3444), denoted by the small_jpg, medium_jpg and huge_jpg fields in the response. Different images are available in different sizes and formats, but all images are available in at least small and medium JPGs.

Here are some abbreviated details about the image:

{
  "id": "1851471952",
  "added_date": "2020-11-10",
  "aspect": 1.5017,
  "assets": {
    "medium_jpg": {
      "display_name": "Med",
      "dpi": 300,
      "file_size": 732305,
      "format": "jpg",
      "height": 666,
      "is_licensable": true,
      "width": 1000
    },
    "small_jpg": {
      "display_name": "Small",
      "dpi": 300,
      "file_size": 204811,
      "format": "jpg",
      "height": 333,
      "is_licensable": true,
      "width": 500
    },
    "huge_jpg": {
      "display_name": "Huge",
      "dpi": 300,
      "file_size": 13290693,
      "format": "jpg",
      "height": 3444,
      "is_licensable": true,
      "width": 5172
    },
    "preview": {
      "height": 299,
      "url": "https://image.shutterstock.com/display_pic_with_logo/250738318/1851471952/stock-photo-full-shot-of-a-multi-generation-family-running-with-a-kite-on-a-sunny-beach-with-the-sea-in-1851471952.jpg",
      "width": 450
    },
    "small_thumb": {
      "height": 67,
      "url": "https://thumb9.shutterstock.com/thumb_small/250738318/1851471952/stock-photo-full-shot-of-a-multi-generation-family-running-with-a-kite-on-a-sunny-beach-with-the-sea-in-1851471952.jpg",
      "width": 100
    },
    "large_thumb": {
      "height": 100,
      "url": "https://thumb9.shutterstock.com/thumb_large/250738318/1851471952/stock-photo-full-shot-of-a-multi-generation-family-running-with-a-kite-on-a-sunny-beach-with-the-sea-in-1851471952.jpg",
      "width": 150
    },
    "huge_thumb": {
      "height": 260,
      "url": "https://image.shutterstock.com/image-photo/full-shot-multigeneration-family-running-260nw-1851471952.jpg",
      "width": 391
    },
    "preview_1000": {
      "url": "https://ak.picdn.net/shutterstock/photos/1851471952/watermark_1000/b8aa144b31c26f4690aa16157ae6c65a/preview_1000-1851471952.jpg",
      "width": 1000,
      "height": 666
    },
    "preview_1500": {
      "url": "https://image.shutterstock.com/z/stock-photo-full-shot-of-a-multi-generation-family-running-with-a-kite-on-a-sunny-beach-with-the-sea-in-1851471952.jpg",
      "width": 1500,
      "height": 999
    }
  },
  "categories": [
    {
      "id": "13",
      "name": "People"
    }
  ],
  "contributor": {
    "id": "250738318"
  },
  "description": "Full shot of a multi-generation family running with a kite on a sunny beach with the sea in background.",
  "image_type": "photo",
  "is_adult": false,
  "is_editorial": false,
  "is_illustration": false,
  "has_model_release": true,
  "has_property_release": false,
  "keywords": [
  ],
  "media_type": "image",
  "model_releases": [
    {}
  ],
  "models": [
    {}
  ],
  "original_filename": "38273.jpg"
}

That's all you have to do to search for images with the API. The reference for the ImagesApi.searchImages() method has many more fields to search on, and other commands like ImagesApi.getSimilarImages() and ImagesApi.getImageRecommendations() get images in different ways. For full details, see the SDK documentation and the images resource in the API reference.

Note that you may see different results when you search through the API from when you search on shutterstock.com. Different subscriptions provide access to different Shutterstock media libraries. API requests use only the media in your subscription's library, including search, details, and licensing requests. For example, when you search with the free subscription, the results are limited to images in the Free stock photos collection.

For this reason, you might see different media by searching on the API versus searching on shutterstock.com. Before trying to license media, make sure that you can access it through the API with your API subscription.

Part 4: Licensing and downloading images

With the free API subscription, you can license and download images from Shutterstock's free collection.

Even though the images don't cost anything to license, your use of the images is legally bound to the conditions of the license that Shutterstock provides. In this case, your API subscription provides a Shutterstock API Platform License.

This license allows you to use the images in your application, but you can't provide or resell the images to other people. Other restrictions apply. For more information about this license, see What is the Shutterstock API Platform License?.

Follow these steps to license and download an image:

Get your subscription ID. If you are using the free subscription, you can find the subscription ID on the https://www.shutterstock.com/account/developers/apps page in your application information, on the Details tab, as shown in the following image.

Take note of the subscription ID, because you will need it soon.

To get your subscription ID through the SDK, run this program:

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const api = new sstk.UsersApi();
api.getUserSubscriptionList()
  .then(({ data }) => {
    console.log(JSON.stringify(data, null, 2));
  })
  .catch((error) => {
    console.error(error);
  });

The response includes your subscription ID and the sizes of media that you can license with that subscription. In this example response, the subscription ID is s12345678.

{
  "data": [
    {
      "id": "s12345678",
      "expiration_time": "2022-06-23T15:08:28-04:00",
      "license": "integrated_media",
      "description": "PS Core Free Product - Image",
      "asset_type": "images",
      "allotment": {
        "start_time": "2021-06-23T15:08:29-04:00",
        "end_time": "2021-07-23T15:08:28-04:00",
        "downloads_left": 500,
        "downloads_limit": 500
      },
      "formats": [
        {
          "media_type": "image",
          "description": "Small",
          "format": "jpg",
          "min_resolution": 500,
          "size": "small"
        },
        {
          "media_type": "image",
          "description": "Med",
          "format": "jpg",
          "min_resolution": 1000,
          "size": "medium"
        },
        {
          "media_type": "image",
          "description": "Huge",
          "format": "jpg",
          "min_resolution": 4000000,
          "size": "huge"
        },
        {
          "media_type": "image",
          "description": "Vector",
          "format": "eps",
          "size": "vector"
        }
      ]
    }
  ]
}

Make the licensing request with the ImagesApi.licenseImages() method. Because the image licensing endpoint is a POST request, you must pass the information in the body of the request in a JavaScript object. In this case, we're using the command to license an image: POST /v2/images/licenses.

Authenticate to the API as usual:

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const imagesApi = new sstk.ImagesApi();

Put the subscription ID, image ID, and size of the image that you want to license in a JavaScript object. Based on the example of this command and its LicenseImageRequest schema, the JavaScript object to license image 1851471952 in the medium size looks like this:

const body = {
  "images": [
    {
      "image_id": "1851471952",
      "subscription_id": "s12345678",
      "size": "medium"
    }
  ]
};

Licensing requests in more complicated scenarios, such as with reseller and enterprise accounts, require more information in the JSON data. For more information about licensing requests in different scenarios, see Licensing and downloading in the API reference.

Send the object to the ImagesApi.licenseImages() method:

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

Run the program.

The complete program looks like this:

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const imagesApi = new sstk.ImagesApi();

const body = {
  "images": [
    {
      "image_id": "1851471952",
      "subscription_id": "s12345678",
      "size": "medium"
    }
  ]
};

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

If the licensing request is successful, the response from the API includes the URL to the full image. Download the image now, because not all subscription types allow you to download the image again later. Here's an example licensing response:

{
 "data": [
   {
     "download": {
         "url": "https://download.shutterstock.com/gatekeeper/W3siZCI6ICJzaHV0dGVyc3RvY2stbWVkaWEiLCAiayI6ICJwaG90by8xODUxNDcxOTUyL21lZGl1bS5qcGciLCAiZGMiOiAiaWRsXzEyMyIsICJlIjogMTYyNTA5NjUxMCwgIm0iOiAxfSwgInMxdUVXeGVHNUd2RkRrTndZWmEwN2gycWhEOCJd/shutterstock_1851471952.jpg"
     },
     "allotment_charge": 1,
     "image_id": "1851471952"
   }
 ]
}

Now the image is available for your use, according to the terms of the license. Some subscription types allow you to download the image again later by using the ImagesApi.downloadImage() endpoint.

If your licensing request fails, make sure that the JSON data matches the example in the last step. Your JSON must be properly formatted, so make sure that all the quotation marks, braces ({}), and brackets ([]) are in the right place.

Also make sure the image ID is an image that you found by searching the free images collection and that you have used a standard size such as medium.

Next steps

That's all you need to get started with the Shutterstock API. From here, you can use all kinds of programming languages and API clients to build applications that use Shutterstock's media and services. For more information about the API, see https://developers.shutterstock.com, and the endpoint reference and code samples in the API reference.

Lots of example code is available on GitHub at https://github.com/shutterstock, such as an example of how to authenticate with the API in JavaScript: shutterstock-oath-example.

A fecha de 30 de noviembre de 2023, contamos con más de 475.000.000 de elementos en Shutterstock.com.

Nuestra empresa

Sobre nosotros

Oportunidades de empleo

Prensa/Medios

Relaciones con inversionistas

Blog de Shutterstock

Precios

Cupones

Búsquedas populares

Contáctanos

Nuestra empresa

Sobre nosotros

Oportunidades de empleo

Prensa/Medios

Relaciones con inversionistas

Blog de Shutterstock

Precios

Cupones

Búsquedas populares

Contáctanos

Legal

Términos de uso del sitio web

Términos de servicio

Política de privacidad

Declaración sobre la esclavitud moderna

Patentes

Preferencias de cookies

Legal

Términos de uso del sitio web

Términos de servicio

Política de privacidad

Declaración sobre la esclavitud moderna

Patentes

Preferencias de cookies

Nuestras marcas

Pond5

PremiumBeat

TurboSquid

Giphy

Nuestras marcas

Pond5

PremiumBeat

TurboSquid

Giphy

Innovación

Shutterstock.AI

Generador de imágenes de IA

Tipos de estilo de IA

Generador de paletas de colores

App móvil de Shutterstock

App de iOS

App de Android