openapi: 3.0.0
info:
title: Shutterstock API Reference audio editorial_images API
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
servers:
- url: https://api.shutterstock.com
description: Shutterstock API
tags:
- name: editorial_images
paths:
/v2/editorial/images/search:
get:
parameters:
- description: One or more search terms separated by spaces
in: query
name: query
schema:
type: string
- description: Sort by
in: query
name: sort
schema:
type: string
enum:
- relevant
- newest
- oldest
default: relevant
- description: Show editorial content within a certain editorial category; specify by category name
in: query
name: category
schema:
type: string
- description: Show only editorial content that is available for distribution in a certain country
in: query
name: country
required: true
example: USA
schema:
type: string
format: country-code-3
- description: Show only editorial content from certain suppliers
in: query
name: supplier_code
schema:
type: array
items:
type: string
- description: Show only editorial content generated on or after a specific date
in: query
name: date_start
schema:
type: string
format: date
- description: Show only editorial content generated on or before a specific date
in: query
name: date_end
schema:
type: string
format: date
- description: Number of results per page
in: query
name: per_page
schema:
type: integer
minimum: 1
maximum: 50
default: 20
- description: The cursor of the page with which to start fetching results; this cursor is returned from previous requests
in: query
name: cursor
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EditorialSearchResults'
examples:
response:
value:
per_page: 1
total_count: 1556949
search_id: q8igACM5gqQY75owjLoVvw
next: eyJ2IjoxLCJzIjoxfQ==
prev: ''
data:
- id: 9804979n
title: Hong Kong kicks off international e-Sports competition, China - 24 Aug 2018
caption: ''
description: Members of the TyLoo e-Sports team from China prepare to face off against the Kinguin e-Sports team from Poland at the ICBC (Asia) e-Sports and Music Festival Hong Kong 2018, Hong Kong, China, 24 August 2018. The festival runs from 24 to 26 August with professional gamers from around the world competing in international e-sports tournaments.
byline: ALEX HOFFORD/EPA-EFE/Shutterstock
keywords: []
date_taken: '2018-08-24'
categories: []
aspect: 1.481
assets:
thumb_170:
height: 115
width: 170
url: https://editorial01.shutterstock.com/thumb/9804979n/c4377a53/Shutterstock_9804979n.jpg
thumb_220:
height: 149
width: 220
url: https://editorial01.shutterstock.com/thumb-220/9804979n/c57a68c7/Shutterstock_9804979n.jpg
watermark_450:
height: 304
width: 450
url: https://editorial01.shutterstock.com/wm-preview-450/9804979n/37d19dce/Shutterstock_9804979n.jpg
watermark_1500:
height: 1500
width: 1040
url: https://editorial01.shutterstock.com/wm-preview-1500/9933285a/ab82fea4/Shutterstock_9933285a.jpg
original:
display_name: Original
height: 3263
width: 4831
is_licensable: true
small_jpg:
display_name: Small
height: 337
width: 500
is_licensable: true
medium_jpg:
display_name: Med
height: 675
width: 1000
is_licensable: true
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'406':
description: Not Acceptable
security:
- basic: []
- customer_accessCode: []
tags:
- editorial_images
x-code-samples:
- lang: shell
source: 'curl -X GET https://api.shutterstock.com/v2/editorial/images/search \
-H "Accept: application/json" \
-G \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
--data-urlencode "query=football" \
--data-urlencode "country=USA" \
--data-urlencode "sort=newest" \
--data-urlencode "date_start=2018-10-23"
'
- lang: javascript--nodejs
source: "const sstk = require(\"shutterstock-api\");\n\nsstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);\n\nconst editorialApi = new sstk.EditorialApi();\n\nconst queryParams = {\n \"query\": \"football\",\n \"country\": \"USA\",\n \"sort\": \"newest\",\n \"date_start\": \"2018-10-23\"\n};\n\nconst country = \"USA\";\n\neditorialApi.editorialImagesSearch(country, queryParams)\n .then((data) => {\n console.log(data);\n })\n .catch((error) => {\n console.error(error);\n });\n"
- lang: php
source: "$queryFields = [\n \"query\" => \"football\",\n \"country\" => \"USA\",\n \"date_start\" => \"2018-10-23\",\n \"sort\" => \"newest\"\n];\n\n$options = [\n CURLOPT_URL => \"https://api.shutterstock.com/v2/editorial/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: searchEditorialImages
summary: Search editorial images
description: This endpoint searches for editorial 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.
/v2/editorial/images/categories:
get:
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EditorialImageCategoryResults'
examples:
response:
value:
data:
- name: Animal
- name: Awards
- name: Art
- name: Film Stills
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
security:
- basic: []
- customer_accessCode: []
tags:
- editorial_images
operationId: getEditorialImageCategories
summary: List editorial categories
description: This endpoint lists the categories that editorial images can belong to, which are separate from the categories that other types of assets can belong to.
/v2/editorial/images/{id}:
get:
parameters:
- description: Editorial ID
in: path
name: id
required: true
example: 9926131a
schema:
type: string
- description: Returns only if the content is available for distribution in a certain country
in: query
name: country
required: true
example: USA
schema:
type: string
format: country-code-3
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EditorialContent'
examples:
response:
value:
id: 9767412v
title: Tokyo 2020 Olympics mascot Miraitowa and Paralympics mascot Someity debut, Japan - 22 Jul 2018
caption: ''
description: Tokyo 2020 Olympics mascot Miraitowa greets with former Japanese prime minister Yoshiko Mori, President of Tokyo 2020 Olympics Committee, as mascots of Tokyo 2020 Olympics and Paralympics debut in Tokyo, Japan, 22 July 2018. Tokyo 2020 Olympics will start on 24 July 2020 and run until 09 August 2020.
byline: KIMIMASA MAYAMA/EPA-EFE/Shutterstock
keywords: []
date_taken: '2018-07-22'
categories: []
aspect: 1.33
assets:
thumb_170:
height: 128
width: 170
url: https://editorial01.shutterstock.com/thumb/9767412v/36aeb953/Shutterstock_9767412v.jpg
thumb_220:
height: 165
width: 220
url: https://editorial01.shutterstock.com/thumb-220/9767412v/b786b189/Shutterstock_9767412v.jpg
watermark_450:
height: 338
width: 450
url: https://editorial01.shutterstock.com/wm-preview-450/9767412v/f75b6680/Shutterstock_9767412v.jpg
watermark_1500:
height: 1500
width: 1040
url: https://editorial01.shutterstock.com/wm-preview-1500/9933285a/ab82fea4/Shutterstock_9933285a.jpg
original:
display_name: Original
height: 3447
width: 4586
is_licensable: true
small_jpg:
display_name: Small
height: 375
width: 500
is_licensable: true
medium_jpg:
display_name: Med
height: 751
width: 1000
is_licensable: true
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
security:
- basic: []
- customer_accessCode: []
tags:
- editorial_images
operationId: getEditorialImageDetails
summary: Get editorial content details
description: This endpoint shows information about an editorial image, including a URL to a preview image and the sizes that it is available in.
/v2/editorial/images/licenses:
get:
parameters:
- description: Show licenses for the specified editorial image ID
in: query
name: image_id
schema:
type: string
- description: Show editorial images that are available with the specified license name
in: query
name: license
schema:
type: string
- 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: 200
default: 20
- description: Sort order
in: query
name: sort
schema:
type: string
enum:
- newest
- oldest
default: newest
- description: Filter licenses by username of licensee
in: query
name: username
schema:
type: string
- name: start_date
in: query
description: Show licenses created on or after the specified date
schema:
type: string
format: date-time
example: 2020-02-02T13:00-05:00
- name: end_date
in: query
description: Show licenses created before the specified date
schema:
type: string
format: date-time
example: 2020-02-02T13:00-05:00
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DownloadHistoryDataList'
examples:
response:
value:
data:
- id: e1dbb15d5384725d292cf64f793ac45062
user:
username: username1
license: premier_editorial_all_digital
download_time: '2020-12-18T02:22:56.000Z'
is_downloadable: false
image:
id: 11231389im
format:
size: original
subscription_id: 1221a491741j1k41yd91dh37al324
metadata:
client: Company A
other: Important media
purchase_order: '457234'
job: Important project
- id: e1dbb15d5384725d292cf64f793ac45114
user:
username: username2
license: premier_editorial_all_digital
download_time: '2020-12-11T01:24:22.000Z'
is_downloadable: false
image:
id: 11231442aa
format:
size: original
subscription_id: 1221a491741j1k41yd91dh37al324
metadata:
client: Company B
other: Important image
purchase_order: '5583831'
job: Important project
page: 1
per_page: 2
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
security:
- customer_accessCode:
- licenses.view
tags:
- editorial_images
operationId: getEditorialImageLicenseList
summary: List editorial image licenses
description: This endpoint lists existing editorial image licenses.
post:
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LicenseEditorialContentResults'
examples:
response:
value:
data:
- editorial_id: '69656358'
download:
url: https://s3-eu-west-1.amazonaws.com/api-downloads.rexfeatures.com/[random-characters].jpg?Expires=1524717323
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'406':
description: Not Acceptable
security:
- customer_accessCode:
- licenses.create
- purchases.view
x-code-samples:
- lang: shell
source: "DATA='{\n \"editorial\": [\n {\n \"editorial_id\": \"8594090h\",\n \"license\": \"premier_editorial_comp\"\n }\n ],\n \"country\": \"USA\"\n}'\n\ncurl -X POST https://api.shutterstock.com/v2/editorial/images/licenses \\\n-d \"$DATA\" \\\n-H \"Content-Type: application/json\" \\\n-H \"Accept: application/json\" \\\n-H \"Authorization: Bearer $SHUTTERSTOCK_API_TOKEN\"\n"
- lang: javascript--nodejs
source: "const sstk = require(\"shutterstock-api\");\n\nsstk.setAccessToken(process.env.SHUTTERSTOCK_API_TOKEN);\n\nconst editorialApi = new sstk.EditorialApi();\n\nconst body = {\n \"editorial\": [\n {\n \"editorial_id\": \"8594090h\",\n \"license\": \"premier_editorial_comp\"\n }\n ],\n \"country\": \"USA\"\n};\n\neditorialApi.licenseEditorialImage(body)\n .then(({ data }) => {\n console.log(data);\n })\n .catch((error) => {\n console.error(error);\n });\n"
- lang: php
source: "$body = [\n \"editorial\" => [\n [\n \"editorial_id\" => \"8594090h\",\n \"license\" => \"premier_editorial_comp\"\n ]\n ],\n \"country\" => \"USA\"\n];\n$encodedBody = json_encode($body);\n\n$options = [\n CURLOPT_URL => \"https://api.shutterstock.com/v2/editorial/images/licenses\",\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:
- editorial_images
operationId: licenseEditorialImages
summary: License editorial content
description: This endpoint gets licenses for one or more editorial images. You must specify the country and one or more editorial images to license.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LicenseEditorialContentRequest'
examples:
default:
value:
editorial:
- editorial_id: 8594090h
license: premier_editorial_comp
country: USA
description: License editorial content
required: true
/v2/editorial/images/livefeeds:
get:
parameters:
- description: Returns only livefeeds that are available for distribution in a certain country
in: query
name: country
required: true
example: USA
schema:
type: string
format: country-code-3
- 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: 50
default: 20
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EditorialImageLivefeedList'
examples:
response:
value:
page: 1
per_page: 1
total_count: 6011
data:
- id: 2018%2F10%2F19%2F'Butterfly'%20photocall%2C%20Rome%20Film%20Festival
name: '''Butterfly'' photocall, Rome Film Festival'
total_item_count: 24
created_time: '2018-10-19T20:27:26+00:00'
cover_item:
height: 170
width: 113
url: https://editorial01.shutterstock.com/thumb/9938080a/532b2be1/Shutterstock_9938080a.jpg
id: 9938080a
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
security:
- basic: []
- customer_accessCode: []
tags:
- editorial_images
operationId: getEditorialLivefeedImagesList
summary: Get editorial livefeed list
/v2/editorial/images/livefeeds/{id}:
get:
parameters:
- description: Editorial livefeed ID; must be an URI encoded string
in: path
name: id
required: true
example: 2018%2F10%2F15%2FWomen%20of%20the%20Year%20Lunch%20%26%20Awards%2C%20London
schema:
type: string
- description: Returns only if the livefeed is available for distribution in a certain country
in: query
name: country
required: true
example: USA
schema:
type: string
format: country-code-3
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EditorialImageLivefeed'
examples:
response:
value:
id: 2018%2F10%2F19%2F'The%20House%20with%20a%20Clock%20in%20Its%20Walls'%20premiere%2C%20Rome%20Film%20Festival
name: '''The House with a Clock in Its Walls'' premiere, Rome Film Festival'
total_item_count: 100
cover_item:
height: 170
width: 114
url: https://editorial01.shutterstock.com/thumb/9938511p/7d1f17d9/Shutterstock_9938511p.jpg
id: 9938511p
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
security:
- basic: []
- customer_accessCode: []
tags:
- editorial_images
operationId: getEditorialImageLivefeed
summary: Get editorial livefeed
/v2/editorial/images/livefeeds/{id}/items:
get:
parameters:
- description: Editorial livefeed ID; must be an URI encoded string
in: path
name: id
required: true
example: 2018%2F10%2F15%2FWomen%20of%20the%20Year%20Lunch%20%26%20Awards%2C%20London
schema:
type: string
- description: Returns only if the livefeed items are available for distribution in a certain country
in: query
name: country
required: true
example: USA
schema:
type: string
format: country-code-3
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EditorialImageContentDataList'
examples:
response:
value:
data:
- id: 9938573m
title: '''The House with a Clock in Its Walls'' premiere, Rome Film Festival, Italy - 19 Oct 2018'
caption: ''
description: Christian Marazziti and Ariadna Romero
byline: Maurizio D'Avanzo/IPA/Shutterstock
keywords: []
date_taken: '2018-10-19'
categories:
- name: Actor
- name: Female
- name: Personality
aspect: 0.666
assets:
thumb_170:
height: 170
width: 113
url: https://editorial01.shutterstock.com/thumb/9938573m/4d5708ce/Shutterstock_9938573m.jpg
thumb_220:
height: 220
width: 146
url: https://editorial01.shutterstock.com/thumb-220/9938573m/b78aabde/Shutterstock_9938573m.jpg
watermark_450:
height: 450
width: 300
url: https://editorial01.shutterstock.com/wm-preview-450/9938573m/4a9a4add/Shutterstock_9938573m.jpg
watermark_1500:
height: 1500
width: 1040
url: https://editorial01.shutterstock.com/wm-preview-1500/9933285a/ab82fea4/Shutterstock_9933285a.jpg
original:
display_name: Original
height: 4928
width: 3280
is_licensable: true
small_jpg:
display_name: Small
height: 500
width: 332
is_licensable: true
medium_jpg:
display_name: Med
height: 1000
width: 660
is_licensable: true
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
security:
- basic: []
- customer_accessCode: []
tags:
- editorial_images
operationId: getEditorialLivefeedImageItems
summary: Get editorial livefeed items
/v2/editorial/{id}:
get:
parameters:
- description: Editorial ID
in: path
name: id
required: true
example: 9926131a
schema:
type: string
- description: Returns only if the content is available for distribution in a certain country
in: query
name: country
required: true
example: USA
schema:
type: string
format: country-code-3
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EditorialContent'
examples:
response:
value:
id: 9767412v
title: Tokyo 2020 Olympics mascot Miraitowa and Paralympics mascot Someity debut, Japan - 22 Jul 2018
caption: ''
description: Tokyo 2020 Olympics mascot Miraitowa greets with former Japanese prime minister Yoshiko Mori, President of Tokyo 2020 Olympics Committee, as mascots of Tokyo 2020 Olympics and Paralympics debut in Tokyo, Japan, 22 July 2018. Tokyo 2020 Olympics will start on 24 July 2020 and run until 09 August 2020.
byline: KIMIMASA MAYAMA/EPA-EFE/Shutterstock
keywords: []
date_taken: '2018-07-22'
categories: []
aspect: 1.33
assets:
thumb_170:
height: 128
width: 170
url: https://editorial01.shutterstock.com/thumb/9767412v/36aeb953/Shutterstock_9767412v.jpg
thumb_220:
height: 165
width: 220
url: https://editorial01.shutterstock.com/thumb-220/9767412v/b786b189/Shutterstock_9767412v.jpg
watermark_450:
height: 338
width: 450
url: https://editorial01.shutterstock.com/wm-preview-450/9767412v/f75b6680/Shutterstock_9767412v.jpg
watermark_1500:
height: 1500
width: 1040
url: https://editorial01.shutterstock.com/wm-preview-1500/9933285a/ab82fea4/Shutterstock_9933285a.jpg
original:
display_name: Original
height: 3447
width: 4586
is_licensable: true
small_jpg:
display_name: Small
height: 375
width: 500
is_licensable: true
medium_jpg:
display_name: Med
height: 751
width: 1000
is_licensable: true
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
security:
- basic: []
- customer_accessCode: []
tags:
- editorial_images
operationId: getEditorialImage
summary: (Deprecated) Get editorial content details
description: Deprecated; use `GET /v2/editorial/images/{id}` instead to show information about an editorial image, including a URL to a preview image and the sizes that it is available in.
deprecated: true
/v2/editorial/licenses:
post:
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LicenseEditorialContentResults'
examples:
response:
value:
data:
- editorial_id: '69656358'
download:
url: https://s3-eu-west-1.amazonaws.com/api-downloads.rexfeatures.com/[random-characters].jpg?Expires=1524717323
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'406':
description: Not Acceptable
security:
- customer_accessCode:
- licenses.create
x-code-samples:
- lang: shell
source: "DATA='{\n \"editorial\": [\n {\n \"editorial_id\": \"8594090h\",\n \"license\": \"premier_editorial_comp\"\n }\n ],\n \"country\": \"USA\"\n}'\n\ncurl -X POST https://api.shutterstock.com/v2/editorial/licenses \\\n-d \"$DATA\" \\\n-H \"Content-Type: application/json\" \\\n-H \"Accept: application/json\" \\\n-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 editorialApi = new sstk.EditorialApi();\n\nconst body = {\n \"editorial\": [\n {\n \"editorial_id\": \"8594090h\",\n \"license\": \"premier_editorial_comp\"\n }\n ],\n \"country\": \"USA\"\n};\n\neditorialApi.licenseEditorialImage(body)\n .then(({ data }) => {\n console.log(data);\n })\n .catch((error) => {\n console.error(error);\n });\n"
- lang: php
source: "$body = [\n \"editorial\" => [\n [\n \"editorial_id\" => \"8594090h\",\n \"license\" => \"premier_editorial_comp\"\n ]\n ],\n \"country\" => \"USA\"\n];\n$encodedBody = json_encode($body);\n\n$options = [\n CURLOPT_URL => \"https://api.shutterstock.com/v2/editorial/licenses\",\n CURLOPT_CUSTOMREQUEST => \"POST\",\n CURLOPT_POSTFIELDS => $encodedBody,\n CURLOPT_USERAGENT => \"php/curl\",\n CURLOPT_HTTPHEADER => [\n \"Authorization: Bearer $SHUTTERSTOCK_API_TOKEN\",\n \"Content-T
# --- truncated at 32 KB (74 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/shutterstock/refs/heads/main/openapi/shutterstock-editorial-images-api-openapi.yml