openapi: 3.0.0
info:
title: Shutterstock API Reference audio editorial_video 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_video
paths:
/v2/editorial/videos/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 video content within a certain editorial category; specify by category name
in: query
name: category
schema:
type: string
- description: Show only editorial video 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 video content from certain suppliers
in: query
name: supplier_code
schema:
type: array
items:
type: string
- description: Show only editorial video content generated on or after a specific date
in: query
name: date_start
schema:
type: string
format: date
- description: Show only editorial video content generated on or before a specific date
in: query
name: date_end
schema:
type: string
format: date
- description: Show only editorial video content with specific resolution
in: query
name: resolution
schema:
type: string
enum:
- 4k
- high_definition
- standard_definition
- description: Show only editorial video content generated with specific frames per second
in: query
name: fps
schema:
type: number
- 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/EditorialVideoSearchResults'
examples:
response:
value:
per_page: 1
total_count: 1556949
search_id: q8igACM5gqQY75owjLoVvw
next: eyJ2IjoxLCJzIjoxfQ==
prev: ''
data:
- id: 10679336a
title: Proud Papa Playing with His Puppies, New Oxford, Pennsylvania, USA - 28 Oct 2020
caption: ''
description: 'Info from Licensor: "In June, we rescued this 2 year old male boxer from spending most of his days in a crate. Our 2 adult female boxers helped him adjust to living a good boxer life with our family. He "thanked" us with this surprise litter of 8 puppies! He has really done amazingly well with playing with all the puppies, and I think he will miss them when they go to their "fur-ever" homes. It was a perfect day of playing in the backyard at the end of October 2020."'
byline: ViralHog/Shutterstock
keywords:
- adorable
- cute
- doggo
- doggy
- dogs
- domesticated animals
- entertainment
- feel good
- grass
- new oxford
- pennsylvania
- pets
- played
- playing
- plays
- pup
- puppies
- puppy
- sweet
- usa
- viralhog
- virals
- yard
date_taken: '2020-10-28'
categories: []
aspect: 1.778
assets:
preview_mp4:
url: https://qa.editorial-cdn.shuttercorp.net/wm-preview-mp4/10679336a/M8TbAb3aNaj2g5w4ODgwMzg=/Shutterstock_10679336a.mp4
preview_webm:
url: https://qa.editorial-cdn.shuttercorp.net/wm-preview-webm/10679336a/M5T3Ab36N4jbgcwbODgwMzg=/Shutterstock_10679336a.webm
thumb_jpg:
url: https://qa.editorial-cdn.shuttercorp.net/thumb-1/10679336a/M5T6Ad37Ncj5g3w1ODgwMzg=/Shutterstock_10679336a.jpg
original:
height: 1080
width: 1920
fps: 29.937
format: avc1
file_size: 124452018
display_name: HD
is_licensable: true
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'406':
description: Not Acceptable
security:
- basic: []
- customer_accessCode: []
tags:
- editorial_video
x-code-samples:
- lang: shell
source: 'curl -X GET https://api.shutterstock.com/v2/editorial/videos/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.EditorialVideoApi();\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.editorialVideosSearch(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/videos/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: editorialVideosSearch
summary: Search editorial video content
description: This endpoint searches for editorial videos. 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/videos/categories:
get:
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EditorialVideoCategoryResults'
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_video
operationId: getEditorialCategories
summary: List editorial video categories
description: This endpoint lists the categories that editorial videos can belong to, which are separate from the categories that other types of assets can belong to.
/v2/editorial/videos/{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/EditorialVideoContent'
examples:
response:
value:
id: 10679336a
title: Proud Papa Playing with His Puppies, New Oxford, Pennsylvania, USA - 28 Oct 2020
caption: ''
description: 'Info from Licensor: "In June, we rescued this 2 year old male boxer from spending most of his days in a crate. Our 2 adult female boxers helped him adjust to living a good boxer life with our family. He "thanked" us with this surprise litter of 8 puppies! He has really done amazingly well with playing with all the puppies, and I think he will miss them when they go to their "fur-ever" homes. It was a perfect day of playing in the backyard at the end of October 2020."'
byline: ViralHog/Shutterstock
keywords:
- adorable
- cute
- doggo
- doggy
- dogs
- domesticated animals
- entertainment
- feel good
- grass
- new oxford
- pennsylvania
- pets
- played
- playing
- plays
- pup
- puppies
- puppy
- sweet
- usa
- viralhog
- virals
- yard
date_taken: '2020-10-28'
categories: []
aspect: 1.778
assets:
preview_mp4:
url: https://qa.editorial-cdn.shuttercorp.net/wm-preview-mp4/10679336a/M8TbAb3aNaj2g5w4ODgwMzg=/Shutterstock_10679336a.mp4
preview_webm:
url: https://qa.editorial-cdn.shuttercorp.net/wm-preview-webm/10679336a/M5T3Ab36N4jbgcwbODgwMzg=/Shutterstock_10679336a.webm
thumb_jpg:
url: https://qa.editorial-cdn.shuttercorp.net/thumb-1/10679336a/M5T6Ad37Ncj5g3w1ODgwMzg=/Shutterstock_10679336a.jpg
original:
height: 1080
width: 1920
fps: 29.937
format: avc1
file_size: 124452018
display_name: HD
is_licensable: true
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'406':
description: Not Acceptable
security:
- basic: []
- customer_accessCode: []
tags:
- editorial_video
operationId: editorialVideosDetails
summary: Get editorial video 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/videos/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].mov?Expires=1524717323
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
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_video_comp\"\n }\n ],\n \"country\": \"USA\"\n}'\n\ncurl -X POST https://api.shutterstock.com/v2/editorial/videos/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\": \"10687492a\",\n \"license\": \"premier_editorial_video_comp\"\n }\n ],\n \"country\": \"USA\"\n};\n\neditorialApi.licenseEditorialVideo(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\" => \"10687492a\",\n \"license\" => \"premier_editorial_video_comp\"\n ]\n ],\n \"country\" => \"USA\"\n];\n$encodedBody = json_encode($body);\n\n$options = [\n CURLOPT_URL => \"https://api.shutterstock.com/v2/editorial/videos/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);"
tags:
- editorial_video
operationId: licenseEditorialVideo
summary: License editorial video content
description: This endpoint gets licenses for one or more editorial videos. You must specify the country and one or more editorial videos to license.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LicenseEditorialVideoContentRequest'
examples:
default:
value:
editorial:
- editorial_id: 8594090h
license: premier_editorial_video_comp
country: USA
description: License editorial video content
required: true
components:
schemas:
LicenseEditorialVideoContent:
description: Individual editorial video content to license
properties:
editorial_id:
description: Editorial ID
type: string
license:
description: License agreement to use for licensing
type: string
enum:
- premier_editorial_video_digital_only
- premier_editorial_video_all_media
- premier_editorial_video_all_media_single_territory
- premier_editorial_video_comp
metadata:
$ref: '#/components/schemas/LicenseRequestMetadata'
size:
description: Asset size to download
default: original
enum:
- original
type: string
required:
- editorial_id
- license
type: object
EditorialCategory:
description: Name of an editorial category
properties:
name:
type: string
type: object
Url:
description: URL object
properties:
url:
description: URL that can be used to download the unwatermarked, licensed asset
type: string
required:
- url
type: object
LicenseRequestMetadata:
description: Additional information for license requests for enterprise accounts and API subscriptions, 4 fields maximum; which fields are required is set by the account holder
example:
customer_id: '12345'
geo_location: US
number_viewed: '15'
search_term: dog
maxProperties: 4
properties: {}
type: object
EditorialVideoContent:
description: Metadata about editorial content
properties:
aspect:
type: number
assets:
$ref: '#/components/schemas/EditorialVideoAssets'
byline:
type: string
caption:
type: string
categories:
description: List of categories
items:
$ref: '#/components/schemas/EditorialCategory'
type: array
date_taken:
format: date
type: string
description:
type: string
id:
type: string
keywords:
items:
type: string
type: array
title:
type: string
required:
- id
type: object
LicenseEditorialContentResult:
description: The response to a licensing request for editorial content
properties:
allotment_charge:
description: For pre-paid plans, how many credits were used for the item license
type: integer
download:
$ref: '#/components/schemas/Url'
description: Information that is needed to download the image
editorial_id:
description: Editorial ID
type: string
error:
type: string
required:
- editorial_id
type: object
LicenseEditorialVideoContentRequest:
description: License editorial video content request
properties:
country:
description: Mandatory country code for where the editorial content will be distributed; this value is used for rights checks
anyOf:
- type: string
format: country-code-3
- type: string
format: country-code-2
example: USA
editorial:
description: Editorial content to license
items:
$ref: '#/components/schemas/LicenseEditorialVideoContent'
type: array
required:
- country
- editorial
type: object
VideoSizeDetails:
description: Video asset information
properties:
display_name:
description: Display name of this video size
type: string
file_size:
description: File size (in bytes) of this video size
type: integer
format:
description: Format of this video size
type: string
fps:
description: Frames per second of this video size
type: number
height:
description: Height of this video size
type: integer
is_licensable:
description: Whether or not videos can be licensed in this video size
type: boolean
width:
description: Width of this video size
type: integer
type: object
EditorialVideoAssets:
description: Asset information, including size and thumbnail URLs
properties:
original:
$ref: '#/components/schemas/VideoSizeDetails'
preview_mp4:
$ref: '#/components/schemas/VideoPreviewUrl'
preview_webm:
$ref: '#/components/schemas/VideoPreviewUrl'
thumb_jpg:
$ref: '#/components/schemas/VideoPreviewUrl'
type: object
Error:
description: Error object
properties:
code:
description: The error code of this error
type: string
data:
description: Debugging information about the error
type: string
items:
description: A list of items that produced the error
items:
type: object
type: array
message:
description: Specific details about this error
type: string
path:
description: Internal code reference to the source of the error
type: string
required:
- message
type: object
EditorialVideoCategoryResults:
description: List of editorial video categories
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/EditorialCategory'
LicenseEditorialContentResults:
description: List of editorial license results
properties:
data:
description: License results
items:
$ref: '#/components/schemas/LicenseEditorialContentResult'
type: array
errors:
description: Error list; appears only if there was an error
items:
$ref: '#/components/schemas/Error'
type: array
message:
description: Optional error message
type: string
page:
description: Current page of the response
type: integer
per_page:
description: Number of results per page
type: integer
total_count:
description: Total count of all results
type: integer
VideoPreviewUrl:
description: Video preview information
properties:
url:
description: Direct URL to the image
type: string
required:
- url
type: object
EditorialVideoSearchResults:
description: Editorial search results
properties:
data:
description: Editorial items
items:
$ref: '#/components/schemas/EditorialVideoContent'
type: array
message:
description: Optional error message
type: string
next:
description: Cursor value that represents the next page of results
type: string
page:
description: Current page of the response
type: integer
per_page:
description: Number of results per page
type: integer
prev:
description: Cursor value that represents the previous page of results
type: string
search_id:
description: Unique identifier for the search request
type: string
total_count:
description: Total count of all results
type: integer
required:
- data
- total_count
type: object
securitySchemes:
basic:
type: http
scheme: basic
customer_accessCode:
type: oauth2
x-shutterstock-realm: customer
flows:
authorizationCode:
authorizationUrl: https://accounts.shutterstock.com/oauth/authorize
tokenUrl: https://api.shutterstock.com/v2/oauth/access_token
scopes:
licenses.create: Grant the ability to download and license media on behalf of the user.
purchases.view: Grant read-only access to a user's purchase history.
licenses.view: Grant read-only access to a user's licenses.
collections.edit: Grant the ability to create new collections, edit a collection, and modify the contents of a collection
collections.view: Grant read-only access to a collection and its contents.