Box Developer Documentation

Join BoxWorks 2024 to discover what's possible with content and AI!

Register now!

Get Basic Thumbnail

Get Basic Thumbnail

A thumbnail is a small image, either as .png or as .jpg that can be used in an application as a representation of the file, for example as a placeholder for a link that downloads or previews the file.

The preferred way to get a thumbnail for a file is using the representations API.

Requesting

To request a file thumbnail use the GET /files/:id/thumbnail.:extension endpoint.

cURL
curl -i -X GET "https://api.box.com/2.0/files/12345/thumbnail.png" \
     -H "authorization: Bearer <ACCESS_TOKEN>"
TypeScript Gen
await client.files.getFileThumbnailById(
  thumbnailFile.id,
  'png' as GetFileThumbnailByIdExtension,
);
Python Gen
client.files.get_file_thumbnail_by_id(
    thumbnail_file.id, GetFileThumbnailByIdExtension.PNG.value
)
.NET Gen
await client.Files.GetFileThumbnailByIdAsync(fileId: thumbnailFile.Id, extension: GetFileThumbnailByIdExtension.Png);
Swift Gen (Beta)
try await client.files.getFileThumbnailById(fileId: thumbnailFile.id, extension_: GetFileThumbnailByIdExtension.png, downloadDestinationURL: destinationPath)
Python
file_id = '11111'

thumbnail = client.file(file_id).get_thumbnail_representation('92x92', extension='jpg')
.NET
Stream thumbnailContents = await client.FilesManager.GetThumbnailAsync("11111", maxWidth: 160, maxHeight: 160);
iOS
client.files.getThumbnail(forFile: "11111", extension: .png) { (result: Result<Data, BoxSDKError>) in
    guard case let .success(thumbnailData) = result else {
        print("Error getting file thumbnail")
        return
    }

    let thumbnailImage = UIImage(data: thumbnailData)
}

When a thumbnail was successfully created, this will return the thumbnail in the body of the response as binary data.

Asynchronous thumbnail creation

Sometimes the thumbnail can not be created directly. Instead, the API will return a HTTP 202 with a location response header. The location is for a temporary image that can be used while the thumbnail is being generated.

A retry-after response header is also provided to present you with an estimated amount of seconds before retrying this endpoint.

Supported file sizes

The following formats and sizes of thumbnails are available.

File TypeDimensions
JPG32x32, 94x94, 160x160, 320x320, 1024x1024, 2048x2048*
PNG1024x1024*, 2048x2048*

Some restrictions apply to the sizes marked as *.

File size restrictions

Original file size

Thumbnails are not scaled up. If the original file size of the file uploaded to Box is smaller than the representation dimensions, the resulting thumbnail is capped at the size of the original file.

Supported file types

At this time the following file types are supported.

File TypeFile Extensions
Documentsdoc, docx, gdoc, gsheet, gslide, gslides, odp, ods, odt, pdf, ppt, pptx, rtf, wpd, xls, xlsm, xlsx, key, pages, numbers
Imagesai, bmp, dcm, dicm, eps, gif, idml, indd, indt, inx, jpeg, jpg, png, ps, psd, svg, svs, tif, tiff, tga
Audioaac, aifc, aiff, amr, au, flac, m4a, mp3, ogg, ra, wav, wma
Video3g2, 3gp, avi, m2v, m2ts, m4v, mkv, mov, mp4, mpeg, mpg, mts, ogg, qt, wmv