Files API

building

Sizes, expiries, widths, and every accepted content type.

Limits and formats

Images we can resize50 MB
Everything else500 MB
Upload URL expiry15 minutes (6 hours for a multipart part)
Split into parts above100 MB, in 10 MB parts
Private URL expiry5 minutes
Page size20
Key requiredsecret (sk_…)
Widths100, 300, 400, 600, 800, 1000, 1200

The image limit is the resizing limit, and that is the point of it. Two different numbers would allow a file that uploads fine and whose smaller versions never arrive — a state that is hard to explain and easy to hit. One number deletes it: anything accepted as a resizable image can be resized.

Both are checked before a byte moves, and the error names the one that applied:

400
1{ "error": "That file is 95.4 MB. The limit is 50 MB for images, so every image can have its smaller versions built." }

Quotas

Separate from the per-request limits above: these are ceilings on what a project holds, checked when an upload is started.

Default
Stored bytes100 GB
Files1,000,000

Past a ceiling, an upload intent is refused before any bytes move:

413
1{ "error": "This project holds 104.2 GB and its limit is 100.0 GB. Delete something, or ask us to raise it." }

Checked at intent rather than at confirm, because the presigned URL is the commitment — once a client holds one the bytes are going to storage whatever we decide afterwards.

Both are raisable per project. Ask.

Resizable formats

These get variants and a srcset, and take the 50 MB limit.

image/jpeg   image/png   image/gif   image/webp   image/avif   image/tiff

Variants are always WebP whatever the source was, so a TIFF that no browser renders still produces sizes that every browser renders.

Stored and served, not resized

500 MB limit, no variants.

image/svg+xml  image/bmp  image/ico
image/vnd.adobe.photoshop  image/x-adobe-dng  application/x-photoshop
application/pdf  application/msword  application/vnd.ms-excel
application/vnd.ms-powerpoint  and the OpenXML equivalents
text/plain  text/csv  text/html  text/css  text/javascript
application/json  application/xml
application/zip  application/gzip  application/x-tar
audio/mpeg  audio/wav  audio/ogg  audio/webm
video/mp4  video/webm  video/ogg
font/woff  font/woff2  font/ttf  font/otf
application/postscript  application/illustrator
application/x-indesign  application/vnd.adobe.indesign-idml-package
application/vnd.adobe.aftereffects.project  application/vnd.adobe.premiere
application/vnd.adobe.xd
model/gltf-binary  model/gltf+json

Two are worth calling out. SVG is vector — it has no widths to render and is served as the original at any size. Photoshop documents and raws are image/* by MIME type but cannot be decoded by the resizer, which is why they take the larger limit rather than the image one.

Anything on neither list is refused:

400
1{ "error": "Content type not allowed" }

Displayable is not the same as resizable

Worth knowing when you render an original directly. Browsers draw JPEG, PNG, GIF, WebP, AVIF and SVG. They do not draw TIFF, BMP, ICO, PSD or DNG — put one in an and you get a download or a broken icon, whatever its size. Use srcset and the browser picks a WebP variant instead.