Bulk metadata Files API reference

The Files API is used to retrieve metadata from Adobe Stock, either one asset at a time, or in bulk.

Files requests

The Files API returns a JSON-formatted list of metadata attributes for a given list of Stock asset IDs.

Endpoints	Methods
https://stock.adobe.io/Rest/Media/1/Files	GET

Authentication

Optional. The Authorization header is only required for retrieving the is_licensed field.

Request headers

See Headers for Stock API Calls for details about header content.

Required headers: x-Product, x-api-key, Authorization
Optional headers: X-Product-Location, X-Request-Id

URL parameters

Parameter	Description
ids	Comma-separated list of file IDs, e.g. `ids=100,101`. Maximum number of IDs is 110. Exceeding this limit triggers an error. String.
locale	Optional. Location language code for the API to use when returning localized messages. The API can usually get the user's default locale through the Authorization header. This value overrides that or provides a locale if not available through Authorization. String. Default is en-US. See the full list of Locales.
result_columns[]	Optional. Fields to include in response. Note that some fields (e.g., `is_licensed`) require an authorization token. Array[]. ✅Tip1: To combine results, use this syntax: `result_columns[]=title&result_columns[]=creation_date` ✅Tip2: `nb_results` will return the number of files that exist. Use this to determine if a set of content IDs are still available. By default, only `id` is returned. id :: nb_results :: title :: creator_name :: creator_id :: country_name :: width :: height :: thumbnail_url :: thumbnail_html_tag :: thumbnail_width :: thumbnail_height :: thumbnail_110_url :: thumbnail_110_width :: thumbnail_110_height :: thumbnail_160_url :: thumbnail_160_width :: thumbnail_160_height :: thumbnail_220_url :: thumbnail_220_width :: thumbnail_220_height :: thumbnail_240_url :: thumbnail_240_width :: thumbnail_240_height :: thumbnail_500_url :: thumbnail_500_width :: thumbnail_500_height :: thumbnail_1000_url :: thumbnail_1000_width :: thumbnail_1000_height :: media_type_id :: category :: category_hierarchy :: keywords :: has_releases :: comp_url :: comp_width :: comp_height :: is_licensed :: vector_type :: content_type :: framerate :: duration :: comps :: details_url :: template_type_id :: template_category_ids :: marketing_text :: description :: size_bytes :: premium_level_id :: is_premium :: is_loop :: is_transparent :: licenses :: video_preview_url :: video_preview_width :: video_preview_height :: video_preview_content_length :: video_preview_content_type :: video_small_preview_url :: video_small_preview_width :: video_small_preview_height :: video_small_preview_content_length :: video_small_preview_content_type :: is_gentech :: icon_option

Responses

The response for any given request is dependent on the value of the result_columns argument. As mentioned, the only field returned by default is id (Stock asset ID, integer).

All responses are in a JSON array with this general structure:

{
  "nb_results" : value,
  "files": [
     { details_for_first_file ...
          field_name: value,
          ...
     },
     { details_for_second_file   ...
          field_name: value,
          ...
     }
  ]
}
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: `Standard`: License for the full-resolution asset `Extended`: Extended license `Video_HD`: Video HD license `Video_4K`: Video 4K license `Standard_M`: License for a medium-size asset approximately 1600x1200 pixels `""` (empty string): No license applies
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. `1`: Photos `2`: Illustrations `3`: Vectors `4`: Videos `6`: 3D `7`: Templates `8`: Premium `9`: Audio
vector_type	If the asset is a vector, this indicates whether it is an SVG or an AI/EPS asset. String. Values and meanings: `svg`: SVG file `zip`: AI/EPS file
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: 1 - Models 2 - Lights 3 - Materials
template_type_id	The ID of the template type, if the returned asset is a template. Integer. Values and meanings: `1`: PSDT `2`: AIT `3`: INDT `4`: PPRO Motion Graphics Template `5`: AE Motion Graphics Template
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. `0`: Core/standard `1`: Free `2`: Premium level 1 `3`: Premium level 2 `4`: Premium level 3
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:

  "comps": {
    "Standard": {
      "url": "https://stock.adobe.io/Rest/Libraries/Watermarked/Download/76203302/1",
      "width": 1000,
      "height": 248
    }
  }
Copied to your clipboard
  "comps": {
    "Standard": {
      "url": "https://stock.adobe.io/Rest/Libraries/Watermarked/Download/76203302/1",
      "width": 1000,
      "height": 248
    }
  }

Vector:

"comps": {
    "Standard": {
      "url": "https://stock.adobe.io/Rest/Libraries/Watermarked/Download/47788193/1",
      "width": 770,
      "height": 1000
    }
  }
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:

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

  "comps": {
    "Video_HD": {
      "url": "https://stock.adobe.io/Rest/Libraries/Watermarked/Download/109410569/3",
      "width": 1920,
      "height": 1080
    }
  }
Copied to your clipboard
  "comps": {
    "Video_HD": {
      "url": "https://stock.adobe.io/Rest/Libraries/Watermarked/Download/109410569/3",
      "width": 1920,
      "height": 1080
    }
  }

Example requests and responses

The basic use of the API (without setting result columns) only returns the list of IDs without additional metadata.

GET /Rest/Media/1/Files?ids=12345678,57185897,94682947,180905406,175119903,113187776,120451263,117684952,84666330,70910021,89866754,97126353 HTTP/1.1
Host: stock.adobe.io
X-Product: MySampleApp/1.0
x-api-key: MyApiKey
Copied to your clipboard
GET /Rest/Media/1/Files?ids=12345678,57185897,94682947,180905406,175119903,113187776,120451263,117684952,84666330,70910021,89866754,97126353 HTTP/1.1
Host: stock.adobe.io
X-Product: MySampleApp/1.0
x-api-key: MyApiKey

Note that in the response, ID "12345678" does not exist because it is not returned by the API. This is expected behavior. Rather than throw an error for missing assets, it excludes them from the results. This way, the entire request does not fail.

{
    "files": [
        {
            "id": 57185897
        },
        {
            "id": 94682947
        },
        {
            "id": 180905406
        },
        {
            "id": 175119903
        },
        {
            "id": 113187776
        },
        {
            "id": 120451263
        }
    ]
}
Copied to your clipboard
{
    "files": [
        {
            "id": 57185897
        },
        {
            "id": 94682947
        },
        {
            "id": 180905406
        },
        {
            "id": 175119903
        },
        {
            "id": 113187776
        },
        {
            "id": 120451263
        }
    ]
}

This example requests the number of results (nb_results) as well as additional fields.

GET /Rest/Media/1/Files/?ids=77625150,117356939&result_columns[]=nb_results&result_columns[]=id&result_columns[]=thumbnail_url HTTP/1.1
Host: stock.adobe.io
X-Product: MySampleApp/1.0
x-api-key: MyApiKey
Copied to your clipboard
GET /Rest/Media/1/Files/?ids=77625150,117356939&result_columns[]=nb_results&result_columns[]=id&result_columns[]=thumbnail_url HTTP/1.1
Host: stock.adobe.io
X-Product: MySampleApp/1.0
x-api-key: MyApiKey

{
  "nb_results": 2,
  "files": [
    {
      "id": 77625150,
      "thumbnail_url": "https://as2.ftcdn.net/jpg/00/77/62/51/500_F_77625150_JCiDBzNWtLXnyuXROMgpquQ9NS64OTbY.jpg"
    },
    {
      "id": 117356939,
      "thumbnail_url": "https://as2.ftcdn.net/jpg/01/17/35/69/500_F_117356939_aJF1d2FMSQdrZ2M5m1aY1gjOcXbItMvJ.jpg"
    }
  ]
}
Copied to your clipboard
{
  "nb_results": 2,
  "files": [
    {
      "id": 77625150,
      "thumbnail_url": "https://as2.ftcdn.net/jpg/00/77/62/51/500_F_77625150_JCiDBzNWtLXnyuXROMgpquQ9NS64OTbY.jpg"
    },
    {
      "id": 117356939,
      "thumbnail_url": "https://as2.ftcdn.net/jpg/01/17/35/69/500_F_117356939_aJF1d2FMSQdrZ2M5m1aY1gjOcXbItMvJ.jpg"
    }
  ]
}

Error handling

If any error is encountered, the response will be a JSON object containing the key error with a textual description of the error and the key code with a numeric identifier for the error.

HTTP Status	JSON Code	JSON Message
400	600	The required X-Product header is missing or invalid
400	601	Authorization required when requesting `is_licensed` field
400	602	Invalid locale supplied
400	603	Invalid value in result_columns supplied
400	604	Unrecognized query parameter received.
404	605	Unknown id in supplied `ids` parameter
400	606	More than 110 IDs supplied for `ids` parameter

Example invalid requests and error responses

curl --header 'X-Api-Key: MyApiKey' 
  https://stock.adobe.io/Rest/Media/1/Files/?ids=100

{"error":"The required X-Product header is missing or invalid","code":"600","case":"ab4a0f466ed85a838853dae159edee6c"}
Copied to your clipboard
curl --header 'X-Api-Key: MyApiKey' 
  https://stock.adobe.io/Rest/Media/1/Files/?ids=100

{"error":"The required X-Product header is missing or invalid","code":"600","case":"ab4a0f466ed85a838853dae159edee6c"}

curl --header 'X-Api-Key: MyApiKey' 
  --header 'X-Product: MySampleApp/1.0' 
  https://stock.adobe.io/Rest/Media/1/Files/?ids=a, 100

{"error":"Required \"ids\" parameter is missing or invalid","code":"605","case":"01f49fa990a7579aa69b6fd232504c71"}
Copied to your clipboard
curl --header 'X-Api-Key: MyApiKey' 
  --header 'X-Product: MySampleApp/1.0' 
  https://stock.adobe.io/Rest/Media/1/Files/?ids=a, 100

{"error":"Required \"ids\" parameter is missing or invalid","code":"605","case":"01f49fa990a7579aa69b6fd232504c71"}