Licensing And Downloading

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

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:

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:

cURLCLIPHPJavaScript


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.

cURLCLIPHPJavaScript


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.

cURLCLIPHPJavaScript


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:

cURLCLIPHPJavaScript


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:

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:

cURLCLIPHPJavaScript


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:

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:

cURLCLIPHPJavaScript


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.

cURLCLIPHPJavaScript


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"
      }
    }
  ]
}

Revenue sharing programs

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:

cURLCLIPHPJavaScript


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:

cURLCLIPHPJavaScript


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: