Search API reference
You can query Adobe Stock for assets that meet your specified search criteria. You can filter the results, specify the sort order in which the results are returned, and choose how many assets to return for each page of results.
Search requests
A request using the Stock Search API retrieves a list of assets from Adobe Stock that matches a set of search and filter values. A maximum of 100 assets can be returned from one request. This is a paginated interface that you can call multiple times to retrieve the full list.
For a guide to usage and additional examples, see Creating Adobe Stock applications.
Endpoint | Methods |
---|---|
GET, POST (only when using the similar_image parameter) |
About search and filter criteria
Search commands have three formats:
Search parameters. In general, search parameters identify asset information for values that cannot be predetermined, such as ID numbers or keywords. Parameters for searches look like this:
search_parameters[*search_item*]=*value*
For example:
search_parameters[words]=dog big happy
Search parameters are treated as AND. For example, you could combine
[words]
and[creator_id]
to search for assets created by a specific creator that have the specified keywords.search_parameters[words]=dog big happy&search_parameters[creator_id]=12345
Tip: You must specify at least one
search_parameters
value for each Search.Filtering values. These optional qualifiers specify which of the found assets to return. In general, filters identify asset information that has a known set of values, such as true/false or file type. Parameters for filtering look like this:
search_parameters[filters][{FILTER NAME}]={VALUE}
For example:
search_parameters[filters][orientation]=horizontal
You can specify multiple filtering values for content_type, template_type_id, and template_category_id; search returns assets that match any of those values. The remaining filters are treated as AND.
Response control. In addition to the filter and search mechanisms above, search queries by default return a fixed number of fields. To increase or decrease the scope of the response data, add one or more
result_columns[]
to the query. For example, using?result_columns[]=id
by itself will return only content IDs.
Copied to your clipboard{"id": 108289885},{"id": 173919253},
Chain together multiple result_columns[]
commands to get exactly the results you want.
Copied to your clipboardresult_columns[]=id&result_columns[]=title&result_columns[]=thumbnail_url
Copied to your clipboard{"id": 108289885,"title": "Vector illustration of colorful horse, unicorn, or pony.","thumbnail_url": "https://as1.ftcdn.net/jpg/01/08/28/98/500_F_108289885_zxdW0u0ds2oI69ZiLaON3kfhM2OLxdin.jpg"},{"id": 173919253,"title": "Isolated cute watercolor unicorn clipart. Nursery unicorns illustration. Princess rainbow unicorns poster. Trendy pink cartoon horse.","thumbnail_url": "https://as1.ftcdn.net/jpg/01/73/91/92/500_F_173919253_ivNTXG10bJKxSPRkxiAeaZZOjaWr5SBe.jpg"},
See Responses, below.
Authentication
An Authorization
header is not required. If you do not pass a valid bearer token in the Authorization header, you can search within Adobe Stock and access preview versions of assets, but the API will not return licensing requirements or give you the licensed status for the assets. Requests made in this way are essentially anonymous, with no notion of the user making the request.
If you do pass a valid token, then the Adobe Stock service returns the license state and licensed URL for each asset. See API authentication.
Request headers
See API authentication and Headers for Stock API calls for details about header content.
- Required headers:
x-Product
,x-api-key
- Optional headers:
Authorization
(required to view license state),X-Request-Id
URL parameters
Pass the following URL parameters with the GET request.
Tip: The only required parameter is at least one search_parameters[].
Parameter | Description |
---|---|
locale | Location language code. String. Default is en_US. This command is crucial for relevant localized search results. See Locale codes reference. |
search_parameters[words] | Keyword search. Space-separated list of keywords. String. Words can also be individual media identifiers (media_id), for example: search_parameters[words]=71182279 |
search_parameters[limit] | Maximum number of assets to return in the call. Valid values are 1 through 100. Default is 32. String. Call repeatedly with different [offset] values to page through the found assets. Tip:The number of images returned in each call can vary, but never exceeds 100 entries. See the note below for search_parameters[filters][premium] and refer to the FAQ question, Why are there more search results returned than the 'limit' value? |
search_parameters[offset] | Start position in query. Valid values are 0 (the first found asset) or higher integers. With each successive call for your search, increment this by the [limit] value to get the next page of assets. For example, by default your first call uses a 0 offset and limit of 32 to return the first 32 found assets. Call this API again with an offset of 32 to retrieve the next page. Integer. Default is 0. |
search_parameters[order] | Sort order in which to return found assets. Default is "relevance". String. Valid strings and their meanings:
|
search_parameters[creator_id] | Search by a specific asset creator's ID. Integer. |
search_parameters[media_id] | Search for one specific asset by its unique identifier (media_id). Integer. |
search_parameters[model_id] | Search for all assets that contain the same model as shown in this media ID. Integer. |
search_parameters[serie_id] | Search for all assets grouped in the same series as this media ID. Integer. |
search_parameters[similar] | Search for assets that are similar in appearance to an asset with a specific media ID. Integer. For example: search_parameters[similar]=99338 |
search_parameters[similar_url] | Search for assets that are similar in appearance to an image at a specific URL. String. For example: search_parameters[similar_url]=https://my.site/cutedog.jpg |
search_parameters[similar_image] | Whether to use similar_image data for visual similarity search. Integer. 0 | 1 (if using image data). |
similar_image | Image data to use when searching for visually similar assets. Must also specify: search_parameters[similar_image]=1 Supported in POST only. Valid image data is for JPG, PNG, or GIF files. Use multipart/form-data. Ignored if search_parameters[similar_url] is specified. |
search_parameters[category] | Search for assets with a specific category ID. Integer. For example, to search for assets in the category "travel": search_parameters[category]=1043 For more information see the CategoryTree API reference. |
search_parameters[thumbnail_size] | Thumbnail size in pixels. Specify the size of thumbnail to return for each found asset. Integer. Valid values and meanings:
|
search_parameters[filters][area_m_pixels] | Image sizes in megapixels (millions of pixels) to return, specified as a range in the format min-max .min and max are both optional and default to open ranges. Values must be (whole) integers.Examples: Search for an image that has a minimum area size of 4000x5000 pixels (20Mpix). |
search_parameters[filters][image_width] | Asset width specified as a range of pixels in the format min-max .min andmax are both optional and default to open ranges.Example: |
search_parameters[filters][image_height] | Asset height specified as a range of pixels in the format min-max . min andmax are both optional and default to open ranges.Examples: Only include images with a max height of 3000 pixels |
search_parameters[filters][premium] | Whether to return Premium assets or not. Possible values:
Strongly recommend always setting this parameter to one of its three values, as it works around an issue where more assets can be returned than set in the |
search_parameters[filters][3d_type_id][] | A multiple-value array specifying which 3D types to return. Valid values and meanings:
|
search_parameters[filters][template_type_id][] | Return found templates (starter files) for PSD or AI only if they are of the specified type. A multiple-value array specifying which template types to return. Valid values and meanings:
search_parameters[filters][template_type_id][]=2 &search_parameters[filters][template_type_id][]=3 |
search_parameters[filters][has_releases] | Return found assets only if the asset has model or property releases. String. Valid values and meanings:
|
search_parameters[filters][content_type:photo] | Include found assets that are photos. Integer. 0 | 1 |
search_parameters[filters][content_type:illustration] | Include found assets that are illustrations. Integer. 0 | 1 |
search_parameters[filters][content_type:vector] | Include found assets that are vectors. Integer. 0 | 1 |
search_parameters[filters][content_type:video] | Include found assets that are videos. Integer. 0 | 1 |
search_parameters[filters][content_type:template] | Include found assets that are templates. Integer. 0 | 1 |
search_parameters[filters][content_type:3d] | Include found assets that are 3D items. Integer. 0 | 1 |
search_parameters[filters][offensive:2] | Return found assets only if they are flagged as including Explicit/Nudity/Violence. Integer.
|
search_parameters[filters][isolated:on] | Return found assets only if the subject is isolated from the background by being on a uniformly colored background. Integer.
|
search_parameters[filters][panoramic:on] | Return found assets only if they are panoramic (can be combined with [orientation]). Integer.
|
search_parameters[filters][orientation] | Return found assets of the specified orientation. String. Valid values and meanings:
|
search_parameters[filters][video_duration] | Return found videos whose duration is no longer than the specified duration in seconds. String. Valid values and meanings:
|
search_parameters[filters][colors] | Comma-separated list of hexadecimal colors (without any # prefix). Return only found assets that contain the specified colors. String. Example: search_parameters[filters][colors]=ff0000,00ff00,0000ff |
search_parameters[gallery_id] | Returns members of the specified Fotolia gallery, which must be public. Note this requires access to a Fotolia website user account. String. |
search_parameters[filters][copy_space] | Image copy space. Value all returns all the images (equivalent to not having the filter in the query); value 1 filters for images that have copy space. String.all | 1 |
search_parameters[filters][is_loop] | Filter to return loop assets; applicable only to audio & video assets. Value 'all' returns all the audio/video assets; Value '1' or 'true' filters for audio/video asset that is a loop. Note: 'false' or '0' is not a valid option
|
search_parameters[filters][transparent] | Filter PNG assets by transparency. When set, only PNG images with a transparent background are included. Value 'all' returns all the images (equivalent to not having the filter in the query); Value `1` or `true` filters for images that have transparency.
|
search_parameters[filters][gentech] | Filter AI generated (gentech) and non-gentech assets. true would return all gentech assets, false would return all non-gentech assets, all would return both gentech and non-gentech assets (equivalent of not having the filter).
|
search_parameters[filters][icon_option][] | Use to filter/exclude is_icon_sheet and is_single_icon content. The supported values are:
result_columns[]=icon_option&search_parameters[filters][icon_option][]=icon_sheet&search_parameters[filters][icon_option][]=-single_icon |
result_columns[] | Specific fields you wish to include in the search result, excluding all other fields. Array[]. For a detailed description of each field, see Responses, below. Tip: To combine result columns, use this syntax: Note 1: Fields marked with * are returned by default, but if the
|
Responses
The Adobe Stock service returns information about all found assets that also match the filtering criteria.
Tip: Assets on Adobe Stock can be added, changed, or removed by other parties between your API calls. Therefore, the total number of matching assets and the selection of assets can change between successive calls to Search.
All responses are in a JSON array with this general structure:
Copied to your clipboard{"nb_results" : value,"files": [{ details_for_first_file ...field_name: value,...},{ details_for_second_file ...field_name: value,...}]}
Response fields
These are the fields returned either by default or by explicit use by the result_columns[]
parameter.
Parameter | Description |
---|---|
nb_results | Total number of found assets in the search result. Integer. |
id | Asset's unique identifier. Integer. |
title | Asset's title. String. |
creator_id | Unique identifier for the asset's creator. Integer. |
creator_name | Asset creator's name. String. |
country_name | Country in which the asset's creator lives. String. |
thumbnail_url | URL for the default-sized asset thumbnail. You can use this to display the thumbnail on your page using your preferred display method. Alternatively, use thumbnail_html_tag . String. |
thumbnail_html_tag | HTML <img> tag that you can use to display the default asset thumbnail. This is a convenience for displaying the thumbnail and references the thumbnail_url . String. Example:"thumbnail_html_tag": "<img src='https://thumbnail-url' alt='German Shepherd Dog Sticking Head Out Driving Car Window' />" |
thumbnail_width | Thumbnail's width in pixels. Integer. |
thumbnail_height | Thumbnail's height in pixels. Integer. |
thumbnail_*_width | Width for the thumbnail of the requested size, where * is the thumbnail size in pixels. Float. For example: "thumbnail_160_width": 200 |
thumbnail_*_height | Height for the thumbnail of the requested size, where * is the thumbnail size in pixels. Integer. |
thumbnail_*_url | URL for the requested thumbnail size, where * is the thumbnail size in pixels. You can use this to display the thumbnail on your page using your preferred display method. Alternatively, use thumbnail_*_html_tag . String. |
thumbnail_*_html_tag | HTML <img> tag that you can use to display the thumbnail of the requested size, where where * is the thumbnail size in pixels. This is a convenience for displaying the thumbnail and references the thumbnail_*_url . String. |
width | Width in pixels of the full-sized original asset. Integer. |
height | Height in pixels of the full-sized original asset. Integer. |
is_licensed | The Adobe Stock licensing state for the asset. String. Values and meaning:
|
comp_url | URL to the watermarked version of the asset. String. |
comp_width | Width in pixels of the asset's complementary (unlicensed) image. Integer. |
comp_height | Height in pixels of the asset's complementary (unlicensed) image. Integer. |
category | JSON structure with information about the category assigned to the asset. "category": { "id": 0000,"name":"..." } For example: "category": { "id": 47, "name": "Dogs"} |
categoryid | Identifier for the category assigned to the asset. Integer. |
categoryname | Localized name of the asset's category. String. |
keywords | List of localized keywords for the asset. Array. |
media_type_id | Type of the asset. Integer.
|
vector_type | If the asset is a vector, this indicates whether it is an SVG or an AI/EPS asset. String. Values and meanings:
|
content-type | Mime type of the asset's content. String. For example: "content_type": "image/jpeg" |
framerate | Frame rate for the asset if it is a video. Float. |
duration | Duration in milliseconds of the asset if it is a video. Integer. |
comps | JSON object that contains one or more of the following properties for complementary assets if applicable: Standard, Video_HD, or Video_4K. The properties contain width, height, comp URL. See Example returned comps values. |
details_url | URL to the Adobe Stock details page for the asset. If you pass the Authorization header with the call, Adobe Stock generates an SSO jump URL. String. |
3d_type_id | The ID of the 3D type, if the return asset is 3D. Values and meanings:
|
template_type_id | The ID of the template type, if the returned asset is a template. Integer. Values and meanings:
|
marketing_text | Marketing text for the template in Markdown format, if the found asset is a template. String. |
description | Description text for the template in Markdown format, if the found asset is a template. String. |
size_bytes | Size of the template file in bytes, if the found asset is a template. Integer. |
premium_level_id | Asset's premium (pricing) level. Integer.
|
is_loop | True if the asset is a looping video or audio clip. Boolean. |
is_transparent | True for PNG assets that have transparency. Boolean. |
is_gentech | True if asset was generated by AI. Boolean. |
icon_option | icon type (icon_sheet, single_icon or null) |
Example returned comps values
Image:
Copied to your clipboard"comps": {"Standard": {"url": "https://stock.adobe.io/Rest/Libraries/Watermarked/Download/76203302/1","width": 1000,"height": 248}}
Vector:
Copied to your clipboard"comps": {"Standard": {"url": "https://stock.adobe.io/Rest/Libraries/Watermarked/Download/47788193/1","width": 770,"height": 1000}}
Video that is available in 4K or HD:
Copied to your clipboard"comps": {"Video_HD": {"url": "https://stock.adobe.io/Rest/Libraries/Watermarked/Download/106945684/3","width": 1920,"height": 1080},"Video_4K": {"url": "https://stock.adobe.io/Rest/Libraries/Watermarked/Download/106945684/4","width": 3840,"height": 2160}}
Video that is in HD only:
Copied to your clipboard"comps": {"Video_HD": {"url": "https://stock.adobe.io/Rest/Libraries/Watermarked/Download/109410569/3","width": 1920,"height": 1080}}
Example queries and responses
This example searches for assets that have the keyword "dog" and returns no more than the first two matches.
Copied to your clipboardGET /Rest/Media/1/Search/Files?locale=en_US&search_parameters[words]=dogs&search_parameters[limit]=2 HTTP/1.1Host: stock.adobe.ioX-Product: MySampleApp/1.0x-api-key: MyApiKey
The preceding request returns two asset descriptions. nb_results
shows that 399,884 assets currently match the keyword "dog".
Copied to your clipboard{"nb_results": 399884,"files": [{"id": 86760419,"title": "German Shepherd Dog Sticking Head Out Driving Car Window","width": 3454,"height": 2303,"creator_name": "Christin Lola","creator_id": 204004289,"thumbnail_url":"https://as1.ftcdn.net/jpg/00/86/76/04/110_F_86760419_NEhOeuriYu82RwfgDqjTeIL9yx7ih5iv.jpg","thumbnail_html_tag":"<img src='https://as1.ftcdn.net/jpg/00/86/76/04/110_F_86760419_NEhOeuriYu82RwfgDqjTeIL9yx7ih5iv.jpg'alt='German Shepherd Dog Sticking Head Out Driving Car Window'title='Photo: German Shepherd Dog Sticking Head Out Driving Car Window' />","thumbnail_width": 110,"thumbnail_height": 73,"media_type_id": 1,"vector_type": null,"category": {"id": 47,"name": "Dogs"}},{"id": 84977202,"title": "Happy dog playing outside and carrying the American flag","width": 5616,"height": 3744,"creator_name": "SSilver","creator_id": 200407313,"thumbnail_url": "https://as1.ftcdn.net/jpg/00/84/97/72/110_F_84977202_JplQMoMQ5QiZCgVeWLwKhFHCrr4HG99Q.jpg","thumbnail_html_tag":"<img src='https://as1.ftcdn.net/jpg/00/84/97/72/110_F_84977202_JplQMoMQ5QiZCgVeWLwKhFHCrr4HG99Q.jpg'alt='Happy dog playing outside and carrying the American flag'title='Photo: Happy dog playing outside and carrying the American flag' />","thumbnail_width": 110,"thumbnail_height": 73,"media_type_id": 1,"vector_type": null,"category": {"id": 47,"name": "Dogs"}}]}
Common search queries
Here are simple examples of common searches.
- Keyword search; assets matching "purple" and "clouds":
Copied to your clipboardhttps://stock.adobe.io/Rest/Media/1/Search/Files?search_parameters[words]=purple+clouds&locale=en_US
- Using pagination, get the 3rd page of results (rows 200-300) for the word "dogs":
Copied to your clipboardhttps://stock.adobe.io/Rest/Media/1/Search/Files?search_parameters[words]=dogs&search_parameters[limit]=100&search_parameters[offset]=200&locale=en_US
- Search for assets similar in appearance to the specified asset ID:
Copied to your clipboardhttps://stock.adobe.io/Rest/Media/1/Search/Files?search_parameters[similar]=121353611&locale=en_US
- Search for assets similar in appearance to the specified URL:
Copied to your clipboardhttps://stock.adobe.io/Rest/Media/1/Search/Files?search_parameters[similar_url]=https://i.kinja-img.com/gawker-media/image/upload/xqkbwkexcl7udc5va7pn.jpg&locale=en_US
- Similar asset by URL and keyword:
Copied to your clipboardhttps://stock.adobe.io/Rest/Media/1/Search/Files?search_parameters[similar_url]=https://i.kinja-img.com/gawker-media/image/upload/xqkbwkexcl7udc5va7pn.jpg&search_parameters[words]=cats&locale=en_US
- Search for assets depicting the specified model:
Copied to your clipboardhttps://stock.adobe.io/Rest/Media/1/Search/Files?search_parameters[model_id]=58344279&locale=en_US
Error codes
Each error generates a JSON array that contains the following keys and values. If your application receives this array and you need assistance, send the array to Adobe.
- An
error
key. - Optionally a
code
key. Specifies an integer designating the category of error. Code values:10
: Invalid access token. The access token that you passed is invalid or expired.11
: Invalid API Key. The API key that you passed is not valid or has expired.20
: Invalid parameters. The URL parameters that you passed are not supported.31
: Invalid Method. The method that you specified does not exist in the method list.100
: Invalid data. Data that you specified as arguments are not supported.
More information
- See the practical search example in Search for assets.
- Refer to the Affiliate API Workflow guide for a complete guide to partnering with Adobe Stock and using the Search API.