/assetsendpoint can be used to stream or retrieve the actual file contents from assets managed within Directus.
# Accessing an Original File
The location of your actual file originals is based on the project's configuration, but you can consistently access them via the API using the following URL.
Original File Used — 602KB and 1800x1200
Direct File Access
While you may technically be able to expose your storage adapters root filesystem and access your raw files through there, it is recommended that you always use the Directus API. This is the only way that you can take advantage of file permissions and other built-in features.
# Requesting a Thumbnail
Fetching thumbnails is as easy as adding query parameters to the original file's URL. If a requested thumbnail doesn't
yet exist, it is dynamically generated and immediately returned. When requesting a thumbnail, the following parameters
are all required, supports thumbnail for
fit— The fit of the thumbnail while always preserving the aspect ratio, can be any of the following options:
cover— Covers both width/height by cropping/clipping to fit
contain— Contain within both width/height using "letterboxing" as needed
inside— Resize to be as large as possible, ensuring dimensions are less than or equal to the requested width and height
outside— Resize to be as small as possible, ensuring dimensions are greater than or equal to the requested width and height
width— The width of the thumbnail in pixels
height— The height of the thumbnail in pixels
quality— The quality of the thumbnail (
withoutEnlargement— Disable image up-scaling
Content-Dispositionheader and force browser to download file
Alternatively, you can reference a specific thumbnail by its preset key.
key— This key of the Storage Asset Preset, a shortcut for the above parameters
# Cover vs Contain
For easier comparison, both of the examples below were requested at
200 height, and
75 quality. The
cover thumbnail forces the dimensions, trimming the outside edges as needed. The
contain thumbnail always maintains
its aspect ratio, shrinking the image to fit within the dimensions and adding "letterboxing" as needed.
8KB • 200x200
6KB • 200x133
Images are never stretched or distorted even when changing the aspect ratio.
# Quality vs Filesize
The quality parameter can be any integer from
0-100. Qualities closer to
0 have lower filesizes, but also poor image
quality due to compression artifacts. Values closer to
100 have larger filesizes, but better image quality. Below are
four possible qualities (200x200 cover) to visually compare the balance between compression and filesize.
# Downloading a File
To download an asset with the correct filename, you need to add the
?download query parameter to the request and the
download attribute to your anchor tag. This will ensure the appropriate
Content-Disposition (opens new window) headers are added. Without this, the
download will work on the same domain, however it will have the file's "id" as the filename for cross-origin requests.
<a href="https://your-directus.com/assets/<file-id>?download" target="_blank" download="Your File.pdf">Download</a>