Skip to content

Thumbnail Image API

Introduction

Like most commercial image hosting services, we have chosen to implement a cookie-free thumbnail API to minimize request latency by avoiding unnecessary network traffic:

  • When a browser requests static files such as images from a server over HTTPS, it is generally unnecessary to send a cookie with each request if the URLs cannot be guessed, so for most practical use cases
  • One possible use of cookies may be to prevent the user from intentionally or accidentally sharing confidential thumbnail URLs with others
  • This is possible with most image hosting services/social media sites, and could also be considered a feature if you just want to share a few thumbnails without a lot of bells and whistles
  • Once an image has been downloaded by someone else, blocking the original URL provides little additional security, as digital copies are just as good as the original, see info box below
  • Keeping that in mind, previously shared URLs can be invalidated by changing the security token in your config
  • This will invalidate the browser cache on all connected devices, requiring previously cached thumbnails to be downloaded again
  • Be aware that frequent token changes result in performance degradation and a poor user experience.

In addition to better performance, a major advantage of cookie-free thumbnails is that they can be easily integrated into a content delivery network (CDN), since there is no need to check cookies or add other complex logic on edge servers.

Since most users only have one domain/host name and modern web applications can store authentication tokens in localStorage, our Thumbnail Image API does not currently require or use cookies.

Security Considerations

Digital copies are as good as originals: Once shared and downloaded, such images should be considered "leaked" because they are cached and can be re-shared by the recipient at any time, with no sure way to get all copies back, even if the download URL becomes invalid or the service is shut down completely.

Any form of protection we could provide would essentially be "snake oil", could be circumvented, and would have a negative impact on the user experience, such as disabling the browser cache or context menu.

For the highest level of protection, it is recommended to shield your private server from the public Internet. Always use HTTPS, a VPN and/or ideally TLS client certificates and make sure that only people you trust have access to your instance.

Further Reading

Image Endpoint URI

A GET request to the following URI returns a thumbnail image of the specified size for the picture referenced by the SHA1 hash:

/api/v1/t/:hash/:token/:size

If the instance requires authentication, you must also specify a valid security token, e.g.:

/api/v1/t/a2195b6840f46b555719d8e22e9b080e61a7317c/10d68214/tile_500

With public mode enabled, you can instead use "public" as security token placeholder:

/api/v1/t/a2195b6840f46b555719d8e22e9b080e61a7317c/public/tile_500

Video Endpoint URI

A GET request to the following URI returns the video referenced by the SHA1 hash (transcoding and range requests are supported for streaming):

/api/v1/videos/:hash/:token/:format

If the instance requires authentication, you must also specify a valid security token, e.g.:

/api/v1/videos/51843134d75f4cbde534270cdd5954067f887ee6/10d68214/avc

With public mode enabled, you can instead use "public" as security token placeholder:

/api/v1/videos/51843134d75f4cbde534270cdd5954067f887ee6/public/avc

The only target format currently available for transcoding is avc (MPEG-4 AVC). Additional formats will become available in a future release.

Thumbnail Sizes

The smallest configurable static and dynamic size limit is 720px, so most sizes up to fit_720 are always generated by default. Higher size limits generate thumbnails with more detail at higher resolutions - either statically (pre-generated while indexing) or on demand if the configuration permits.

Optional thumbnail sizes cannot be pre-generated and are only rendered on request, for example when sharing an image on Instagram.

The following overview shows the name, dimensions, and aspect ratio for each thumbnail size as well as a description of how it is used:

Name Width Height Aspect Ratio Available Usage
colors 3 3 1:1 Always Color Detection
tile_50 50 50 1:1 Always List View
tile_100 100 100 1:1 Always Places View
left_224 224 224 1:1 On-Demand TensorFlow
right_224 224 224 1:1 On-Demand TensorFlow
tile_224 224 224 1:1 Always TensorFlow, Mosaic View
tile_500 500 500 1:1 Always Cards View
fit_720 720 720 Preserved Always SD TV, Mobile
tile_1080 1080 1080 1:1 Optional Instagram
fit_1280 1280 1024 Preserved On-Demand HD TV, SXGA
fit_1600 1600 900 Preserved Optional Social Media
fit_1920 1920 1200 Preserved On-Demand Full HD
fit_2048 2048 2048 Preserved Optional DCI 2K, Tablets
fit_2560 2560 1600 Preserved On-Demand Quad HD, Notebooks
fit_3840 3840 2400 Preserved Optional 4K Ultra HD
fit_4096 4096 4096 Preserved On-Demand DCI 4K, Retina 4K
fit_7680 7680 4320 Preserved On-Demand 8K Ultra HD 2

↪ internal/thumb/sizes.go

Generated thumbnail files are stored in the storage/cache/thumbnails folder, where the path and file name depend on the thumbnail size and original file hash. Learn more ›