Licensing And Downloading

To license and download media with the API, you need:

An account at https://www.shutterstock.com
An application at https://www.shutterstock.com/account/developers/apps
An access token with the licenses.create, licenses.view, and purchases.view scopes. See Authentication.
An active subscription that is valid for the type, size, and use of media that you want to download.

You must be aware of what license types your subscription or subscriptions provide so you use the correct license and subscription and download the correct media:

Some license types allow you to redownload the media later and others don't.
Different license types allow you to download different media sizes. For example, a footage standard-definition subscription allows you to license and download standard-definition videos, but not high-definition videos. A footage high-definition subscription allows you to license and download high-definition videos, but not necessarily standard-definition videos.
Different licenses permit different uses. For example, both standard and enhanced image licenses allow royalty-free use of an asset, but the standard license allows only 500,000 print runs and advertising impressions, while the enhanced license allows unlimited runs and impressions.

When you request a license with the API, it provides platform licenses for media. These platform licenses allow different uses of assets than the standard and enhanced licenses. For example, platform licenses can be used to resell media licenses or to use media in places such as applications, web sites, mobile apps, and social media . For details about what you can do with platform licenses, see Shutterstock API Terms of Service.

To get information about your subscriptions and the licenses and media types that they provide, send a request to the GET /v2/user/subscriptions endpoint, with your access token in place of the environment variable SHUTTERSTOCK_API_TOKEN, as in this example:








curl -X GET 'https://api.shutterstock.com/v2/user/subscriptions' \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"

The response includes the subscription ID and the formats that it provides:

{
  "id": "s14519612",
  "license": "standard",
  "description": "Images On Demand",
  "formats": [
    {
      "size": "huge",
      "format": "jpg",
      "media_type": "image",
      "min_resolution": 4000000,
      "description": "Huge"
    },
    {
      "size": "medium",
      "format": "jpg",
      "media_type": "image",
      "min_resolution": 1000,
      "description": "Med"
    },
    {
      "size": "supersize",
      "format": "jpg",
      "media_type": "image",
      "min_resolution": 16000000,
      "description": "Super"
    },
    {
      "size": "small",
      "format": "jpg",
      "media_type": "image",
      "min_resolution": 500,
      "description": "Small"
    },
    {
      "size": "vector",
      "format": "eps",
      "media_type": "image",
      "description": "Vector"
    }
    ]
}

Licensing media

To request a license and download media, pass the media ID and the subscription ID to the appropriate endpoint. For example, to license images, use the POST /v2/images/licenses endpoint, as in the following examples. The examples use s12345678 for the subscription ID.

If you are using an API subscription from shutterstock.com, you can leave out the subscription ID field in your licensing request. In this case, the API uses the subscription that is linked to the account in the token. If that account has more than one API subscription, it uses the subscription that is closest to its expiration date. Also, API subscriptions can license only one image per request.

If you are using an API subscription, you must include the price and metadata.customer_id fields in the request body, as in the following examples. These fields are for resellers to record their customer's ID and the floating-point price that they charged to the customer, within the restrictions of their revenue-sharing agreement. If you are not reselling the media, you can pass any string in the customer_id field and 0 in the price field.








DATA='{
  "images": [
    {
      "image_id": "59656357",
      "subscription_id": "s12345678",
      "price": 12.50,
      "metadata": {
        "customer_id": "12345"
      }
    }
  ]
}'

curl -X POST "https://api.shutterstock.com/v2/images/licenses" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-H 'Content-Type: application/json' \
-d "$DATA"

The response includes a download link for each piece of media. Download links are valid for 8 hours.

After that, to download the image again, you must request a new link by either licensing the image again or requesting a redownload link if the license type permits redownloads. See Redownloading media.

Here is an example of a licensing response with download links:

{
  "data": [
    {
      "image_id": "59656357",
      "download": {
        "url": "https://download.shutterstock.com/gatekeeper/[random-characters]/shutterstock_59656357.jpg"
      },
      "allotment_charge": 1
    },
    {
      "image_id": "1079756147",
      "download": {
        "url": "https://download.shutterstock.com/gatekeeper/[random-characters]/shutterstock_1079756147.jpg"
      },
      "allotment_charge": 1
    }
  ]
}

Licensing editorial media

The endpoint that you use to license editorial media depends on where you find the editorial media. Some editorial accounts license editorial media from the same endpoints as they use to access non-editorial media. Other accounts use separate editorial endpoints to find and license editorial media. Contact your account representative for information about how you should access editorial media.

Accessing editorial media from non-editorial endpoints

If you access editorial media from non-editorial endpoints, you can find editorial media by searching with the GET /v2/images/search endpoint and setting the license parameter to editorial. Then use the POST /v2/images/licenses endpoint to license them as you would license non-editorial media.

Editorial images have the is_editorial field set to true. To license these images, you must acknowledge the editorial agreement as part of the licensing request. You must include "editorial_acknowledgement": true in the request, as in the following example.








curl -X POST "https://api.shutterstock.com/v2/images/licenses" \
--header "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"images": [
  {
    "image_id": "494469670",
    "subscription_id": "s12345678",
    "editorial_acknowledgement": true
  }
  ]
}'

Accessing editorial media from editorial endpoints

If you access editorial media from separate editorial endpoints, use the GET /v2/editorial/images/search or GET /v2/editorial/videos/search endpoints to find the media. Use the POST /v2/editorial/images/licenses or POST /v2/editorial/videos/licenses endpoints to license and download the media, as in this example:








DATA='{
  "editorial": [
    {
      "editorial_id": "8594090h",
      "license": "premier_editorial_comp"
    }
  ],
  "country": "USA"
}'

curl -X POST https://api.shutterstock.com/v2/editorial/images/licenses \
-d "$DATA" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"

Licensing sandbox

You can use the licensing sandbox API to test your application's licensing, downloading, and license history code for images, video, and audio and verify that your subscription is working. Editorial licensing is not available in the sandbox. To use the sandbox, change the base URL of your requests to https://api-sandbox.shutterstock.com. If you are using the JavaScript SDK, use the setSandbox method (requires SDK version 1.0.11 or later).

The sandbox API verifies that the subscription is valid for requests just like the main API. It also returns the same HTTP status codes, so the licensing endpoints return a 200 OK code if the request was valid. The sandbox API uses the same applications and it requires the same authentication and subscriptions as the main API.

The licensing sandbox API is exactly like the main API except for these differences:

Licensing requests don't deduct credits from your subscription or provide licenses. The response includes an allotment_charge field as usual, but that allotment charge is not deducted from your subscription.
Licensing requests return different things depending on the endpoint that you use:
- Requests to the POST /v2/images/licenses endpoint return the watermarked preview_1500 version of the image if one exists, or a preset sample image if it does not.
- Requests to the POST /v2/videos/licenses and POST /v2/audio/licenses endpoints provide a preset sample file.
- Requests to the POST /v2/editorial/images/licenses endpoint in the sandbox fail.
License history requests provide information about your sandbox licensing requests.

For example, if you make requests to the the POST /v2/images/licenses endpoint in the sandbox, requests to the GET /v2/images/licenses endpoint return information about those sandbox requests. In the sandbox, the license history endpoints return information only about sandbox licenses, not licenses that you created with the main API. The API stores license history in the sandbox for at least one week and then resets it.
Redownload requests allow you to simulate redownloading media that you previously licensed with the sandbox endpoints.

For example, you can pass the ID of a sandbox image license to the POST /v2/images/licenses/{id}/downloads sandbox endpoint. If the license ID matches a license that you created in the sandbox and the license permits redownloads, the redownload endpoint returns a 200 OK code and a link to a preset sample file.

All other endpoints in the sandbox API work exactly the same way as the main API.

These examples show how to test licensing with the sandbox:








DATA='{
  "images": [
    {
      "image_id": "59656357",
      "subscription_id": "s12345678",
      "price": 12.50,
      "metadata": {
        "customer_id": "12345"
      }
    }
  ]
}'

curl -X POST "https://api-sandbox.shutterstock.com/v2/images/licenses" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-H 'Content-Type: application/json' \
-d "$DATA"

RESPONSE=$(curl -X GET https://api-sandbox.shutterstock.com/v2/images/licenses \
-H "Accept: application/json" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
--data-urlencode "image_id=59656357")

echo "The next step requires the jq program."

LICENSE_ID=$(jq -r .data[0].id <<< $RESPONSE)

REDOWNLOAD_DATA='{
  "size": "huge"
}'

curl -X POST https://api-sandbox.shutterstock.com/v2/images/licenses/$LICENSE_ID/downloads \
-d "$REDOWNLOAD_DATA" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"

Downloading the correct size and format

When you license and download media, you must be careful to license and download the size and format that you want. For each download, you should check these things:

Verify that your license allows you to download the size that you want. For example, if you want to download a 4K video, your license must include that size.
Verify that the media is available in the size and format that you want to download.
Verify that you are downloading the size and format that you want.

For example, assume that you searched for images and found an image that you want to license and download. The results from the GET /v2/images/search endpoint might look like this:

{
  "page": 1,
  "per_page": 20,
  "total_count": 7920866,
  "search_id": "Gu4P5p5iJu868FmHUMSBjg",
  "data": [
    {
      "id": "721943485",
      "aspect": 1.5,
      "assets": {
        "preview": {
          "height": 300,
          "url": "https://image.shutterstock.com/display_pic_with_logo/1879103/721943485/stock-photo-mountain-in-the-cloud-and-fog-721943485.jpg",
          "width": 450
        },
        "small_thumb": {
          "height": 67,
          "url": "https://thumb9.shutterstock.com/thumb_small/1879103/721943485/stock-photo-mountain-in-the-cloud-and-fog-721943485.jpg",
          "width": 100
        },
        "large_thumb": {
          "height": 100,
          "url": "https://thumb9.shutterstock.com/thumb_large/1879103/721943485/stock-photo-mountain-in-the-cloud-and-fog-721943485.jpg",
          "width": 150
        },
        "huge_thumb": {
          "height": 260,
          "url": "https://image.shutterstock.com/image-photo/mountain-cloud-fog-260nw-721943485.jpg",
          "width": 390
        },
        "preview_1000": {
          "url": "https://ak.picdn.net/shutterstock/photos/721943485/watermark_1000/381392d26c1a52d05f8417ea344f896b/preview_1000-721943485.jpg",
          "width": 1000,
          "height": 667
        },
        "preview_1500": {
          "url": "https://image.shutterstock.com/z/stock-photo-mountain-in-the-cloud-and-fog-721943485.jpg",
          "width": 1500,
          "height": 1000
        }
      },
      "contributor": {
        "id": "1879103"
      },
      "description": "Mountain in the cloud and fog ",
      "image_type": "photo",
      "media_type": "image"
    }
  ]
}

You can pass the ID of the image to the GET /v2/images/{id} endpoint with the parameter view=full to see the full details about the image, including the sizes that are available. (As a shortcut, you can also pass view=full to the search endpoint, but in this case the amount of data returned can be very large.) In this case, the image is available in several sizes of JPG format. With this information, you can verify that the media is licensable in the resolution that you want. You can also check for model releases and other details that affect how you can license and use the media.

{
  "id": "547233985",
  "added_date": "2017-01-02",
  "aspect": 1.5264,
  "assets": {
    "medium_jpg": {
      "display_name": "Med",
      "dpi": 300,
      "file_size": 595968,
      "format": "jpg",
      "height": 655,
      "is_licensable": true,
      "width": 1000
    },
    "huge_tiff": {
      "display_name": "Huge",
      "dpi": 300,
      "file_size": 49686696,
      "format": "tiff",
      "height": 3294,
      "is_licensable": false,
      "width": 5028
    },
    "small_jpg": {
      "display_name": "Small",
      "dpi": 300,
      "file_size": 174080,
      "format": "jpg",
      "height": 328,
      "is_licensable": true,
      "width": 500
    },
    "huge_jpg": {
      "display_name": "Huge",
      "dpi": 300,
      "file_size": 6163456,
      "format": "jpg",
      "height": 3294,
      "is_licensable": true,
      "width": 5028
    },
    "preview": {
      "height": 294,
      "url": "https://image.shutterstock.com/display_pic_with_logo/1603781/547233985/stock-photo-male-and-female-hikers-climbing-up-mountain-cliff-and-one-of-them-giving-helping-hand-people-547233985.jpg",
      "width": 450
    },
    "small_thumb": {
      "height": 66,
      "url": "https://thumb9.shutterstock.com/thumb_small/1603781/547233985/stock-photo-male-and-female-hikers-climbing-up-mountain-cliff-and-one-of-them-giving-helping-hand-people-547233985.jpg",
      "width": 100
    },
    "large_thumb": {
      "height": 98,
      "url": "https://thumb9.shutterstock.com/thumb_large/1603781/547233985/stock-photo-male-and-female-hikers-climbing-up-mountain-cliff-and-one-of-them-giving-helping-hand-people-547233985.jpg",
      "width": 150
    },
    "huge_thumb": {
      "height": 260,
      "url": "https://image.shutterstock.com/image-photo/male-female-hikers-climbing-mountain-260nw-547233985.jpg",
      "width": 398
    },
    "preview_1000": {
      "url": "https://ak.picdn.net/shutterstock/photos/547233985/watermark_1000/cb3783ea3af73280c029e958c193395c/preview_1000-547233985.jpg",
      "width": 1000,
      "height": 655
    },
    "preview_1500": {
      "url": "https://image.shutterstock.com/z/stock-photo-male-and-female-hikers-climbing-up-mountain-cliff-and-one-of-them-giving-helping-hand-people-547233985.jpg",
      "width": 1500,
      "height": 983
    }
  },
  "categories": [
    {
      "id": "13",
      "name": "People"
    },
    {
      "id": "18",
      "name": "Sports/Recreation"
    }
  ],
  "contributor": {
    "id": "1603781"
  },
  "description": "Male and female hikers climbing up mountain cliff and one of them giving helping hand.  People helping and, team work concept.

",
  "image_type": "photo",
  "is_adult": false,
  "is_illustration": false,
  "has_model_release": true,
  "media_type": "image",
  "model_releases": [
    {
      "id": "20931733"
    },
    {
      "id": "20931727"
    }
  ],
  "original_filename": "IMG_8407.jpg"
}

To verify that your subscription includes licenses for the size that you want, check the output of the GET /v2/user/subscriptions endpoint, as in the following example. This subscription includes standard licenses for vector, small, and medium images, but not huge image or supersize images or enhanced licenses.

{
  "data": [
    {
      "id": "s12345678",
      "expiration_time": "2019-08-27T10:21:10-04:00",
      "license": "standard",
      "description": "Annual Subscription",
      "allotment": {
        "start_time": "2018-08-27T10:21:11-04:00",
        "end_time": "2018-09-27T10:21:10-04:00",
        "downloads_left": 20,
        "downloads_limit": 25
      },
      "formats": [
        {
          "size": "medium",
          "format": "jpg",
          "media_type": "image",
          "min_resolution": 1000,
          "description": "Med"
        },
        {
          "size": "small",
          "format": "jpg",
          "media_type": "image",
          "min_resolution": 500,
          "description": "Small"
        },
        {
          "size": "vector",
          "format": "eps",
          "media_type": "image",
          "description": "Vector"
        }
      ]
    }
  ]
}

When you know that the media is available in the size and format that you want and that your subscription's license coves the correct size, you can download the media in the appropriate size and format. For example, this command licenses the image in medium JPG format:








DATA='{
  "images": [
    {
      "image_id": "547233985",
      "subscription_id": "s12345678",
      "format": "jpg",
      "size": "medium",
      "price": 12.50,
      "metadata": {
        "customer_id": "12345"
      }
    }
    ]
  }'

curl -X POST "https://api.shutterstock.com/v2/images/licenses" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-H "Content-Type: application/json" \
-d "$DATA"

If your application is enabled for custom image sizes, you can specify a height or width in pixels and the API resizes the image to fit that height or width, as in the following example. You can set the height or the width but not both. The height or width must be at least 100 pixels and has a maximum of the original image size.

To enable your application for custom image sizes, contact us.








DATA='{
  "images": [
    {
      "image_id": "59656357",
      "subscription_id": "s12345678",
      "size": "custom",
      "custom_dimensions": {
        "width": 500
      }
    }
  ]
}'

curl -X POST "https://api.shutterstock.com/v2/images/licenses" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-H 'Content-Type: application/json' \
-d "$DATA"

Request metadata

The licensing request body must include metadata that includes details about the licensing request. The specific metadata fields depend on your subscription type and on the type of media that you are licensing. Some customers use this metadata to track details about how they use the media, such as the project that they licensed the media for. Resellers use this metadata to track the customer that they licensed the media to and the price that they charged.

API subscriptions

If you are using an API subscription from the API subscription page, you must include the price and metadata.customer_id fields in the request body, as in the following example. These fields are for resellers to record their customer's ID and the floating-point price that they charged to the customer, within the restrictions of their revenue-sharing agreement. If you are using an API subscription and are not reselling the media, you can pass any string in the customer_id field and 0 in the price field.

{
  "images": [
    {
      "image_id": "59656357",
      "subscription_id": "s12345678",
      "price": 22.50,
      "metadata": {
        "customer_id": "12345"
      }
    }
  ]
}

For more information about API subscriptions, see Subscriptions in the API reference.

Enterprise subscriptions

Enterprise partners who are using Premier subscriptions must provide a metadata object on each media item to license. These partners customize their integration to have up to 4 metadata fields for tracking, grouping, or correlating licensing transactions on their invoices. Each integration requires a different set of metadata fields.

In this case, you must pass an empty or non-empty value for each field that your integration requires, as in the following example. To find the metadata fields that are required or optional for your subscription, use the GET /v2/user/subscriptions endpoint or contact your account representative.

{
  "images": [
    {
      "image_id": "59656357",
      "subscription_id": "s12345678",
      "metadata": {
        "purchase_order": "123456",
        "client": "Company A",
        "job": "Important project",
        "other": "Important media"
      }
    }
  ]
}

Downloads under revenue-sharing programs must include the floating-point number final cost to the end customer in the price field. The revenue sharer keeps a percentage of this cost based on its agreement with Shutterstock. This price can not be lower than the price floor for the media asset; if it is, the API changes it to the price floor for the asset.

{
  "images": [
    {
      "image_id": "59656357",
      "subscription_id": "s12345678",
      "price": 22.50,
      "metadata": {
        "customer_id": "12345",
        "geo_location": "US",
        "number_viewed": "15",
        "search_term": "dog"
      }
    }
  ]
}

Subscriptions with comp licenses

Complimentary (comp) licenses are used for testing purposes, unlimited plans, and other special cases. The request for a comp license is the same as for any other type of license, but the resulting license is not always the same. If the subscription is configured for testing purposes and similar cases, the API provides a dummy license. This dummy license does not provide any rights to the customer; it permits customers to view the media without a full license. In this case, the customers have no rights to use the media in any way.

When the API processes a comp license transaction, it does not validate the metadata. Therefore, if you are using comp licenses for testing purposes and your transactions require metadata, you must make sure that the metadata is accurate.

Retrieving metadata

To retrieve licensing request metadata, use the GET /v2/images/licenses endpoint. The response includes the metadata that was sent with each license request.

{
  "data": [
    {
      "id": "i101534558",
      "user": {
        "username": "userone"
      },
      "license": "media",
      "subscription_id": "s12345678",
      "download_time": "2019-11-01T12:10:22-05:00",
      "metadata": {
        "purchase_order": "123456",
        "client": "Company A",
        "job": "Important project",
        "other": "Important media"
      },
      "is_downloadable": false,
      "image": {
        "id": "499124106",
        "format": {
          "size": "huge"
        }
      }
    }
  ]
}

Redownloading media

Most of the time, you download media as soon as you license it, but some subscription types allow you to redownload media later. Platform licenses that you request through the API do not allow redownloads. Shutterstock considers each license to be a unique transaction for a single use of the media, so licensing a media item once does not necessarily mean that you can retrieve it later.

You can use the appropriate endpoint, such as GET /v2/images/licenses, to see your licenses:








curl 'https://api.shutterstock.com/v2/images/licenses' \
-X GET \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"

The response includes your license information:

{
  "data": [
  {
    "id": "i4117504982",
    "user": {
      "username": "jsmith"
      },
    "license": "standard",
    "subscription_id": "s12345678",
    "download_time": "2018-08-31T14:27:10-04:00",
    "image": {
      "id": "1079756147",
      "format": {
        "size": "huge"
      }
    }
  },
  {
    "id": "i4117504971",
    "user": {
      "username": "jsmith"
      },
    "license": "standard",
    "subscription_id": "s12345678",
    "download_time": "2018-08-31T14:27:10-04:00",
    "image": {
      "id": "59656357",
      "format": {
        "size": "huge"
      }
    }
  }
  ]
}

Then, if your subscription permits redownloads, you can use the license ID to request a new download URL from the POST v2/images/licenses/{license_id}/downloads endpoint, as in this example:








curl "https://api.shutterstock.com/v2/images/licenses/i4117504982/downloads" \
-X POST \
--header "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"

The response includes a download link:

{
  "url":"https://download.shutterstock.com/gatekeeper/[random-characters]/shutterstock_1079756147.jpg"
}

Downloading or backing up assets to a CMS or DAM

To populate your content management system (CMS) or digital asset management (DAM) system with your licensed media, you write client code that runs these tasks:

Authenticate using your image purchasing account as usual.
Create a list of the images that you need to download. If your CMS or DAM has a list of images that you have already downloaded, you can use the response from the GET /v2/images/licenses endpoint to get the IDs of licensed images that you have not downloaded. The images in the response are in reverse chronological order, with the most recent download at the top of the list. Therefore, you can page through the results from this endpoint and add each image to the list until you find an image that you have already downloaded. Then, you can stop adding items to the list, because all images past that image are older downloads.
Download the images with one of these methods:
- Download the image with the download URL that you received when you first licensed the image.
- If your license permits redownloads, redownload the image with the POST /v2/images/licenses/{license_id}/downloads endpoint. You can tell if you can redownload the image by sending a request to the GET /v2/images/licenses endpoint and including the image ID in the image_id query parameter. If the is_downloadable field in the response is true, you can redownload the image.
- Relicense the image and get a new download URL. When you have the image, you can rename it before copying the file to your system.
Run this process in batches as needed to keep downloading and copying the previously-licensed images. The process is similar for videos and audio tracks.