URL API
Every transformation lives in the path. Segments are optional unless marked required, but their order is fixed. The engine reads them positionally, so a filter cannot appear before a size.
https://img.focaltool.com/<delivery-key>/unsafe/<meta>/<trim>/<crop>/<fit-mode>/<WIDTH>x<HEIGHT>/<halign>/<valign>/filters:<pipeline>/<source>
Your delivery key is on the dashboard, next to each project. Examples below start from
/unsafe/ and leave the host and key out.
Segments
Signature
Required/unsafe/ Always `unsafe`. The engine keeps this slot for a signature, and Focal delivers public URLs, so nothing else goes here. Delivered images are publicly readable and fully cacheable: no key, no cookie, no auth.
Metadata
Optional/meta/ Returns JSON describing what the operation would produce, including source dimensions and the resolved operations, without encoding an image. Useful for debugging a crop.
Trim
Optional/trim/ · /trim:<orientation>/ · /trim:<orientation>:<tolerance>/ orientation: top-left (default) | bottom-right · tolerance: 0–442
Removes uniform surrounding space. The reference colour comes from the corner pixel you pick. Tolerance is the euclidean distance between RGB colours, so a higher number trims more of a noisy background.
Manual crop
Optional/<left>x<top>:<right>x<bottom>/ Crops to an explicit rectangle before any resize. Coordinates are in source pixels.
Fit mode
Optional/fit-in/ · /full-fit-in/ · /adaptive-fit-in/ Without a fit mode, Focal resizes and crops the image to fill the box exactly. `fit-in` scales the whole image inside the box instead, so it leaves space rather than cropping. `full-fit-in` uses the smaller dimension. `adaptive-fit-in` swaps width and height when that keeps more detail.
Size
Required/<width>x<height>/ 0 = proportional · orig = source dimension · a leading - flips that axis
Target box. `300x0` scales to 300 wide at the source ratio; `300xorig` keeps the source height; `-300x200` flips horizontally.
Alignment
Optional/<halign>/<valign>/ halign: left | center | right · valign: top | middle | bottom
Chooses which part of the image survives a crop to the box. Defaults to center and middle.
Filters
Optional/filters:<name>(<args>):<name>(<args>)/ Filters run left to right, in the order written. See the filter table below.
Source
Required/<url-encoded source path> The image path, relative to the project origin. URL-encode it if it contains a query string.
Filters
Filters run left to right, in the order written. Focal strips EXIF metadata from every image, including camera details and GPS location, whether or not you ask.
| Filter | Effect |
|---|---|
quality(<0-100>) | JPEG/WebP encoder quality. |
format(<webp|avif|jpeg|png|gif>) | Sets the output format. Without it, browsers that accept WebP get WebP and the rest get the source format. |
fill(<colour>[,<fill-transparent>]) | Fills the space `fit-in` leaves over, and optionally flattens transparency onto it. Takes a named colour or hex. |
blur(<radius>[,<sigma>]) | Gaussian blur. Useful for cheap placeholders. |
sharpen(<amount>,<radius>,<luminance-only>) | Unsharp mask. Worth applying after a large downscale. |
grayscale() | Removes colour. |
rotate(<0|90|180|270>) | Rotates by a fixed quarter turn. |
proportion(<0.0-1.0>) | Scales relative to the source size. |
strip_icc() | Drops the colour profile. Files get smaller, and colours can shift. |
upscale() | Allows `fit-in` to enlarge an image smaller than the box. |
Examples
Trim the background, fit to a box, serve WebP
/unsafe/trim:top-left:80/fit-in/300x300/filters:fill(white,1):quality(75):format(webp)/products/chair.jpgTrims uniform background from the top-left reference pixel at tolerance 80, scales the whole image inside a 300×300 box, fills the remaining space with white and flattens transparency onto it, then encodes WebP at quality 75. This is the shape we benchmarked against a commercial provider on a hundred real product images.
Fixed width, proportional height
/unsafe/800x0/filters:quality(80)/products/chair.jpgScales to 800px wide and lets the height follow the source ratio.
Square thumbnail, keeping the top of the image
/unsafe/200x200/center/top/filters:quality(70)/products/chair.jpgCrops to a square and keeps the top edge, which suits portraits and tall product shots.
Inspect without encoding
/unsafe/meta/300x300/products/chair.jpgReturns JSON describing the operation and the source dimensions. Nothing is encoded.