List thumbnails for a driveItem
Namespace: microsoft.graph
Important
APIs under the /beta
version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.
Retrieve a collection of thumbnailSet resources for a driveItem resource.
Zero or more thumbnailSet resources can represent a driveItem.
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're 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
This API is available in the following national cloud deployments.
Global service | US Government L4 | US Government L5 (DOD) | China operated by 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
Permissions
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.
Permission type | Least privileged permissions | Higher privileged permissions |
---|---|---|
Delegated (work or school account) | Files.Read | Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All |
Delegated (personal Microsoft account) | Files.Read | Files.Read.All, Files.ReadWrite, 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.
Additionally, this method supports retrieving the thumbnail with the original orientation EXIF value and without the applied rotation by appending the originalOrientation=true
query parameter.
It is currently only supported on OneDrive Personal.
Response
If successful, this method returns a 200 OK
response code and collection of ThumbnailSet objects in the response body.
Example
The following example shows a request that retrieves available thumbnails for an item in the current user's OneDrive.
GET /me/drive/items/{item-id}/thumbnails
It 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
The following example shows the 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's a custom thumbnail, its index is 0. |
size | string | The size of the thumbnail requested. It 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": "https://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 changes, if the item changes in a way that requires a new thumbnail to be generated.
Getting thumbnails while listing driveItems
If you're retrieving a list of driveItem resources to display, you can use the $expand query string parameter to also include the thumbnails for those resources. It 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 values
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. It 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 were requested, but does 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 doesn't work:
GET /drive/root:/{item-path}?expand=children(expand=thumbnails)
GET /drive/items/{item-id}/children?expand=thumbnails
Thumbnails aren't supported on SharePoint Server 2016.
Error responses
See Error responses for more info about how errors are returned.
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for