To search for media with the Shutterstock API, you need:

  • An account at https://www.shutterstock.com
  • An application at https://developers.shutterstock.com/user/me/apps
  • One of these types of authentication:
    • Basic authentication: You provide the client ID and client secret with each API request.
    • OAuth authentication: You use the client ID and client secret to get an authentication token and use this token in each request. In the examples on this page, the access token is in the SHUTTERSTOCK_API_TOKEN environment variable.

Some API subscriptions return a limited set of results. See Subscriptions in the API reference.

Here are some examples of searches that use these types of authentication:

Searching with basic authentication

cURL

curl -X GET "https://api.shutterstock.com/v2/images/search" \
--user 123abc456def:1a2b3c4d \
-G \
--data-urlencode "query=sunrise"
--data-urlencode "image_type=photo" \
--data-urlencode "page=1" \
--data-urlencode "per_page=5" \
--data-urlencode "sort=popular" \
--data-urlencode "view=minimal"

PHP

$queryFields = [
  "query" => "sunrise",
  "image_type" => "photo",
  "page" => 1,
  "per_page" => 5,
  "sort" => "popular",
  "view" => "minimal"
];

$options = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/images/search?" . http_build_query($queryFields),
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
  CURLOPT_USERPWD => "123abc456def:1a2b3c4d",
  CURLOPT_RETURNTRANSFER => 1
];

$handle = curl_init();
curl_setopt_array($handle, $options);
$response = curl_exec($handle);
curl_close($handle);

$decodedResponse = json_decode($response);
print_r($decodedResponse);

JavaScript

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

const applicationClientId = "123abc456def";
const applicationClientSecret = "1a2b3c4d";
sstk.setBasicAuth(applicationClientId, applicationClientSecret);

const imagesApi = new sstk.ImagesApi();

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

imagesApi.searchImages(queryParams)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

Searching with OAuth authentication

cURL

curl -X GET "https://api.shutterstock.com/v2/images/search" \
--header "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=kites" \
--data-urlencode "image_type=photo" \
--data-urlencode "page=1" \
--data-urlencode "per_page=5" \
--data-urlencode "sort=popular" \
--data-urlencode "view=minimal"

PHP

$queryFields = [
  "query" => "kites",
  "image_type" => "photo",
  "page" => 1,
  "per_page" => 5,
  "sort" => "popular",
  "view" => "minimal"
];

$options = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/images/search?" . http_build_query($queryFields),
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$handle = curl_init();
curl_setopt_array($handle, $options);
$response = curl_exec($handle);
curl_close($handle);

$decodedResponse = json_decode($response);
print_r($decodedResponse);

JavaScript

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(data);
  })
  .catch((error) => {
    console.error(error);
  });

For more information about authentication, see Authentication.

Keyword searches

To search for media with a keyword, pass the search keywords to the appropriate endpoint:

  • Images: GET https://api.shutterstock.com/v2/images/search
  • Video: GET https://api.shutterstock.com/v2/videos/search
  • Audio: GET https://api.shutterstock.com/v2/audio/search

The search keywords must be URL encoded and in the query query parameter. For examples of search results, see Results.

Here are some examples of simple image, video, and audio search requests:

Simple image keyword search

cURL

curl -X GET "https://api.shutterstock.com/v2/images/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=kites"

PHP

$queryFields = [
  "query" => "kites"
];

$options = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/images/search?" . http_build_query($queryFields),
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$handle = curl_init();
curl_setopt_array($handle, $options);
$response = curl_exec($handle);
curl_close($handle);

$decodedResponse = json_decode($response);
print_r($decodedResponse);

JavaScript

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const imagesApi = new sstk.ImagesApi();

const queryParams = {
  "query": "kites"
};

imagesApi.searchImages(queryParams)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

Simple video keyword search

cURL

curl -X GET "https://api.shutterstock.com/v2/videos/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=hot air balloon"

PHP

$queryFields = [
  "query" => "hot air balloon"
];

$options = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/videos/search?" . http_build_query($queryFields),
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$handle = curl_init();
curl_setopt_array($handle, $options);
$response = curl_exec($handle);
curl_close($handle);

$decodedResponse = json_decode($response);
print_r($decodedResponse);

JavaScript

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const videosApi = new sstk.VideosApi();

const queryParams = {
  "query": "hot air balloon"
};

videosApi.searchVideos(queryParams)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

Simple audio keyword search

cURL

curl -X GET "https://api.shutterstock.com/v2/audio/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=bluegrass"

PHP

$queryFields = [
  "query" => "bluegrass"
];

$options = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/audio/search?" . http_build_query($queryFields),
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$handle = curl_init();
curl_setopt_array($handle, $options);
$response = curl_exec($handle);
curl_close($handle);

$decodedResponse = json_decode($response);
print_r($decodedResponse);

JavaScript

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const audioApi = new sstk.AudioApi();

const queryParams = {
  "query": "bluegrass"
};

audioApi.searchAudio(queryParams)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

Wildcards

Searches do not support wildcards such as *. Instead, all keywords have an implicit wildcard at the end. For example, searching for door includes results with the keywords doors and doorbell.

Conditional searches

Searches for images and video can use AND, OR, and NOT conditions, but searches for audio do not support these keywords.

To use AND, OR, or NOT in searches, you include these operators in the query query parameter. The operators must be in upper case and they must be in English, regardless of the language the keywords are in.

  • AND is added implicitly between each search keyword. Therefore, searching for dog AND cat is equivalent to searching for dog cat.
  • OR searches for results that include any of the specified keywords, such as dog OR cat OR mouse.
  • NOT searches exclude keywords from search results, such as dog NOT hot dog. You can also use NOT in the contributor search field.

You can group conditional search terms with parentheses. For example, to search for images with either dogs or cats, but not both, use (dog NOT cat) OR (cat NOT dog).

Here are some examples of searching with conditions:

cURL

curl -X GET "https://api.shutterstock.com/v2/images/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=dog AND cat"

curl -X GET "https://api.shutterstock.com/v2/videos/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=mountain NOT camping"

PHP

$inclusionQueryFields = [
  "query" => "dog AND cat"
];

$inclusionOptions = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/images/search?" . http_build_query($inclusionQueryFields),
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$inclusionHandle = curl_init();
curl_setopt_array($inclusionHandle, $inclusionOptions);
$inclusionResponse = curl_exec($inclusionHandle);
curl_close($inclusionHandle);

$inclusionDecodedResponse = json_decode($inclusionResponse);
print_r($inclusionDecodedResponse);


$exclusionQueryFields = [
  "query" => "mountain NOT camping"
];

$exclusionOptions = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/images/search?" . http_build_query($exclusionQueryFields),
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$exclusionHandle = curl_init();
curl_setopt_array($exclusionHandle, $exclusionOptions);
$exclusionResponse = curl_exec($exclusionHandle);
curl_close($exclusionHandle);

$exclusionDecodedResponse = json_decode($exclusionResponse);
print_r($exclusionDecodedResponse);

JavaScript

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const imagesApi = new sstk.ImagesApi();

const queryParamsAND = {
  "query": "dog AND cat"
};

imagesApi.searchImages(queryParamsAND)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

const queryParamsNOT = {
  "query": "mountain NOT camping"
};

imagesApi.searchImages(queryParamsNOT)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

Paging results

Each search endpoint (as well as many other endpoints) can split the response 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. You can show up to 500 results per page. For example:

cURL

curl -X GET "https://api.shutterstock.com/v2/images/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=giraffes" \
--data-urlencode "page=2" \
--data-urlencode "per_page=5"

PHP

$queryFields = [
  "query" => "giraffes",
  "page" => 2,
  "per_page" => 5
];

$options = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/images/search?" . http_build_query($queryFields),
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$handle = curl_init();
curl_setopt_array($handle, $options);
$response = curl_exec($handle);
curl_close($handle);

$decodedResponse = json_decode($response);
print_r($decodedResponse);

JavaScript

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const imagesApi = new sstk.ImagesApi();

const queryParams = {
  "query": "giraffes",
  "page": "2",
  "per_page": "5"
};

imagesApi.searchImages(queryParams)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

Sorting results

The sort parameter controls how results are ordered. By default, image and video searches return the most popular media first, and audio searches return the tracks that best match the overall search criteria first. Use the sort_order parameter to specify if the results are in ascending ("asc") or descending ("desc," the default) order.

The image and video search endpoints can order results in the following ways:

  • "newest": Sort by when the image was added.
  • "popular": Sort by the popularity of the image.
  • "random": Return the search results in random order.
  • "relevance": Sort by how well the result matches the overall search criteria.

The audio search endpoint can sort results in the following ways:

  • "artist": Sort by the artist name.
  • "bpm": Sort by beats per minute.
  • "duration": Sort by the length of the track.
  • "freshness": Sort by when the track was added.
  • "ranking_all": Sort by aggregated factors including popularity, keywords, and views.
  • "score": Sort by the relevancy score based on the search query.
  • "title": Sort alphabetically by title.

Here are some examples:

cURL

curl -X GET "https://api.shutterstock.com/v2/videos/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=boats" \
--data-urlencode "sort=popular"


curl -X GET "https://api.shutterstock.com/v2/audio/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "instruments=Piano" \
--data-urlencode "duration_from=300"
--data-urlencode "sort=bpm" \
--data-urlencode "sort_order=desc"

PHP

$videoQueryFields = [
  "query" => "boats",
  "sort" => "popular"
];

$videoOptions = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/videos/search?" . http_build_query($videoQueryFields),
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$videoHandle = curl_init();
curl_setopt_array($videoHandle, $videoOptions);
$videoResponse = curl_exec($videoHandle);
curl_close($videoHandle);

$videoDecodedResponse = json_decode($videoResponse);
print_r($videoDecodedResponse);


$audioQueryFields = [
  "query" => "Piano",
  "duration_from" => 300,
  "sort" => "bpm",
  "sort_order" => "desc"
];

$audioOptions = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/audio/search?" . http_build_query($audioQueryFields),
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$audioHandle = curl_init();
curl_setopt_array($audioHandle, $audioOptions);
$audioResponse = curl_exec($audioHandle);
curl_close($audioHandle);

$audioDecodedResponse = json_decode($audioResponse);
print_r($audioDecodedResponse);

JavaScript

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const videosApi = new sstk.VideosApi();

const queryParamsVideo = {
  "query": "boats",
  "sort": "popular"
};

videosApi.searchVideos(queryParamsVideo)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

const audioApi = new sstk.AudioApi();

const queryParamsAudio = {
  "query": "Piano",
  "duration_from": "300",
  "sort": "bpm",
  "sort_order": "desc"
};

audioApi.searchAudio(queryParamsAudio)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

Result detail

The view parameter 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 (human-curated descriptors) and categories (Shutterstock-assigned genres) that apply to each image.

For examples of the results, see Results.

Search languages

You can provide search keywords in the following languages by specifying the two-character country code in the language parameter.

  • Czech (cs)
  • Danish (da)
  • German (de)
  • English (en)
  • Spanish (es)
  • Finnish (fi)
  • French (fr)
  • Hungarian (hu)
  • Italian (it)
  • Japanese (ja)
  • Korean (ko)
  • Norwegian (nb)
  • Dutch (nl)
  • Polish (pl)
  • Portuguese (pt)
  • Russian (ru)
  • Swedish (sv)
  • Thai (th)
  • Turkish (tr)
  • Chinese (zh)

For example:

cURL

curl -X GET "https://api.shutterstock.com/v2/images/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=chien" \
--data-urlencode "language=fr"

curl -X GET "https://api.shutterstock.com/v2/images/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=perro" \
--data-urlencode "language=es"

PHP

$frenchQueryFields = [
  "query" => "chien",
  "language" => "fr"
];

$frenchOptions = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/images/search?" . http_build_query($frenchQueryFields),
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$frenchHandle = curl_init();
curl_setopt_array($frenchHandle, $frenchOptions);
$frenchResponse = curl_exec($frenchHandle);
curl_close($frenchHandle);

$frenchDecodedResponse = json_decode($frenchResponse);
print_r($frenchDecodedResponse);


$spanishQueryFields = [
  "query" => "perro",
  "language" => "es"
];

$spanishOptions = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/images/search?" . http_build_query($spanishQueryFields),
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$spanishHandle = curl_init();
curl_setopt_array($spanishHandle, $spanishOptions);
$spanishResponse = curl_exec($spanishHandle);
curl_close($spanishHandle);

$spanishDecodedResponse = json_decode($spanishResponse);
print_r($spanishDecodedResponse);

JavaScript

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const imagesApi = new sstk.ImagesApi();

const queryParamsFr = {
  "query": "chien",
  "language": "fr"
};

imagesApi.searchImages(queryParamsFr)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

const queryParamsEs = {
  "query": "perro",
  "language": "es"
};

imagesApi.searchImages(queryParamsEs)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

Search parameters

cURL

curl -X GET "https://api.shutterstock.com/v2/images/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=dog" \
--data-urlencode "image_type=illustration" \
--data-urlencode "image_type=vector" \
--data-urlencode "license=enhanced" \
--data-urlencode "license=sensitive"

PHP

$query = [
  "query" => "dog",
  "image_type" => "illustration",
  "image_type" => "vector",
  "license" => "enhanced",
  "license" => "sensitive"
];

$options = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/audio/search?" . http_build_query($query),
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$handle = curl_init();
curl_setopt_array($handle, $options);
$response = curl_exec($handle);
curl_close($handle);

$decodedResponse = json_decode($response);
print_r($decodedResponse);

JavaScript

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const imagesApi = new sstk.ImagesApi();

const queryParams = {
  "query": "dog",
  "image_type": "illustration",
  "image_type": "vector",
  "license": "enhanced",
  "license": "sensitive"
};

imagesApi.searchImages(queryParams)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

Aside from the keywords in the query field, search requests can include many other search fields. The following sections show common search parameters for image, video, and audio searches.

Some parameters in the search endpoints (and other endpoints) can accept more than one value. In this case, you can specify the same parameter more than one time, as in the example in the right-hand pane. For more information about using parameters multiple times, see Passing multiple values.

For a complete list of these search parameters, see the API documentation for the search endpoints:

Here are examples of searching with multiple fields:

cURL

curl -X GET "https://api.shutterstock.com/v2/images/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=earthquake" \
--data-urlencode "sort=newest" \
--data-urlencode "image_type=photo"


curl -X GET "https://api.shutterstock.com/v2/images/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "sort=popular" \
--data-urlencode "category=Holidays"

PHP

$newestQueryFields = [
  "query" => "earthquake",
  "sort" => "newest",
  "image_type" => "photo"
];

$newestOptions = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/images/search?" . http_build_query($newestQueryFields),
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$newestHandle = curl_init();
curl_setopt_array($newestHandle, $newestOptions);
$newestResponse = curl_exec($newestHandle);
curl_close($newestHandle);

$newestDecodedResponse = json_decode($newestResponse);
print_r($newestDecodedResponse);


$popularQueryFields = [
  "sort" => "popular",
  "category" => "Holidays"
];

$popularOptions = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/images/search?" . http_build_query($popularQueryFields),
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$popularHandle = curl_init();
curl_setopt_array($popularHandle, $popularOptions);
$popularResponse = curl_exec($popularHandle);
curl_close($popularHandle);

$popularDecodedResponse = json_decode($popularResponse);
print_r($popularDecodedResponse);

JavaScript

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const imagesApi = new sstk.ImagesApi();

const queryParams1 = {
  "query": "earthquake",
  "image_type": "photo",
  "sort": "newest"
};

imagesApi.searchImages(queryParams1)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

const queryParams2 = {
  "category": "Holidays",
  "sort": "popular"
};

imagesApi.searchImages(queryParams2)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

Here's an example of providing multiple values for the same field. Note that only certain fields can accept multiple values:

cURL

curl -X GET "https://api.shutterstock.com/v2/audio/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "instrument=Trumpet" \
--data-urlencode "instrument=Drums"

PHP

$query = "instrument=Trumpet&instrument=Drums";

$options = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/audio/search?$query",
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$handle = curl_init();
curl_setopt_array($handle, $options);
$response = curl_exec($handle);
curl_close($handle);

$decodedResponse = json_decode($response);
print_r($decodedResponse);

JavaScript

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const audioApi = new sstk.AudioApi();

const queryParams = {
  "instrument": [ "Trumpet", "Drums" ]
};

audioApi.searchAudio(queryParams)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

Common image search parameters

  • category: The category of the image, such as "People," "Science," or "Holidays." For a full list of categories, see List image categories.
  • color: A prominent color in the image, in hexadecimal code, such as "008000" for green or "FFFF00" for yellow. Omit the # from the color code.
  • image_type: The type of image, one or more of "photo," "vector," or "illustration."
  • orientation: The orientation of the image, "horizontal" or "vertical."
  • license: The license that you want to use the image with, such as "commercial," "editorial," "enhanced," or "sensitive."

To search for images of people, use one or more of these parameters:

  • people_ethnicity: The ethnicity of the people in the image, such as "african_american," "middle_eastern," or "east_asian."
  • people_gender: The gender of the people in the image, such as "male," "female," or "both."
  • people_number: The number of people in the image, from 0-4.
  • people_age: The age of the people in the image, such as "infants," "children," "teenagers," "20s," "30s," "40s," "50s," "60s," or "older."

To search for images by size (in pixels), use these parameters:

  • height_from: Show images with the specified height or larger.
  • height_to: Show images with the specified height or smaller.
  • height: Show images with the exact specified height.
  • width_from: Show images with the specified width or larger.
  • width_to: Show images with the specified width or smaller.
  • width: Show images with the exact specified width.

For a complete list of image search parameters, see Search for images.

For example:

cURL

curl -X GET "https://api.shutterstock.com/v2/images/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=hiking" \
--data-urlencode "image_type=photo" \
--data-urlencode "orientation=vertical" \
--data-urlencode "people_number=3"

curl -X GET "https://api.shutterstock.com/v2/images/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=ocean" \
--data-urlencode "color=FFFF00" \
--data-urlencode "width_from=4096"

PHP

$simpleQueryFields = [
  "query" => "hiking",
  "image_type" => "photo",
  "orientation" => "vertical",
  "people_number" => 3
];

$simpleOptions = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/images/search?" . http_build_query($simpleQueryFields),
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$simpleHandle = curl_init();
curl_setopt_array($simpleHandle, $simpleOptions);
$simpleResponse = curl_exec($simpleHandle);
curl_close($simpleHandle);

$simpleDecodedResponse = json_decode($simpleResponse);
print_r($simpleDecodedResponse);


$colorQueryFields = [
  "query" => "ocean",
  "color" => "FFFF00",
  "width_from" => "4096"
];

$colorOptions = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/images/search?" . http_build_query($colorQueryFields),
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$colorHandle = curl_init();
curl_setopt_array($colorHandle, $colorOptions);
$colorResponse = curl_exec($colorHandle);
curl_close($colorHandle);

$colorDecodedResponse = json_decode($colorResponse);
print_r($colorDecodedResponse);

JavaScript

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const imagesApi = new sstk.ImagesApi();

const queryParams1 = {
  "query": "hiking",
  "image_type": "photo",
  "orientation": "vertical",
  "people_number": "3"
};

imagesApi.searchImages(queryParams1)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

const queryParams2 = {
  "query": "ocean",
  "color": "FFFF00",
  "width_from": "4096"

};

imagesApi.searchImages(queryParams2)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

Common video search parameters

  • aspect_ratio: The aspect ratio of the video, including "4_3," "16_9," or "nonstandard" for other aspect ratios.
  • category: The category of the video, such as "People," "Science," or "Holidays." For a full list of categories, see List video categories.
  • license: The license that you want to use the video with, including "commercial" and "editorial."
  • resolution: The resolution of the video, including "4k", "high_definition," or "standard_definition."

To specify the duration of the video, use these parameters:

  • duration_from: Show videos with the specified length in seconds or longer.
  • duration_to: Show videos with the specified length in seconds or shorter.
  • duration: Show videos with the exact specified length in seconds.

To search for videos by frames per second (FPS), use these parameters:

  • fps_from: Show videos with the specified FPS or greater.
  • fps_to: Show videos with the specified FPS or fewer.
  • fps: Show videos with the exact specified length in seconds.

To search for videos with people, use one or more of these parameters:

  • people_ethnicity: The ethnicity of the people in the video, such as "african_american," "middle_eastern," or "east_asian."
  • people_gender: The gender of the people in the video, such as "male," "female," or "both."
  • people_number: The number of people in the video, from 0-4.
  • people_age: The age of the people in the video, such as "infants," "children," "teenagers," "20s," "30s," "40s," "50s," "60s," or "older."

For a complete list of video search parameters, see Search for videos.

For example:

cURL

curl -X GET "https://api.shutterstock.com/v2/videos/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=cycling" \
--data-urlencode "resolution=4k" \
--data-urlencode "people_number=1"

PHP

$queryFields = [
  "query" => "cycling",
  "resolution" => "4k",
  "people_number" => 1
];

$options = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/videos/search?" . http_build_query($queryFields),
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$handle = curl_init();
curl_setopt_array($handle, $options);
$response = curl_exec($handle);
curl_close($handle);

$decodedResponse = json_decode($response);
print_r($decodedResponse);

JavaScript

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const videosApi = new sstk.VideosApi();

const queryParams = {
  "query": "cycling",
  "resolution": "4k",
  "people_number": "1"
};

videosApi.searchVideos(qeryParams)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

Common audio search parameters

  • genre: The musical genre of the track, such as "Blues," "Holiday," or "R&B/Soul."
  • is_instrumental: Whether the music is instrumental (true) or has lyrics (false).
  • instruments: One or more instruments in the track, such as "Guitar" or "Piano."
  • moods: The mood type of the track, such as "Uplifting" or "Aggressive."

To search for tracks by beats per minute (BPM), use these parameters:

  • bpm_from: Show videos with the specified BPM or greater.
  • bpm_to: Show videos with the specified BPM or fewer.
  • bpm: Show videos with the exact specified BPM.

To specify the duration of the track, use these parameters:

  • duration_from: Show tracks with the specified length in seconds or longer.
  • duration_to: Show tracks with the specified length in seconds or shorter.
  • duration: Show tracks with the exact specified length in seconds.

For a complete list of audio search parameters, see Search for tracks.

For example:

cURL

curl -X GET "https://api.shutterstock.com/v2/audio/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "genre=Blues"

PHP

$queryFields = [
  "genre" => "Blues"
];

$options = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/audio/search?" . http_build_query($queryFields),
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$handle = curl_init();
curl_setopt_array($handle, $options);
$response = curl_exec($handle);
curl_close($handle);

$decodedResponse = json_decode($response);
print_r($decodedResponse);

JavaScript

const audioApi = new sstk.AudioApi();

const queryParams = {
  "genre": "Blues"
};

audioApi.searchAudio(queryParams)
  .then(({data}) => {
    console.log(data);
  })
  .catch((error) => {
    console.error(error);
  });

Reverse image search

Reverse image search uses computer vision to provide images that are similar to a reference image that you supply. To use reverse image search, your application must be enabled for computer vision. Please contact us for access.

First, upload your reference image encoded in base 64 to the POST /v2/images endpoint, as in the following examples:

cURL

curl -X POST 'https://api.shutterstock.com/v2/images' \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-H 'Content-Type: application/json' \
-d "{\"base64_image\":\"`base64 myImage.jpg -w 0`\"}"

PHP

$imageData = file_get_contents("myImage.jpg");
$encodedImageData = base64_encode($imageData);

$body = [
  "base64_image" => $encodedImageData
];
$encodedBody = json_encode($body);

$options = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/images",
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => $encodedBody,
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN",
    "Content-Type: application/json"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$handle = curl_init();
curl_setopt_array($handle, $options);
$response = curl_exec($handle);
curl_close($handle);

$decodedResponse = json_decode($response);
print_r($decodedResponse);

JavaScript

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const imagesApi = new sstk.ImagesApi();

const imageFile = fs.readFileSync('./myImage.jpg');
const base64File = Buffer.from(imageFile).toString('base64');

const body = new sstk.ImageCreateRequest(base64File);

const queryParams = {
  "page": 1,
  "per_page": 20,
  "view": 'minimal'
};

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

The API returns a search ID.

{
  "id": "Ue9ecf147307485dc71cf947d1dbb90bd"
}

Then, pass that search ID to the GET /v2/images/{id}/similar endpoint. The API returns up to 200 images that appear visually similar to your image.

cURL

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

PHP

$options = [
  CURLOPT_URL => "https://api.shutterstock.com/v2/images/Ue9ecf147307485dc71cf947d1dbb90bd/similar",
  CURLOPT_USERAGENT => "php/curl",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
  ],
  CURLOPT_RETURNTRANSFER => 1
];

$handle = curl_init();
curl_setopt_array($handle, $options);
$response = curl_exec($handle);
curl_close($handle);

$decodedResponse = json_decode($response);
print_r($decodedResponse);

JavaScript

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

sstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);

const imagesApi = new sstk.ImagesApi();

const imageFile = fs.readFileSync('./myImage.jpg');
const base64File = Buffer.from(imageFile).toString('base64');

const body = new sstk.ImageCreateRequest(base64File);

const queryParams = {
  "page": 1,
  "per_page": 20,
  "view": 'minimal'
};

imagesApi.uploadEphemeralImage(body)
  .then((data) => {
    console.log(data.id);
    api.getSimilarImages(data.id, queryParams)
    .then((similarImageData) => {
      console.log(similarImageData)
    })
  })
  .catch((error) => {
    console.error(error);
  });

Results

The search results start with information about the search and the results, including the search ID, the total number of results, and the paging information. Not all results are returned at once; to page through the results, see Paging results.

Each search result includes one or more preview links that you can use to preview the media before licensing and downloading the full version.

You can sort the search results by factors like the popularity of the media and how recently it was added. For more information about sorting, see Sorting results.

By default, the results show basic information about each search result, including its description, its contributor, information about its dimensions, aspect ratio, or length, and links to previews. You can get more details about each result by including the view=full parameter with the search. For more information, see Result detail.

Here are examples of search results:

Example image search results

Image search responses show information about each image, such as its aspect ratio, its dimensions, the media type (image, in this case, as opposed to video or audio search results), the type of image (such as photo, vector, or illustration), the contributor that provided the image, and a textual description for the image.

{
  "page": 1,
  "per_page": 1,
  "total_count": 6471766,
  "search_id": "BogDL7hW4kdptwSXvWsE3w",
  "data": [
    {
      "id": "755022088",
      "aspect": 1.5,
      "assets": {
        "preview": {
          "height": 300,
          "url": "https://image.shutterstock.com/display_pic_with_logo/2723875/755022088/stock-photo-aerial-view-to-ocean-waves-blue-water-background-755022088.jpg",
          "width": 450
        },
        "small_thumb": {
          "height": 67,
          "url": "https://thumb9.shutterstock.com/thumb_small/2723875/755022088/stock-photo-aerial-view-to-ocean-waves-blue-water-background-755022088.jpg",
          "width": 100
        },
        "large_thumb": {
          "height": 100,
          "url": "https://thumb9.shutterstock.com/thumb_large/2723875/755022088/stock-photo-aerial-view-to-ocean-waves-blue-water-background-755022088.jpg",
          "width": 150
        },
        "huge_thumb": {
          "height": 260,
          "url": "https://image.shutterstock.com/image-photo/aerial-view-ocean-waves-blue-260nw-755022088.jpg",
          "width": 390
        }
      },
      "contributor": {
        "id": "2723875"
      },
      "description": "Aerial view to ocean waves. Blue water background",
      "image_type": "photo",
      "media_type": "image"
    }
  ],
  "spellcheck_info": {}
}

Example video search results

Video search responses video search results include the duration of the video in seconds and the aspect ratio expressed both as a ratio and as a decimal.

{
  "page": 1,
  "per_page": 1,
  "total_count": 323254,
  "search_id": "Kz8nE1uZ8f9SVZiC41DbPQ",
  "data": [
    {
      "media_type": "video",
      "id": "32074804",
      "description": "Large container ship at sea - Top down Aerial ",
      "aspect": 1.778,
      "duration": 39,
      "contributor": {
        "id": "474853"
      },
      "aspect_ratio": "16:9",
      "assets": {
        "thumb_webm": {
          "url": "https://ak4.picdn.net/shutterstock/videos/32074804/thumb/stock-footage-large-container-ship-at-sea-top-down-aerial.webm"
        },
        "thumb_mp4": {
          "url": "https://ak4.picdn.net/shutterstock/videos/32074804/thumb/stock-footage-large-container-ship-at-sea-top-down-aerial.mp4"
        },
        "preview_webm": {
          "url": "https://ak4.picdn.net/shutterstock/videos/32074804/preview/stock-footage-large-container-ship-at-sea-top-down-aerial.webm"
        },
        "preview_mp4": {
          "url": "https://ak4.picdn.net/shutterstock/videos/32074804/preview/stock-footage-large-container-ship-at-sea-top-down-aerial.mp4"
        },
        "thumb_jpg": {
          "url": "https://ak4.picdn.net/shutterstock/videos/32074804/thumb/1.jpg"
        },
        "preview_jpg": {
          "url": "https://ak4.picdn.net/shutterstock/videos/32074804/thumb/1.jpg"
        }
      }
    }
  ]
}

Example audio search results

Audio search results include the file size in bytes and the title for the track.

{
  "page": 1,
  "per_page": 1,
  "total_count": 107,
  "search_id": "d375d427-7ba3-4636-b00b-2fb48a0bf41e",
  "data": [
    {
      "id": "394445",
      "description": "Groovy and whimsical, playful marimba and island percussion create an atmosphere of winsome fun.",
      "assets": {
        "clean_audio": {
          "file_size": 29402944
        },
        "preview_mp3": {
          "file_size": 3676706,
          "url": "https://ak.picdn.net/shutterstock/audio/394445/preview/preview.mp3"
        },
        "preview_ogg": {
          "file_size": 3866129,
          "url": "https://ak.picdn.net/shutterstock/audio/394445/preview/preview.ogg"
        },
        "waveform": {
          "file_size": 19060,
          "url": "https://ak.picdn.net/shutterstock/audio/394445/waveform/waveform.png"
        }
      },
      "title": "Calypso Bird",
      "media_type": "audio",
      "contributor": {
        "id": "2847971"
      },
      "published_time": "2015-09-17T11:31:27-04:00",
      "added_date": "2015-09-17"
    }
  ]
}

Previewing media

To preview the media, use the URLs in the assets section of the search response. Each result includes one or more previews. Images include watermarked previews in different sizes, videos include thumbnail images and low-resolution watermarked preview videos, and audio tracks include versions with voice-overs. You can embed these previews on web pages or link to them.

The dimensions for thumbnail and preview images and videos depend on the aspect ratio of the original images and videos.

Image thumbnail and preview dimensions

Image search results and responses to the GET /v2/images/{id} endpoint include thumbnails and previews in multiple sizes. The response includes the dimensions of each image.

  • small_thumb: Scaled until the larger dimension is 100px, no watermark
  • large_thumb: Scaled until the larger dimension is 150px, no watermark
  • huge_thumb: Scaled to 260px in height, no watermark, available only to paying API customers
  • preview: Scaled until the larger dimension is 450px, watermarked

Video thumbnail and preview dimensions

Thumbnails of videos with aspect ratios less than or equal to 16:9 are 180 pixels in height with an appropriate width for the aspect ratio. For example, 16:9 videos (such as 720p, 1080p, and 4K videos) have thumbnails that are 320x180 pixels, and 4:3 videos have thumbnails that are 238x180 pixels. Thumbnails of videos with aspect ratios greater than 16:9 have a height equal to 320 divided by the aspect ratio. For example, 1.9:1 videos have thumbnails that are 320x168. Video thumbnails are not watermarked.

Previews of videos with aspect ratios less than or equal to 16:9 are 336 pixels in height with an appropriate width. For example, 16:9 videos have previews that are 596x336. Previews of videos with aspect ratios greater than 16:9 have a height equal to 600 divided by the aspect ratio. For example, 1.9:1 videos have previews that are 600x316. Preview videos are watermarked.

Removing the ID from preview versions of images

Shutterstock preview images, such as the images in the results of requests to GET /v2/images/search, come with image IDs (also known as the "whitestrip") embedded on the images. Depending on the orientation of the image, the whitestrip can be on the side or bottom of an image.

Example of preview image with embedded ID

Depending on how you use the preview images, you may prefer to hide this image ID whitestrip. The API can not remove the whitestrip itself, but it provides information that you can use to hide it. When the API returns information about preview images, it provides the dimensions of the image without the whitestrip, as in this example:

{
  "page": 1,
  "per_page": 1,
  "total_count": 3207000,
  "search_id": "pH4mTr97r-nHSY6tUrOeVA",
  "data": [
    {
      "id": "228722404",
      "aspect": 1.4997,
      "assets": {
        "preview": {
          "height": 300,
          "url": "https://image.shutterstock.com/display_pic_with_logo/708811/228722404/stock-photo-forest-road-under-sunset-sunbeams-lane-running-through-the-autumn-deciduous-forest-at-dawn-or-228722404.jpg",
          "width": 450
        },
        "small_thumb": {
          "height": 67,
          "url": "https://thumb7.shutterstock.com/thumb_small/708811/228722404/stock-photo-forest-road-under-sunset-sunbeams-lane-running-through-the-autumn-deciduous-forest-at-dawn-or-228722404.jpg",
          "width": 100
        },
        "large_thumb": {
          "height": 100,
          "url": "https://thumb7.shutterstock.com/thumb_large/708811/228722404/stock-photo-forest-road-under-sunset-sunbeams-lane-running-through-the-autumn-deciduous-forest-at-dawn-or-228722404.jpg",
          "width": 150
        },
        "huge_thumb": {
          "height": 260,
          "url": "https://image.shutterstock.com/image-photo/forest-road-under-sunset-sunbeams-260nw-228722404.jpg",
          "width": 390
        }
      },
      "contributor": {
        "id": "708811"
      },
      "description": "Forest Road Under Sunset Sunbeams. Lane Running Through The Autumn Deciduous Forest At Dawn Or Sunrise. Toned Instant Photo",
      "image_type": "photo",
      "media_type": "image"
    }
  ]
}

The preview image has a whitestrip on the bottom:

Preview image of forest road at sunrise, with whitestrip that shows the image ID

The response from the API says that the image has a height of 300 pixels and a width of 450 pixels. These are the dimensions of the image without the whitestrip. Therefore, you can use a <div> tag and CSS styles to constrain the image to those dimensions, as in this example:

<div style="height:300px;width:450px;overflow:hidden">
<img src="stock-photo-forest-road-under-sunset-sunbeams-lane-running-through-the-autumn-deciduous-forest-at-dawn-or-228722404.jpg">
</div>

As a result, the page shows the image without the whitestrip:

Considerations for responsive UIs and apps

Removing the whitestrip can be problematic for responsive UIs and apps because the styles may not work the same way after browser actions, user actions, and changes in responsive breakpoints. To account for these changes, you can use the dimensions of the image in various cropping methodologies and add-ons. There are many ways to keep the images at the correct dimensions; which technique you use depends on your platform and language.

Next steps

Now that you have the IDs of pieces of media that you're interested in, you can group them into collections (also known as lightboxes, clipboxes, or soundboxes) on the Shutterstock site then pull it through the API into your application. This way, you can offer this media as a custom collection on your platform.

To license and download media, see Licensing and downloading.

Limitations

By default, searches are limited to 2,000 results. If you receive a message that says "Too Many Results: Please provide more query parameters to narrow your search," suggest to your end users that they add more search terms.

If your application requires more than 2000 search results, please contact us.