openapi: 3.0.0
info:
title: Shutterstock API Reference
description: 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. The API enables searching, browsing, licensing, and downloading
images, videos, audio tracks, and sound effects. It also supports editorial content, computer vision features, collection
management, and OAuth 2.0 authentication.
version: 1.0.30
contact:
name: Shutterstock Developer Support
url: https://www.shutterstock.com/developers/contact-us
license:
name: Shutterstock API Terms
url: https://www.shutterstock.com/api/terms
paths:
/v2/images/search:
get:
parameters:
- description: Show images added on the specified date
in: query
name: added_date
schema:
type: string
format: date
- description: Show images added on or after the specified date
in: query
name: added_date_start
schema:
type: string
format: date
- description: Show images with the specified aspect ratio or higher, using a positive decimal of the width divided
by the height, such as 1.7778 for a 16:9 image
in: query
name: aspect_ratio_min
schema:
type: number
minimum: 0
exclusiveMinimum: true
- description: Show images with the specified aspect ratio or lower, using a positive decimal of the width divided by
the height, such as 1.7778 for a 16:9 image
in: query
name: aspect_ratio_max
schema:
type: number
minimum: 0
exclusiveMinimum: true
- description: Show images with the specified aspect ratio, using a positive decimal of the width divided by the height,
such as 1.7778 for a 16:9 image
in: query
name: aspect_ratio
schema:
type: number
minimum: 0
exclusiveMinimum: true
- description: Show images added before the specified date
in: query
name: added_date_end
schema:
type: string
format: date
- description: Show images with the specified Shutterstock-defined category; specify a category name or ID
in: query
name: category
schema:
type: string
- description: Specify either a hexadecimal color in the format '4F21EA' or 'grayscale'; the API groups it into one
of 15 color categories and returns images that primarily use that color category
in: query
name: color
schema:
type: string
- description: Show images with the specified contributor names or IDs, allows multiple
in: query
name: contributor
schema:
type: array
items:
type: string
- description: Show images from contributors in one or more specified countries
in: query
name: contributor_country
schema:
type: array
items:
type: string
format: country-code-2
- description: Fields to display in the response; see the documentation for the fields parameter in the overview section
in: query
name: fields
schema:
type: string
uniqueItems: true
- description: (Deprecated; use height_from and height_to instead) Show images with the specified height
in: query
name: height
deprecated: true
schema:
type: integer
- description: Show images with the specified height or larger, in pixels
in: query
name: height_from
schema:
type: integer
- description: Show images with the specified height or smaller, in pixels
in: query
name: height_to
schema:
type: integer
- description: Show images of the specified type
in: query
name: image_type
schema:
type: array
items:
enum:
- photo
- illustration
- vector
type: string
- description: Hide results with potentially unsafe keywords
in: query
name: keyword_safe_search
schema:
type: boolean
default: true
- description: Set query and result language (uses Accept-Language header if not set)
in: query
name: language
schema:
$ref: '#/components/schemas/Language'
- description: Show only images with the specified license
in: query
name: license
schema:
type: array
items:
default: commercial
enum:
- commercial
- editorial
- enhanced
type: string
- description: Show image results with the specified model IDs
in: query
name: model
schema:
type: array
items:
type: string
- description: Show image results with horizontal or vertical orientation
in: query
name: orientation
schema:
type: string
enum:
- horizontal
- vertical
- description: Page number
in: query
name: page
schema:
type: integer
minimum: 1
default: 1
- description: Number of results per page
in: query
name: per_page
schema:
type: integer
minimum: 0
maximum: 500
default: 20
- description: Show images of people with a signed model release
in: query
name: people_model_released
schema:
type: boolean
- description: Show images that feature people of the specified age category
in: query
name: people_age
schema:
type: string
enum:
- infants
- children
- teenagers
- 20s
- 30s
- 40s
- 50s
- 60s
- older
- description: Show images with people of the specified ethnicities
in: query
name: people_ethnicity
schema:
type: array
items:
enum:
- african
- african_american
- black
- brazilian
- chinese
- caucasian
- east_asian
- hispanic
- japanese
- middle_eastern
- native_american
- pacific_islander
- south_asian
- southeast_asian
- other
type: string
- description: Show images with people of the specified gender
in: query
name: people_gender
schema:
type: string
enum:
- male
- female
- both
- description: Show images with the specified number of people
in: query
name: people_number
schema:
type: integer
minimum: 0
maximum: 4
- description: One or more search terms separated by spaces; you can use NOT to filter out images that match a term
in: query
name: query
schema:
type: string
- description: Raise or lower search result rankings based on the result's relevance to a specified region; you can
provide a country code or an IP address from which the API infers a country
in: query
name: region
schema:
anyOf:
- type: string
format: country-code-2
- type: string
format: ipv4
- description: Enable or disable safe search
in: query
name: safe
schema:
type: boolean
default: true
- description: Sort by
in: query
name: sort
schema:
type: string
enum:
- newest
- popular
- relevance
- random
default: popular
- description: Spellcheck the search query and return results on suggested spellings
in: query
name: spellcheck_query
schema:
type: boolean
default: true
- description: Amount of detail to render in the response
in: query
name: view
schema:
type: string
enum:
- minimal
- full
default: minimal
- description: (Deprecated; use width_from and width_to instead) Show images with the specified width
in: query
name: width
deprecated: true
schema:
type: integer
- description: Show images with the specified width or larger, in pixels
in: query
name: width_from
schema:
type: integer
- description: Show images with the specified width or smaller, in pixels
in: query
name: width_to
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ImageSearchResults'
examples:
response:
value:
page: 1
per_page: 1
total_count: 193097419
search_id: p5S6QwRikdFJTHXwsoiqTg
data:
- id: '1120280123'
aspect: 1.6667
assets:
preview:
height: 269
url: https://image.shutterstock.com/display_pic_with_logo/3673637/1120280123/stock-vector-minimal-geometric-background-dynamic-shapes-composition-eps-vector-1120280123.jpg
width: 450
small_thumb:
height: 60
url: https://thumb10.shutterstock.com/thumb_small/3673637/1120280123/stock-vector-minimal-geometric-background-dynamic-shapes-composition-eps-vector-1120280123.jpg
width: 100
large_thumb:
height: 90
url: https://thumb10.shutterstock.com/thumb_large/3673637/1120280123/stock-vector-minimal-geometric-background-dynamic-shapes-composition-eps-vector-1120280123.jpg
width: 150
huge_thumb:
height: 260
url: https://image.shutterstock.com/image-vector/minimal-geometric-background-dynamic-shapes-260nw-1120280123.jpg
width: 435
preview_1000:
url: https://ak.picdn.net/shutterstock/photos/1120280123/watermark_1000/f4954f705e782cc12cd13910137e3555/preview_1000-1120280123.jpg
width: 1000
height: 600
preview_1500:
url: https://image.shutterstock.com/z/stock-vector-minimal-geometric-background-dynamic-shapes-composition-eps-vector-1120280123.jpg
width: 1500
height: 900
contributor:
id: '3673637'
description: Minimal geometric background. Dynamic shapes composition. Eps10 vector.
image_type: vector
has_model_release: false
media_type: image
url: https://www.shutterstock.com/image-photo/1120280123
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
security:
- basic: []
- customer_accessCode: []
tags:
- images
x-code-samples:
- lang: shell
source: 'curl -X GET https://api.shutterstock.com/v2/images/search \
-H "Accept: application/json" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=Vienna" \
--data-urlencode "orientation=horizontal" \
--data-urlencode "sort=popular"
'
- lang: javascript--nodejs
source: "const sstk = require(\"shutterstock-api\");\n\nsstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);\n\
\nconst imagesApi = new sstk.ImagesApi();\n\nconst queryParams = {\n \"query\": \"New York\",\n \"sort\": \"popular\"\
,\n \"orientation\": \"horizontal\"\n};\n\nimagesApi.searchImages(queryParams)\n .then((data) => {\n console.log(data);\n\
\ })\n .catch((error) => {\n console.error(error);\n });\n"
- lang: php
source: "$queryFields = [\n \"query\" => \"New York\",\n \"sort\" => \"popular\",\n \"orientation\" => \"horizontal\"\
\n];\n\n$options = [\n CURLOPT_URL => \"https://api.shutterstock.com/v2/images/search?\" . http_build_query($queryFields),\n\
\ CURLOPT_USERAGENT => \"php/curl\",\n CURLOPT_HTTPHEADER => [\n \"Authorization: Bearer $SHUTTERSTOCK_API_TOKEN\"\
\n ],\n CURLOPT_RETURNTRANSFER => 1\n];\n\n$handle = curl_init();\ncurl_setopt_array($handle, $options);\n$response\
\ = curl_exec($handle);\ncurl_close($handle);\n\n$decodedResponse = json_decode($response);\nprint_r($decodedResponse);\n"
operationId: searchImages
summary: Search for images
description: This endpoint searches for images. If you specify more than one search parameter, the API uses an AND condition.
Array parameters can be specified multiple times; in this case, the API uses an AND or an OR condition with those
values, depending on the parameter. You can also filter search terms out in the `query` parameter by prefixing the
term with NOT. Free API accounts show results only from a limited library of media, not the full Shutterstock media
library. Also, the number of search fields they can use in a request is limited.
/v2/images/search/suggestions:
get:
parameters:
- description: Search term for which you want keyword suggestions
in: query
name: query
required: true
example: cats
schema:
type: string
- description: Limit the number of suggestions
in: query
name: limit
schema:
type: integer
default: 10
minimum: 1
maximum: 25
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Suggestions'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
security:
- basic: []
- customer_accessCode: []
tags:
- images
operationId: getImageSuggestions
summary: Get suggestions for a search term
description: This endpoint provides autocomplete suggestions for partial search terms.
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchEntitiesRequest'
description: Plain text to extract keywords from
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SearchEntitiesResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
security:
- basic: []
- customer_accessCode: []
x-code-samples:
- lang: shell
source: 'DATA=''{"text": "The beach is a wonderful place to visit. It has beautiful sand and ocean waves."}''
curl -X POST https://api.shutterstock.com/v2/images/search/suggestions \
-d "$DATA" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN"
'
- lang: javascript--nodejs
source: "const sstk = require(\"shutterstock-api\");\n\nsstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);\n\
\nconst imagesApi = new sstk.ImagesApi();\n\nconst body = {\n \"text\": \"The beach is a wonderful place to visit.\
\ It has beautiful sand and ocean waves.\"\n};\n\nimagesApi.postImageEntities(body)\n .then((data) => {\n console.log(data);\n\
\ })\n .catch((error) => {\n console.error(error);\n });\n"
- lang: php
source: "$body = [\n \"text\" => \"The beach is a wonderful place to visit. It has beautiful sand and ocean waves.\"\
\n];\n$encodedBody = json_encode($body);\n\n$options = [\n CURLOPT_URL => \"https://api.shutterstock.com/v2/images/search/suggestions\"\
,\n CURLOPT_CUSTOMREQUEST => \"POST\",\n CURLOPT_POSTFIELDS => $encodedBody,\n CURLOPT_USERAGENT => \"php/curl\"\
,\n CURLOPT_HTTPHEADER => [\n \"Authorization: Bearer $SHUTTERSTOCK_API_TOKEN\",\n \"Content-Type: application/json\"\
\n ],\n CURLOPT_RETURNTRANSFER => 1\n];\n\n$handle = curl_init();\ncurl_setopt_array($handle, $options);\n$response\
\ = curl_exec($handle);\ncurl_close($handle);\n\n$decodedResponse = json_decode($response);\nprint_r($decodedResponse);\n"
tags:
- images
operationId: postImageEntities
summary: Get keywords from text
description: This endpoint returns up to 10 important keywords from a block of plain text.
/v2/images/{id}:
get:
parameters:
- description: Image ID
in: path
name: id
required: true
example: '465011609'
schema:
type: string
- description: Language for the keywords and categories in the response
in: query
name: language
example: es
schema:
$ref: '#/components/schemas/Language'
- description: Amount of detail to render in the response
in: query
name: view
schema:
type: string
enum:
- minimal
- full
default: full
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Image'
examples:
response:
value:
id: '465011609'
added_date: '2016-08-07'
aspect: 0.8501
assets:
huge_jpg:
display_name: Huge
dpi: 300
file_size: 6980608
format: jpg
height: 4902
is_licensable: true
width: 4167
vector_eps:
display_name: Vector
format: eps
is_licensable: true
preview:
height: 450
url: https://image.shutterstock.com/display_pic_with_logo/1384888/465011609/stock-vector-happy-mid-autumn-festival-background-with-golden-glitter-moon-and-hand-drawn-moon-rabbits-vector-465011609.jpg
width: 382
small_thumb:
height: 100
url: https://thumb7.shutterstock.com/thumb_small/1384888/465011609/stock-vector-happy-mid-autumn-festival-background-with-golden-glitter-moon-and-hand-drawn-moon-rabbits-vector-465011609.jpg
width: 85
large_thumb:
height: 150
url: https://thumb7.shutterstock.com/thumb_large/1384888/465011609/stock-vector-happy-mid-autumn-festival-background-with-golden-glitter-moon-and-hand-drawn-moon-rabbits-vector-465011609.jpg
width: 128
huge_thumb:
height: 260
url: https://image.shutterstock.com/image-vector/happy-mid-autumn-festival-background-260nw-465011609.jpg
width: 221
preview_1000:
url: https://ak.picdn.net/shutterstock/photos/465011609/watermark_1000/e80e64e55f14aeb951feaf93ea337dc0/preview_1000-465011609.jpg
width: 850
height: 1000
preview_1500:
url: https://image.shutterstock.com/z/stock-vector-happy-mid-autumn-festival-background-with-golden-glitter-moon-and-hand-drawn-moon-rabbits-vector-465011609.jpg
width: 1275
height: 1500
categories:
- id: '8'
name: Holidays
- id: '11'
name: The Arts
contributor:
id: '1384888'
description: Happy Mid Autumn Festival background with golden glitter Moon and hand drawn Moon Rabbits.
Vector illustration
image_type: vector
is_adult: false
is_editorial: false
is_illustration: true
has_model_release: false
has_property_release: true
keywords:
- abstract
- art
- artistic
- asian
- autumn
- background
- bunny
- calligraphy
- celebration
- china
media_type: image
url: https://www.shutterstock.com/image-photo/465011609
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
security:
- basic: []
- customer_accessCode: []
tags:
- images
operationId: getImage
summary: Get details about images
description: This endpoint shows information about an image, including a URL to a preview image and the sizes that it
is available in.
/v2/images/categories:
get:
parameters:
- description: Language for the keywords and categories in the response
in: query
name: language
example: es
schema:
$ref: '#/components/schemas/Language'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CategoryDataList'
examples:
response:
value:
data:
- id: '15'
name: Science
- id: '17'
name: Signs/Symbols
- id: '18'
name: Sports/Recreation
- id: '16'
name: Technology
- id: '0'
name: Transportation
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
security:
- basic: []
- customer_accessCode: []
tags:
- images
operationId: getImageCategories
summary: List image categories
description: This endpoint lists the categories (Shutterstock-assigned genres) that images can belong to.
/v2/images/{id}/similar:
get:
parameters:
- description: Image ID
in: path
name: id
required: true
example: '465011609'
schema:
type: string
- description: Language for the keywords and categories in the response
in: query
name: language
example: es
schema:
$ref: '#/components/schemas/Language'
- description: Page number
in: query
name: page
schema:
type: integer
minimum: 1
default: 1
- description: Number of results per page
in: query
name: per_page
schema:
type: integer
minimum: 1
maximum: 500
default: 20
- description: Amount of detail to render in the response
in: query
name: view
schema:
type: string
enum:
- minimal
- full
default: minimal
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ImageSearchResults'
examples:
response:
value:
page: 1
per_page: 1
total_count: 200
search_id: ''
data:
- id: '224429596'
aspect: 1
assets:
preview:
height: 450
url: https://image.shutterstock.com/display_pic_with_logo/302287/224429596/stock-vector-happy-halloween-vector-224429596.jpg
width: 450
small_thumb:
height: 100
url: https://thumb1.shutterstock.com/thumb_small/302287/224429596/stock-vector-happy-halloween-vector-224429596.jpg
width: 100
large_thumb:
height: 150
url: https://thumb1.shutterstock.com/thumb_large/302287/224429596/stock-vector-happy-halloween-vector-224429596.jpg
width: 150
huge_thumb:
height: 260
url: https://image.shutterstock.com/image-vector/happy-halloween-vector-260nw-224429596.jpg
width: 260
preview_1000:
url: https://ak.picdn.net/shutterstock/photos/224429596/watermark_1000/9b5c88b67f10298f7b5340f21dffc953/preview_1000-224429596.jpg
width: 1000
height: 1000
preview_1500:
url: https://image.shutterstock.com/z/stock-vector-happy-halloween-vector-224429596.jpg
width: 1500
height: 1500
contributor:
id: '302287'
description: Happy Halloween - vector
image_type: vector
media_type: image
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
security:
- basic: []
- customer_accessCode: []
tags:
- images
operationId: getSimilarImages
summary: List similar images
description: This endpoint returns images that are visually similar to an image that you specify.
/v2/images/licenses:
post:
parameters:
- description: Subscription ID to use to license the image
in: query
name: subscription_id
schema:
type: string
- description: Image format
in: query
name: format
schema:
type: string
enum:
- eps
- jpg
default: jpg
- description: Image size
in: query
name: size
schema:
type: string
enum:
- small
- medium
- huge
- vector
- custom
default: huge
- description: Search ID that was provided in the results of an image search
in: query
name: search_id
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LicenseImageResultDataList'
examples:
response:
value:
data:
- image_id: '547233985'
download:
url: https://download.shutterstock.com/gatekeeper/[random-characters]/shutterstock_547233985.jpg
allotment_charge: 1
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
security:
- customer_accessCode:
- licenses.create
- purchases.view
ldap_accessCode:
- user.view
x-code-samples:
- lang: shell
source: "DATA='{\n \"images\": [\n {\n \"image_id\": \"59656357\",\n \"price\": 12.50,\n \"metadata\"\
: {\n \"customer_id\": \"12345\"\n }\n }\n ]\n}'\n\ncurl -X POST \"https://api.shutterstock.com/v2/images/licenses?subscription_id=$SUBSCRIPTION_ID\"\
\ \\\n-H \"Authorization: Bearer $SHUTTERSTOCK_API_TOKEN\" \\\n-H 'Content-Type: application/json' \\\n-d \"$DATA\"\
\n"
- lang: javascript--nodejs
source: "const sstk = require(\"shutterstock-api\");\n\nsstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);\n\
\nconst imagesApi = new sstk.ImagesApi();\n\nconst body = {\n \"images\": [\n {\n \"image_id\": \"419235589\"\
,\n \"price\": 12.50,\n \"metadata\": {\n \"customer_id\": \"12345\"\n }\n }\n ]\n};\n\
\nconst queryParams = {\n \"format\": \"jpg\",\n \"size\": \"huge\",\n \"subscription_id\": process.env.SUBSCRIPTION_ID\n\
};\n\nimagesApi.licenseImages(body, queryParams)\n .then(({ data }) => {\n console.log(data);\n })\n .catch((error)\
\ => {\n console.error(error);\n });\n"
- lang: php
source: "$body = [\n \"images\" => [\n [\n \"image_id\" => \"539753938\",\n \"price\" => 12.50,\n \
\ \"metadata\" => [\n \"customer_id\" => \"12345\"\n ]\n ]\n ]\n];\n$encodedBody = json_encode($body);\n\
\n$options = [\n CURLOPT_URL => \"https://api.shutterstock.com/v2/images/licenses?subscription_id=$SUBSCRIPTION_ID\"\
,\n CURLOPT_CUSTOMREQUEST => \"POST\",\n CURLOPT_POSTFIELDS => $encodedBody,\n CURLOPT_USERAGENT => \"php/curl\"\
,\n CURLOPT_HTTPHEADER => [\n \"Authorization: Bearer $SHUTTERSTOCK_API_TOKEN\",\n \"Content-Type: application/json\"\
\n ],\n CURLOPT_RETURNTRANSFER => 1\n];\n\n$handle = curl_init();\ncurl_setopt_array($handle, $options);\n$response\
\ = curl_exec($handle);\ncurl_close($handle);\n\n$decodedResponse = json_decode($response);\nprint_r($decodedResponse);\n"
tags:
- images
operationId: licenseImages
summary: License images
description: This endpoint gets licenses for one or more images. You must specify the image IDs in the body parameter
and other details like the format, size, and subscription ID either in the query parameter or with each image ID in
the body parameter. Values in the body parameter override values in the query parameters.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LicenseImageRequest'
examples:
default:
value:
images:
- image_id: '59656357'
format: jpg
metadata:
customer_id: '12345'
geo_location: US
number_viewed: '15'
search_term: dog
- image_id: '75359656'
editorial_acknowledgement: true
format: jpg
metadata:
customer_id: '12345'
geo_location: US
number_viewed: '15'
search_term: dog
description: List of images to request licenses for
# --- truncated at 32 KB (383 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/shutterstock/refs/heads/main/openapi/shutterstock-openapi.yml