Edit

Share via

List thumbnails for a DriveItem

  • Article

Retrieve a collection of ThumbnailSet resources for a DriveItem resource.

A DriveItem can be represented by zero or more ThumbnailSet resources. Each thumbnailSet can have one or more thumbnail objects, which are images that represent the item. For example, a thumbnailSet may include thumbnail objects, such as common ones including small, medium, or large.

There are many ways to work with thumbnails on OneDrive. Here are the most common ones:

  • Enumerate available thumbnails for an item
  • Retrieve a single thumbnail for an item
  • Retrieve thumbnail content
  • Retrieve thumbnails for multiple items in a single request
  • Retrieve custom thumbnail sizes
  • Upload a custom thumbnail for an item
  • Determine if a custom uploaded thumbnail exists

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Permission type Permissions (from least to most privileged)
Delegated (work or school account) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Delegated (personal Microsoft account) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All
Application Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All

HTTP request

GET /drives/{drive-id}/items/{item-id}/thumbnails
GET /groups/{group-id}/drive/items/{item-id}/thumbnails
GET /me/drive/items/{item-id}/thumbnails
GET /sites/{site-id}/drive/items/{item-id}/thumbnails
GET /users/{user-id}/drive/items/{item-id}/thumbnails

Optional query parameters

This method supports the $select OData query parameter to customize the response.

Response

If successful, this method returns a 200 OK response code and collection of ThumbnailSet objects in the response body.

Example

Here is an example of the request which retrieves available thumbnails for an item in the current user's OneDrive.

GET /me/drive/items/{item-id}/thumbnails

This returns an array of available thumbnailSets for the item. Any item in a drive can have zero or more thumbnails.

Note: You can use the select query string parameter to control which thumbnail sizes are returned in the ThumbnailSet. For example, /thumbnails?select=medium retrieves only the medium sized thumbnails.

Response

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "0",
      "small": { "height": 64, "width": 96, "url": "https://sn3302files..."},
      "medium": { "height": 117, "width": 176, "url": "https://sn3302files..."},
      "large": { "height": 533, "width": 800, "url": "https://sn3302files..."}
    }
  ]
}

Get a single thumbnail

Retrieve the metadata for a single thumbnail and size by addressing it directly in a request.

HTTP request

GET /me/drive/items/{item-id}/thumbnails/{thumb-id}/{size}

Path parameters

Name Type Description
item-id string The unique identifier for the item referenced.
thumb-id number The index of the thumbnail, usually 0-4. If there is a custom thumbnail, its index is 0.
size string The size of the thumbnail requested. This can be one of the standard sizes listed below or a custom size. 
HTTP/1.1 200 OK
Content-Type: application/json

{
  "width": 100,
  "height": 100,
  "url": "http://onedrive.com/asd123a/asdjlkasjdkasdjlk.jpg"
}

Retrieve thumbnail binary content

You can directly retrieve the content of the thumbnail by requesting the content property of the thumbnail.

HTTP request

GET /me/drive/items/{item-id}/thumbnails/{thumb-id}/{size}/content

Response

The service responds with a redirect to the thumbnail URL.

HTTP/1.1 302 Found
Location: https://b0mpua-by3301.files.1drv.com/y23vmagahszhxzlcvhasdhasghasodfi

Thumbnail URLs are cache-safe. The URL will change, if the item changes in a way that requires a new thumbnail to be generated.

Getting thumbnails while listing DriveItems

If you are retrieving a list of DriveItem resources to display, you can use the $expand query string parameter to also include the thumbnails for those resources. This enables your app to retrieve thumbnails and items in a single request, instead of issuing many requests.

HTTP request

GET /me/drive/items/{item-id}/children?$expand=thumbnails

Response

The service responses with the list of DriveItems and their thumbnails.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "182331E8-2788-4932-B52A-A6550577043F",
      "name": "my photo.jpg",
      "thumbnails": [
        {
          "small": { "width": 96,
                     "height": 96,
                     "url": "https://sn3302files..."
                   }
        }
      ]
    },
    {
      "id": "2D223953-A56B-4D9B-ADF3-13E7820673A2",
      "name": "presentation.pptx",
      "thumbnails": [
        {
          "small": { "width": 96,
                     "height": 96,
                     "url": "https://sn3302files..."
                   }
        }
      ]
    }
  ]
}

Size options

This table defines the possible thumbnail sizes. While you can request any arbitrary thumbnail size, the defined values are likely to exist and return a value quickly:

Name Resolution Aspect Ratio Description
small 96 longest Original Small, highly compressed thumbnail cropped to a square aspect ratio.
medium 176 longest Original Cropped to the standard item size for the OneDrive web view.
large 800 longest Original Thumbnail with the longest edge resized to 800 pixels.
smallSquare 96x96 Square Crop Small square thumbnail
mediumSquare 176x176 Square Crop Small square thumbnail
largeSquare 800x800 Square Crop Large square thumbnail

Requesting custom thumbnail sizes

In addition to the defined sizes, your app can request a custom thumbnail size by specifying the dimensions of the thumbnail prefixed with c. For example if your app needs thumbnails that are 300x400, it can request that size like this:

GET /me/drive/items/{item-id}/thumbnails?select=c300x400_Crop

Which responds with just the custom thumbnail size selected:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "value": [
    {
      "id": "0",
      "c300x400_Crop": { "height": 300, "width": 400, "url": "https://sn3302files.onedrive.com/123"},
    }
  ]
}

You can specify the following options after the size of the thumbnail requested:

Examples of custom identifiers

Thumbnail identifier Resolution Aspect ratio Description
c300x400 Bounded by 300x400 box Original Generate a thumbnail that fits inside a 300x400 pixel box, maintaining aspect ratio
c300x400_Crop 300x400 Cropped Generate a thumbnail that is 300x400 pixels. This works by resizing the image to fill the 300x400 box and cropping whatever spills outside the box.

Note: The thumbnail returned may not exactly match the pixel dimensions that was requested, but will match the aspect ratio. In some cases, a larger thumbnail may be returned than was requested, if the thumbnail already exists and can easily be scaled to match the requested resolution.

Remarks

Note In OneDrive for Business and SharePoint:

Using these calls to expand the thumbnails collection will not work:

  • GET /drive/root:/{item-path}?expand=children(expand=thumbnails)
  • GET /drive/items/{item-id}/children?expand=thumbnails

Thumbnails are not supported on SharePoint Server 2016.

Error responses

See Error Responses for more info about how errors are returned.