Image Transformations
Resize, crop, optimize, and convert UploadKit Cloud images at the edge.
UploadKit generates CDN-cached image variants without creating additional objects in your project. Originals remain unchanged in Cloudflare R2. Choose stable public URLs at cdn.uploadkit.dev/p/* or expiring signed URLs at cdn.uploadkit.dev/t/*.
Image transformations require a paid plan and UploadKit-managed cloud storage. Files uploaded through BYOS adapters are never accessible to the transformation service.
Plan limits
| Plan | Transformation units/month |
|---|---|
| Free | Not available |
| Pro | 5,000 |
| Team | 25,000 |
| Enterprise | Custom, starting at 100,000 |
Usage is shared across every project owned by the account and resets each calendar month.
How units are counted
A transformation unit is reserved when the API issues the first signed URL for a combination of source file, dimensions, fit mode, quality, and explicit output format during the current month. Requesting the same combination again does not consume more units, even after the URL expires. CDN cache hits do not consume quota. Changing any option creates a new variant.
Explicit formats (avif, webp, jpeg, or png) reserve 1 unit. format: 'auto' reserves 3 units because it can create separate AVIF, WebP, and JPEG variants based on the browser's Accept header. Units are reserved when the URL is issued, whether or not the URL is subsequently fetched.
Supported options
| Option | Values | Default |
|---|---|---|
width | 1–4096 pixels | — |
height | 1–4096 pixels | — |
fit | scale-down, contain, cover, crop, pad | scale-down |
quality | 1–100 | 85 |
format | auto, avif, webp, jpeg, png | auto |
delivery | signed, public | signed |
At least one dimension is required. format: 'auto' negotiates AVIF or WebP from the browser's Accept header and falls back to JPEG.
Public and signed delivery
Use delivery: 'public' for assets that must keep working in a website or app without backend refreshes: avatars, product images, article media, Open Graph images, CSS backgrounds, and responsive srcset URLs. Public transform URLs are stable and have no expiry:
https://cdn.uploadkit.dev/p/<signature>/w_800,h_600,fit_cover,q_80,f_webp/<file-key>Use delivery: 'signed' for private or temporary content. Signed URLs are valid for at most 25 hours:
The cloud API verifies the plan, project ownership, upload status, MIME type, and monthly quota before issuing a URL. Every URL contains an HMAC signature and expiry; altering its file key or options invalidates it.
https://cdn.uploadkit.dev/t/<expires>/<signature>/w_800,h_600,fit_cover,q_80,f_webp/<file-key>Signed delivery protects and expires the transformed URL. It does not retroactively make the original private if its public Cloud URL has already been exposed. Do not publish the original URL when the transformed asset is access-controlled.
Generate URLs in trusted server code with a live (uk_live_) key through the Core SDK or REST API. Test keys cannot issue transformation URLs. Never expose an UploadKit API key in browser code.
Both URL types include an HMAC signature, so changing the file key or transformation options invalidates the URL. Public means the URL does not expire; it does not mean callers can create arbitrary variants without your API key.
The recipe segment is intentionally readable: w and h are dimensions, fit is the resize mode, q is quality, and f is the output format. It is safe to inspect and log, but not to edit manually—the signature covers the exact recipe. Generate a new signed URL through the SDK, API, MCP, or dashboard when options change. URLs issued before readable recipes were introduced remain valid.
Public URLs remain stable across normal deployments and rotation of the short-lived signing key. UploadKit may invalidate them only during a security incident involving the dedicated public-signing key.
Transformed responses are cached at the edge for at most one hour. The URL remains valid when a cache entry expires: UploadKit regenerates the variant from the original on the next request. Deleting the source prevents new cache misses from being generated; an already cached response can remain available until that cache window ends.