Searching

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

  • An account at https://www.shutterstock.com
  • An application at https://www.shutterstock.com/account/developers/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. For more information about authentication, see Authentication.

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

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. The API searches for the keywords in all textual fields, including but not limited to the description, keywords, and title. For examples of search results, see Results.

Searches do not support wildcards such as *.

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

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

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

Bulk searches

You can run up to 5 image searches in a single request with the POST /v2/images/bulk_search endpoint. The API returns a maximum of 20 results for each search. To use this endpoint, pass multiple searches in the queries array in the request body. Each search in the queries array has the same parameters as an individual image search.

You can also pass query parameters in the request. These parameters become defaults for each search, but the parameters in the individual searches override them.

Here is an example of sending 2 searches in a single request:

DATA='[
  {
    "query": "cat",
    "license": ["editorial"],
    "sort": "popular"
  },
  {
    "query": "dog",
    "orientation": "horizontal"
  }
]'

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

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 most requests. Some endpoints have different limits; see the description of the per_page parameter for the individual endpoints.

For example:

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"

Sorting results

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. 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 or video, returning images or videos that are often downloaded as a result of searches with similar keywords.
  • "random": Return the search results in random order.
  • "relevance": Sort by how well the result matches the keywords. Relevance also takes into account the age of the media and the popularity of the media.

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

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.

Localizing searches

You can localize searches and their results by setting the language or region for the search.

Search languages

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

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

For example:

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" \
--data-urlencode "region=es"

Geo-ranking results

You can customize image search results based on location with the region parameter. This parameter accepts any ISO 3166-1 alpha-2 country code. You can also specify an IP address in this parameter and the API infers a country code from it.

Based on the location, the API changes rankings to provide more appropriate results. For example, searches for the term "football" return images of different sports depending on the location. Search results are raised or lowered in relevance based on how well they relate to the location.

Search parameters

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 following example. For more information about using parameters multiple times, see Passing multiple values.

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"

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

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

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

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," or "enhanced."

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

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

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 -X GET "https://api.shutterstock.com/v2/audio/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "genre=Blues"

Aspect ratios

To search for images by aspect ratio, specify the ratio as a positive decimal of the width divided by the height. For example, to search for images with a 4:3 aspect ratio, set the aspect_ratio parameter to 1.3333. The search endpoints calculate aspect ratio to four decimal places and return only images that exactly match this decimal aspect ratio.

Images with a higher aspect ratio are wider and images with a lower aspect ratio are narrower. Images with a landscape orientation have aspect ratios greater than 1 and images with a portrait orientation have aspect ratios less than or equal to 1, such as 0.75 for an image with a 3:4 aspect ratio.

Images do not always exactly match a standard ratio. Because of a difference of a few pixels, images that have a ratio of approximately 3:2 can have decimal aspect ratios of 1.4998, 1.5, or 1.5001. To search for images that have an aspect ratio of approximately 1.5, set the aspect_ratio_max parameter to 1.5005 and the aspect_ratio_min parameter to 1.4995.

To search for videos by aspect ratio, set the aspect_ratio parameter to a preset value such as 4_3 or 16_9. The search returns videos that have approximately that aspect ratio.

By default, the API hides media that may not be appropriate for all audiences. The API provides two parameters that you can use to enable this content in the responses of some endpoints:

  • By default, the safe parameter is set to true to enable safe search, which hides media with the Mature Content designation. Shutterstock's content guidelines require contributors to use this designation to manually flag media with sexual content, graphic medical scenes, vulgar language, or other mature subject matter. Flagging media in this way is a subjective decision. For more information, see Why was my content rejected for Mature Content Designation?.

  • By default, the keyword_safe_search parameter is set to true, which hides media based on a list of keywords. Any media with one of the keywords is removed from API responses. The keywords include words related to nudity, offensive language, bodily fluids, drug use, racism, weapons, and violence.

To disable either type of restriction, set one or both of these parameters to false. The image and video search endpoints support both parameters. The recommended images and similar images and videos endpoints support only the safe parameter.

Computer vision provides images and videos that are similar to a reference image that you supply.

To upload an image for reverse image and video search or keyword suggestions with computer vision, use the POST /v2/cv/images endpoint. Then, use the upload ID that this endpoint returns to get similar images or videos from the GET /v2/cv/similar/images or GET /v2/cv/similar/videos endpoints. The API returns up to 200 images or videos that appear visually similar to your image.

Images must be in JPG or PNG format. They can be no larger than 25mb and can be no larger than 10,000 pixels in width or height. Some operating systems have a limit on the size of the parameters that you can send in a command-line request, such as with the curl program. If you see an error such as "Argument list too long," send a smaller image or make the request with a programming language such as PHP or Node.JS.

To use the computer vision endpoints, your application must be enabled for computer vision. Please contact us for access.

RESPONSE=$(curl -X POST 'https://api.shutterstock.com/v2/cv/images' \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-H 'Content-Type: application/json' \
-d "{\"base64_image\":\"`base64myImage.jpg`\"}")

echo "The next step requires the jq program."

UPLOAD_ID=$(jq -r .upload_id <<< $RESPONSE)

curl -X GET https://api.shutterstock.com/v2/cv/similar/images \
-H "Accept: application/json" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "asset_id=$UPLOAD_ID"

Computer vision keyword suggestions

Computer vision can also provide suggested keywords for an image.

To get suggested keywords for an image, upload it to the POST /v2/cv/images endpoint as with reverse image search. Then, use the upload ID that this endpoint returns to get suggested keywords from the GET /v2/cv/keywords endpoint. You can also use the ID of an existing image in the Shutterstock collection. In this case, the suggested keywords may not be the same as the keywords in the image metadata.

RESPONSE=$(curl -X POST 'https://api.shutterstock.com/v2/cv/images' \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-H 'Content-Type: application/json' \
-d "{\"base64_image\":\"`base64myImage.jpg`\"}")

echo "The next step requires the jq program."

UPLOAD_ID=$(jq -r .upload_id <<< $RESPONSE)

curl -X GET https://api.shutterstock.com/v2/cv/keywords \
-H "Accept: application/json" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "asset_id=$UPLOAD_ID"

Shutterstock.AI predicts which assets will perform best based on what you're trying to achieve.

To use AI insights, pass only these parameters to the GET /v2/image/search endpoint:

  • query: One or more search terms separated by spaces as usual. You can use NOT to filter out images that match a term.
  • ai_search: Set to true to use AI search. If you set this parameter to true, you must also specify the next two parameters:
  • ai_objective: Set to awareness, traffic, or conversions based on your goal for the media.
  • ai_industry: ai_industry: The target industry, including automotive, cpg (consumer packaged goods), finance, healthcare, retail, or technology.
  • ai_labels_limit: Optionally, the maximum number of labels to return.

If you are using AI search, you cannot pass any parameters other than query, ai_search, ai_objective, ai_industry, and ai_labels_limit. You cannot pass sorting or paging parameters or any other search filters.

The API uses Shutterstock Predict to determine which assets will accomplish the specified objective for the specified audience. The response from the API sorts images based on how well they satisfy the objective for the target industry.

shutterstock images search-images \
  --query "travel" \
  --ai_search true \
  --ai_objective "awareness" \
  --ai_industry "finance"

To help explain how it ordered the images, the AI lists features that are visible in the images, such as "Person" and "Automobile." It also shows how well images with those features perform for the specified goal compared to other images. Analyzing these features is part of how the AI determines which images satisfy the goal.

The top-level insights object shows the top features that the AI thinks perform best for the specified industry and objective. The percentile_performance field shows how well images with a certain feature perform compared to images without the feature. These percentages depend on the audience and industry in the request, so if you use different audiences or industries, the API returns different features and percentages. These features are not the same as the categories that the API uses to classify images via GET /v2/images/categories.

For example, this truncated response shows that images with the "Automobile" label perform better than 98.7% of all other images for the goal specified in the request. These percentages may change as the AI learns over time.

Each image in the response has a labels array that lists the features that the AI sees in the image. This array includes only the labels that are in the insights.label_performance array, not every label that the AI sees in the image.

{
  "page": 1,
  "per_page": 20,
  "total_count": 12345678,
  "data": [
    {
      "id": 87654321,
      "description": "An image of a car, a person, and a dog",
      "assets": {...},
      "insights": {
        "labels": [
          "Automobile",
          "Dog",
          "Person"
        ]
      }
    },
    {
      "id": 98765432,
      "description": "An image of a car with a driver and no dog",
      "assets": {...},
      "insights": {
        "labels": [
          "Automobile",
          "Person"
        ]
      }
    }
  ],
  "insights": {
    "label_performance": [
      {
        "name": "Automobile",
        "percentile_performance": 98.7
      },
      {
        "name": "Person",
        "percentile_performance": 96.8
      },
      {
        "name": "Dog",
        "percentile_performance": 92.3
      },
      {
        ...
      }
    ]
  }
}

To use the AI search, your application must be enabled for AI search. Contact us for access.

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
        },
        "preview_1000": {
          "url": "https://ak.picdn.net/shutterstock/photos/755022088/watermark_1000/4aa68fbdca3b3c6b9792a555c7b793e9/preview_1000-755022088.jpg",
          "width": 1000,
          "height": 667
        },
        "preview_1500": {
          "url": "https://image.shutterstock.com/z/stock-photo-aerial-view-to-ocean-waves-blue-water-background-755022088.jpg",
          "width": 1500,
          "height": 1000
        }
      },
      "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. Which sizes appear in your response depends on the type of your account.

  • 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. This size is available only to paying API customers.
  • preview: Scaled until the larger dimension is 450px, watermarked.
  • preview_1000: Scaled until the larger dimension is 1000px, watermarked. This size is available only to paying API customers.
  • preview_1500: Scaled until the larger dimension is 1500px, watermarked. This size is available only to paying API customers.

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 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 and thumbnails, 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. This example shows a whitestrip at the bottom of a thumbnail image:

Depending on how you use the previews or thumbnails, 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 or thumbnails, 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
        },
        "preview_1000": {
          "url": "https://ak.picdn.net/shutterstock/photos/228722404/watermark_1000/007874edefea7d358134ea6c9e29324f/preview_1000-228722404.jpg",
          "width": 1000,
          "height": 667
        },
        "preview_1500": {
          "url": "https://image.shutterstock.com/z/stock-photo-forest-road-under-sunset-sunbeams-lane-running-through-the-autumn-deciduous-forest-at-dawn-or-228722404.jpg",
          "width": 1500,
          "height": 1000
        }
      },
      "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 and thumbnails have a whitestrip on the bottom:

The response from the API says that the preview 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 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.