Shutterstock Unlimited
Charise Scrivner
The Shutterstock API provides access to Shutterstock's library of media, as well as information about customers' accounts and the contributors that provide the media.It allows customer platforms to search for media, view information and previews for the media, and license and download media.
This documentation provides information about each endpoint in the API.The right-hand pane of this page shows example requests and responses for each endpoint in cURL, Node.js/JavaScript, PHP, and the Shutterstock command-line client.
As an alternative to using the SDK, you can make requests with any JavaScript HTTPS request library.Regardless of which library you use, you must ensure that your request includes the user-agent header.Some libraries include this header automatically and others do not.
After you have authenticated to the API, you can send requests to the API using any programming language or program that can send HTTP requests.The base URL for all endpoints is examples, see the right-hand pane.
Some endpoints can accept or return some data in multiple languages.Not all response data is translated, and not all endpoints support languages other than English.Different endpoints support different language features:
Most image and video endpoints can return metadata such as categories and keywords in the specified language.For example, the GET /v2/images/categories endpoint can provide the image categories in multiple languages.
To search or return data in a language other than English, pass the language code (such as fr or zh-Hant) in the language query parameter or the Accept-Language header, as in the example in the right-hand pane.
Some endpoints return information in JSON format.In most cases, the metadata is in the root fields of the JSON data, and the data about the media is in a data field.Most programming languages have libraries that can accept and manipulate JSON data.
Many endpoints, including search endpoints, split long response data into multiple pages with the page and per_page parameters.For example, if a search result has 20 pieces of media, you can retrieve items 6-10 by using page=2 and per_page=5 in the request, as shown in the examples in the right-hand pane.You can show up to 500 results per page for most requests.Some endpoints have different limits; see the description of the per_page parameter for the individual endpoints.
The sort parameter controls how results are ordered.By default, image and video searches return the most popular media first.Audio searches without the sort parameter return tracks based on the popularity of that track in the location of the request.
To save bandwidth, you can compress API responses by passing the header Accept-Encoding: gzip.The API returns the JSON results as usual, but they are compressed into a gzip file.It is up to you to save and extract the compressed file.
The view parameter on some search and informational endpoints controls how much detail is shown in the response.By default (view=minimal), the response includes a moderate amount of detail about each search result, but if you set the view parameter to full, the response includes complete information about each result.For example, full image results include the full list of keywords and categories that apply to each image.
You can limit the information shown further with the fields parameter.You pass one or more fields and the API returns only those fields.The examples in the right pane perform an image search and return only the ID of the image and a link to a preview image.The value of the fields parameter specifies fields in the same way that Google supports it across many of their APIs.For more information, see Partial responses in the Google API documentation.
To specify the fields to return, use slashes to indicate the position of the field in the hierarchy of the normal JSON response.For example, the value data(id,assets/preview/url) returns the data.id field and the data.assets.preview.url field.
A 400 Bad Request response often means that the request body is improperly formatted or missing required fields.In the case of missing fields, the response includes the name of the field that is missing, as in the example in the right-hand column.
A 500 Internal Server Error response means that an error happened on the server.This can mean that the request is not valid, such as if you try to delete or edit a collection that does not exist, or if the API otherwise can't do what you requested.It can also mean a temporary problem with the API.Check your request and try again or contact us.
The licensing endpoints return the same errors as other endpoints for authentication problems, such as if the token is not valid.For other problems, such as if the requested media is not found, the licensing endpoints return a 200 OK response and an error message in the response body.
All applications are limited to a certain number of API requests per minute.If your application exceeds its limit, the API returns an error response with a status code of 429.The message in the response states the UTC time in milliseconds for when the application's quota renews, as in this example:
To access the API, you need an API application and either a free or paid API subscription.The type of subscription determines which media library you have access to and what level of access you have to other features such as reverse image search.To set up a paid API subscription, see the API subscription page.To set up a free API subscription, create an application and select the free subscription as described in Applications.
These API subscriptions are separate from the subscriptions that are available on the Shutterstock web site, so be sure to get an API subscription if you want to work with the API.See
You can use an API subscription to license and download media only with the API; API subscriptions don't work on the Shutterstock web site.If you have a subscription that does not include API access and want to use it with the API, contact us.
Each type of subscription provides access to a specific media library; all API requests use only the media in that library, including search, details, and licensing requests.For example, when you search with a 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.
To access the REST API you need an application, which represents the application, program, or computer commands that are accessing the API.To use the API, you need the application's consumer key and consumer secret, which are shown on the page.
When you have the application's consumer key and consumer secret, you can use them to access the API directly or to request a token that you can use to access the API.For more information on these methods of authentication, see Authentication.
Referrer: If you are creating a front-end or client-side integration or using one of Shutterstock's front-end integrations, such as the Shutterstock UI search widget, specify a comma-separated list of valid referrer domains and paths, such as "mycompany.com/myApplication."Each item in the list must match one of the callback host names.
When you add paths to this list, the API accepts requests with an HTTP Referer header from one of these paths and with the API key in the api_key query parameter. Front-end integrations often use this style of authentication to hide secrets from the end user.
Included products: This list shows the API products that the application has access to.To get access to other products, contact your Shutterstock representative, visit the Pricing page or contact us.
Subscription: Optionally, select this check box to start a free subscription or use your existing free subscription.If you have a paid subscription, you can use it with any of your applications.
The new application appears on the My apps page.Each application has a consumer key and a consumer secret.You use this consumer key and consumer secret either to use the API directly with basic authentication or to request a token for OAuth authentication; see Authentication.Do not share your key and secret, because they can be used to access your account through the API.
Each application has access to one or more API products.These products control the media library that the application accesses and whether the application can access other features such as reverse image search.These products are separate from the subscriptions that control how many assets you can license and download and what level of access the application has to other features.
Most endpoints require OAuth 2.0 authentication.In this type of authentication, you use an application and an individual user's login credentials to obtain a token.Then you can use that token as credentials for API requests in place of a user name and password.
Some endpoints require one or more scopes, or permissions, which let the user control what the application can do with the token.For example, to edit a user's collections, the token must include the collections.edit scope.Applications can request multiple tokens with different scopes or a single token with multiple scopes.
Open the URL in a web browser, log in, and allow your Shutterstock account to access the callback host name.The Permission Request window lets you make sure that you want to let programs with the token access your Shutterstock account with the specific permissions:
When you click Allow, the Shutterstock API redirects your web browser to the callback URL with information in the parameters. If you don't have a full application set up yet, the browser gives an error because the web page isn't available, but that's OK because for now, all you need is the URL. Here's an example:
For testing the API, copy the authentication code from the URL (in the previous example, it's ABC123) and use it in the next step. When you're ready to code a complete application, you can set it up to embed or refer to the login web page, accept the request from this URL, and store the information from the URL parameters. This code can be used only once, and it expires after 5 minutes.
4a15465005