Bring the power of 25 million
images to any application.

Our API supports a wide range of integrations across websites,
mobile applications, content management systems, and more.

Get a Key Your Email Address Your website URL Description of how you will use our API We're sorry but something went wrong. Please try again later. Thank you! Your key is on its way.

Questions? Contact api@shutterstock.com

Table of Contents

Introduction

A bird's-eye view of how the Shutterstock REST API works.

Representation File Formats

An explanation of which data formats can be returned by the API and how to request them.

HTTP Request Methods

A list of HTTP methods and their mappings to the common operations create, read, update, and delete.

HTTP Response Codes

A list of response codes and their descriptions. These are the codes that will be returned by the API to indicate success, redirection, or errors.

Code Samples

Working example code.

Affiliate Site Link Creation

How to create affiliate links from API results.

Affiliate Site Optimization

Tips on how to make your site respond more quickly while hitting the Shutterstock API.

Resources

/auth/customer

Allows the client to login as a registered downloading customer.

/categories

Displays all categories and their category ids.

/customers/<username>

Creates a registered user, and displays or modifies registered user information.

/customers/<username>/images/downloads

Displays customer image downloads and the subscriptions under which they were downloaded. NOT IMPLEMENTED: Listing of free downloads and pre-2007 downloads.

/customers/<username>/lightboxes

Displays and creates customer lightboxes.

/customers/<username>/lightboxes/extended

Additional information about the contents of customer lightboxes

/customers/<username>/subscriptions

Displays information about customer subscriptions including start and end dates, number of downloads remaining, and available sizes. For enterprise subscriptions, also returns price per download.

/images/<image_id>

Displays details for a specific image.

/images/<image_id>/similar

Searches for images similar to the given image.

/images/search

Searches for images that meet provided criteria.

/lightboxes/<lightbox_id>

Displays and deletes collections of images created by the user.

/lightboxes/<lightbox_id>/extended

Additional information about lightbox contents

/lightboxes/<lightbox_id>/images/<image_id>

Adds or removes images from a collection of images created by the user.

/lightboxes/<lightbox_id>/public_url

Returns public URLs for lightboxes

/resources

A meta-resource which provides information about all available resources.

/subscriptions/<subscription_id>/images/<image_id>/sizes/<size>

Provides a URL for a customer to download an image and charges their account as needed. If a customer has had multiple subscriptions with Shutterstock, some previously-downloaded images may be available for redownload without charge. It is the client's responsibility to check for this and use the correct subscription id under which the image was originally purchased. Otherwise, the download will count against the subscription id provided. NOT IMPLEMENTED: free image downloads.

/test/echo

Allows developers to test their code by verifying that inputs are received by the API and outputs are received by the client.

Footage-specific Resources

/videos/<video_id>

Displays details for a specific video.

/videos/search

Searches for videos that meet provided criteria.

Introduction

The Shutterstock REST API allows outside developers to create their own tools using the functionality of the Shutterstock website. If you've ever been in a situation where it seemed like the best solution would be to write a "screen scraper" to make a web request, parse the results, and use that data in some way, you understand the need. This is what an API allows you to do, but it makes things much easier. The web pages you retrieve through an API are designed to be machine-readable and not subject to frequent changes, unlike a human-readable web page.

In this documentation, when we refer to the "user," we're referring to the end user--the customer or entity who is getting the benefit of using your application that is using the Shutterstock API. The term "client" will refer to your application that is accessing the API on behalf of a user.

The Shutterstock API conforms to REST standards for the most part. REST refers to both static web pages and dynamic web applications as resources. REST loosely maps the common operations of create, read, update, and delete ("CRUD") to HTTP methods PUT, GET, POST, and DELETE respectively.

Authentication

We have two layers of authentication which may be required simultaneously.

HTTP basic authentication is necessary to access all API resources. You can speak to a Shutterstock representative to get an API username and API key which you then must always supply as the HTTP basic authentication username and password. Do not supply a customer's username and password via HTTP basic authentication. Simple searches like those that are performed by most Shutterstock affiliates require no further authentication.

However, some resources are specific to certain users, such as the resource that allows viewing the contents of a customer's lightboxes, in which case you will have to provide us with a customer's username and password (in addition to your API username and API key). A customer's username and password must not be submitted via HTTP basic authentication. Instead, you will submit the customer's username and password as normal post parameters (in addition to always providing your API username and API key via HTTP basic authentication in the request headers) to one of the "auth" resources listed in this document. The auth resource will return a value which is called the auth_token. User-specific protected resources require this auth_token argument as a parameter in every request (in addition to always requiring your API username and API key to be provided via HTTP basic authentication in the request headers). An auth_token is good for a limited time. If it expires, the client application will start receiving an HTTP response code of 403. If this happens, the client application will have to resubmit the customer's username and password and request a new auth_token.

In most cases, you will only need your API username and API key. But if you wish to access resources that are specific to a customer so you can act on a customer's behalf, you will need 2 usernames and 2 passwords: an API username and an API key, provided by your application via HTTP basic authentication headers, and the user's Shutterstock username and Shutterstock password, provided by the user, that you submit to the /auth/customer resource via post parameters. Failing to provide an API username and API key will result in a 401 status. Failing to provided a customer's auth_token will result in a 403 status.

Accessing the API

The API can be accessed at http://api.shutterstock.com/. You must choose a resource path to append to this URL. An example of a resource path is /test/echo. An example URL which can be viewed in a web browser is http://api.shutterstock.com/test/echo.html?hello=world. Feel free to change the parameter names and values to see how this example resource works. You can also change the file extension from html to yaml, json, or perl to view a resource in a different representation file format.

There are not yet any libraries to help you write your client code, so you'll have to handle every step, from making the web request to analyzing and parsing the results. As new tools are written and published, we'll link to them here. We encourage you to make any reusable code that you write open source, and be sure to let us know if you do.

API Interface Changes

Some types of changes to the API interface are likely to occur without notice, so when you write code to access the API, keep this in mind. Hash keys (AKA associative array indexes) may be ordered, or returned in any random order, and this ordering may change without notice. New hash keys may be added to the data that the API returns at any time without notice. We will do our best to notify our users before removing hash keys from results or adding new required fields to inputs, but we may occasionally do these things without notice as well. The Shutterstock API has no warranty.

Representation File Formats

Representation file formats are chosen by the file extension of the resource URL.

JSON: JSON is valid executable Javascript, but it is commonly used to send data between other languages as well. www.json.org

YAML: YAML is language-independent, but resembles JSON plus a few other features. www.yaml.org

Perl: Perl output is valid executable Perl. www.perl.org

HTML: HTML can also be output, but should not be used by automated requests. It is bulky because it contains display information, and this display information is subject to change at any time. Feel free to view HTML responses in a browser to get a feel for how the API works.

HTTP Request Methods

PUT: A PUT request indicates a create operation. However, this requires being able to guess the created resource's URL ahead of time, since after resource creation, the created resource is presumed to exist at that same location. In other words, after a successful PUT request to a given URL, a GET request can be made (assuming the resource supports GET) to that URL to view the newly-created resource. When the URL cannot be guessed ahead of time, a POST to a separate resource may be used instead. Web applications designed for use by humans (as opposed to REST web APIs designed for use by machines) usually use POSTs to create resources since many browsers do not support PUT. PUT requests are, in a trivial sense, idempotent (they can be executed multiple times on the same resource without changing anything), but only because an error will be thrown after the first successful operation. It does not make sense to create a resource that has already been created.

GET: A GET request indicates a read operation. Most resources will respond to a GET request. A GET request simply displays the resource in its current state. It gets a bit more complicated than that, however, since a single resource state can have many representations. For example, the state of the office coffee pot resource (if you were to create a web application for it) might be represented as a video feed, a recent photo, or a chart indicating things like the time the coffee was last made and its current level. Furthermore, each representation can have many representation file formats as well (such as avi, jpg, svg, html, etc.) In a REST API, these representations and representation file formats could all be retrieved from the same resource (yes, that means the same URL), distinguished by differing HTTP headers or query string parameters (or in a useful slight reinterpretation of REST principles, differing file extensions, which the Shutterstock API uses). A GET request should always be idempotent and safe (it should have no side effects on the resource). Non-REST web applications in the real world sometimes violate this principle.

POST: A POST request often indicates an update operation, or it can be a request to a "factory" resource (a resource that creates other resources). POST requests are also sometimes used in place of GET requests when the parameters of a GET request would be too long and unwieldy. Web applications designed for use by humans also use POSTs to create and delete resources, since many browsers do not support PUT and DELETE. POSTs are usually neither idempotent nor safe. They are intended to modify, create, or delete resources. Successive duplicate requests may make multiple modifications or creations, changing the state of the resource in some way with each request.

DELETE: A DELETE request indicates a delete operation. It means that the resource that is requested should be deleted. Web applications designed for use by humans usually use POSTs to delete resources, since many browsers do not support DELETE. DELETEs are, in a trivial sense, idempotent, but only because an error will be thrown after the first successful operation. It does not make sense to delete a resource that has already been deleted.

HTTP Response Codes

One of these response codes will be returned with every request. These are our API-specific meanings for these response codes. We have tried to follow the standards as well as possible, but where the standards are vague or inadequate we may use these codes in ways which are slightly different from how they were originally intended.

Depending on the request and the state of the resource, the response's content entity body may be empty, may contain a generic Apache error message, may contain a specific text message relating to your request, or may contain a response made up of machine-readable structured data. If a given response's content entity body is empty or generic, you can refer to this chart for more information.

Codes shown in black are normal and should be expected by your client. Codes shown in yellow are due to mistakes made by your client. That is, we will do our best to provide your client with the resources it needs to avoid these errors entirely, and they should only show up when your client is under development. Your code should not have to check for these statuses, because they should not happen at all. If you feel that you have no choice but to check for these client-side errors in your production code, please notify our development team. Codes shown in red indicate an error on our server. If you receive a red response code which does not resolve itself promptly, or a response code which is not listed below, please notify our development team.

Code Samples

PHP example

This code is a small unsecured web application that hits the Shutterstock search API for both photos and footage results.

<!DOCTYPE html>
<html>
<head>
	<title>Shutterstock API PHP Sample Code</title>
</head>
<body>

Search:
<form method="get">
	<input type="text" name="search_terms">
	<input type="hidden" name="api_username" value="<?php echo $_GET['api_username'] ?>">
	<input type="hidden" name="api_key" value="<?php echo $_GET['api_key'] ?>">
	<input type="submit">
</form>

<?php
4
class ShutterstockAPI {

	protected $ch;
	protected $username;
	protected $key;

	public function __construct($username, $key) {
		$this->username = $username;
		$this->key      = $key;
	}

	protected function getCurl($url) {
		if (is_null($this->ch)) {
			$ch = curl_init();
			curl_setopt( $ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC );
			curl_setopt( $ch, CURLOPT_USERPWD, $this->username . ':' . $this->key );
			curl_setopt( $ch, CURLOPT_HEADER, 0 );
			curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 );
			$this->ch = $ch;
		}
		curl_setopt( $this->ch, CURLOPT_URL, $url );
		return $this->ch;
	}

	public function search($search_terms, $type='images') {
		$search_terms_for_url = preg_replace('/ /', '+', $search_terms);
		$url                  = 'http://api.shutterstock.com/' . $type . '/search.json?searchterm=' . $search_terms_for_url;
		$username             = $this->username;
		$key                  = $this->key;
		$ch                   = $this->getCurl( $url );
		$json                 = curl_exec( $ch );
		return json_decode( $json );
	}
}

$api_username = $_GET['api_username']; // Insert your API username here instead of GETting it from browser
$api_key      = $_GET['api_key'];      // Insert your API key here instead of GETting it from browser
$search_terms = $_GET['search_terms']; // Add your own security checks to cleanse this input

$api          = new ShutterstockAPI($api_username, $api_key);
$images       = $api->search($search_terms);
$videos       = $api->search($search_terms, 'videos');

if ($images) {
	for ( $i = 0; $i < 3; $i++ ) {
		$description  = $images->results[$i]->description;
		$thumb        = $images->results[$i]->thumb_large->url;
		$thumb_width  = $images->results[$i]->thumb_large_width;
		$thumb_height = $images->results[$i]->thumb_large_height;
		echo '<div style="display:inline-block;width:' . $thumb_width . 'px; height:' . $thumb_height . 'px; overflow:hidden;">';
		echo '<img src="' . $thumb . '" alt="' . $description . '">' . "\n\n";
		echo '</div>';
		echo '<textarea rows="10" cols="80">' . "\n";
		var_dump($images->results[$i]);
		echo "</textarea><br><hr>\n\n";
	}
}

if ($videos) {
	for ( $i = 0; $i < 3; $i++ ) {
		$description   = $videos->results[$i]->description;
		$thumb_mp4     = $videos->results[$i]->sizes->thumb_video->mp4_url;
		$thumb_webm    = $videos->results[$i]->sizes->thumb_video->webm_url;
		$preview_image = $videos->results[$i]->sizes->preview_image->url;
		echo '<img src="' . $preview_image . '" alt="' . $description . '">' . "\n\n";
		echo '<video controls="controls">' . "\n";
		echo "\t" . '<source src="' . $thumb_mp4  . '" type="video/mp4">'  .  "\n";
		echo "\t" . '<source src="' . $thumb_webm . '" type="video/webm">' . "\n";
		echo "</video>\n\n";
		echo '<textarea rows="10" cols="80">' . "\n";
		var_dump($videos->results[$i]);
		echo "</textarea><br><hr>\n\n";
	}
}

?>
</body>
</html>

Displaying thumbnails

Shutterstock thumbnails usually come with ids embedded into the images themselves. The API gives you the information you need to hide these ids. For thumbs either the actual jpg width or actual jpg height will be different from the width or height returned by the API. The width and height returned by the API is the appropriate cropped display size, not the size of the jpg itself. To hide these ids, enclose the jpgs inside a div of the returned width and height, with overflow set to hidden. The id at the bottom or right of the jpg will overflow beyond the dimensions of the containing div and disappear. See code sample.

Affiliate Site Link Creation

The API returns results that link directly to Shutterstock, because the API is intended to be general-purpose. If you are an affiliate and want to be paid for directing users to Shutterstock, you will have to generate your own affiliate links:

1. Retrieve a link from the API, or supply your own:
   http://www.shutterstock.com/pic.mhtml?id=[image id]
2. URL encode it:
   http%3A%2F%2Fwww.shutterstock.com%2Fpic.mhtml%3Fid%3D[image id]
3. Append it via the u param to your Impact Radius URL.
   Image affiliates:
   http://shutterstock.7eer.net/c/[your impact radius affiliate id]/43068/1305?u=http%3A%2F%2Fwww.shutterstock.com%2Fpic.mhtml%3Fid%3D[image id]
   Footage affiliates:
   http://shutterstock.7eer.net/c/[your impact radius affiliate id]/43977/1305?u=http%3A%2F%2Fwww.shutterstock.com%2Fpic.mhtml%3Fid%3D[image id]

Affiliate Site Optimization

If your site responds slowly because it is waiting for Shutterstock search results to return, we recommend caching search results and loading them via Ajax. To do this, create an Ajax resource on your server, in addition to your main page. Have your main page request results from this Ajax resource. The Ajax resource should have access to cached Shutterstock API search results for as many recent searches as possible. If the Ajax resource finds a hit in the cache for the search query, it can return immediately without making a request to the Shutterstock API at all, and the main page will update immediately. If the Ajax resource does not find a hit in the cache, it can then query the Shutterstock API, and store its results in the cache before returning them to the main page. At that point the main page can update. But, since the main page was already loaded, and only waiting to update itself via Ajax, it won't feel slow to the user.

Downloading

Downloading with Cumulative Subscriptions

To download images via cumulative subscriptions (e.g. 25-a-day), a validation_code parameter must be supplied. Speak to a Shutterstock representative to get more information about this parameter. This parameter is not required for non-cumulative subscriptions (e.g. On Demand).

Downloading Editorial Images

To download an editorial image, a user must acknowledge that the image will be used only as the license allows. The following notice (or equivalent non-English translation) must be presented to the user before downloading each editoral image: Editorial Use Only. Use of this image in advertising or for promotional purposes is prohibited. The user must indicate agreement (for instance, by checking a checkbox) before an editorial download can begin. Calls to the download endpoint for editorial images must include an editorial_acknowledgement parameter. The parameter's value should be 1 if the user agreed to the notice and 0 if the user did not agree. A download will not be allowed if the user did not agree.

To determine whether an image is considered an editorial image, look at the value for model_released returned by the image details API method. Editorial images have a code value of 3 and a translation_id of EDITORIAL_ONLY.

Resources