> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convertly.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Transforms
> CDN URL parameters for resize, crop, AI, watermarks, face and plate privacy, format negotiation, and delivery.
The CDN URL is the API. Any combination of parameters produces a deterministic URL with a stable cache key — same params, same cached bytes worldwide.
```
GET https://cdn.convertly.sh/{endpointNamespace}/{fileIdOrSlug}?w=600&h=400&q=auto&format=auto&fit=cover&gravity=auto
```
Each guide below opens with **live output examples**, then documents the params for that transform family.
Background removal, generative replace, object removal, text-to-image, and outpaint.
Single marks, tiled grids, blend modes, rotation, and anchor positions.
Face blur, face pixelation, license-plate redaction, and coordinate-based region privacy.
Width, height, aspect ratio, fit modes, and smart gravity crops.
Dynamic OG cards, badges, multiline text, stroke, and custom fonts.
Brightness, contrast, blur, sharpen, auto-enhance, and auto-compress.
Format negotiation, progressive JPEG, content-aware quality, client hints, and metadata stripping.
Force browser downloads with `dl` and Content-Disposition attachment headers.
Raster-to-SVG tracing and SVG input sanitization.
Padding, borders, rounded corners, alpha trim, and image masks.
Poster frames, clip trimming, transcode, and animated GIF output.
For focal-point workflows and `/api/images/analyze`, see [Smart cropping & image analysis](/docs/image-cdn/smart-cropping).
Parameter reference
### Size, crop, and focal
| Param | Value | Default |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `w` | Output width in pixels (16–4000). | source width |
| `h` | Output height in pixels (16–4000). | source height |
| `ar` (`aspect`) | Target aspect ratio when only one dimension is set. Accepts `16:9`, `3/2`, or a decimal like `1.5`. | — |
| `rect` | Source crop before resize: `x,y,w,h` in pixels or percentages. Named anchors: `left`, `center`, `right`, `top`, `middle`, `bottom`, `full`. | — |
| `dpr` | Device pixel ratio multiplier (`1`–`4`). `w=400&dpr=2` returns 800 physical pixels. | `1` |
| `fit` | `cover`, `contain`, `fill`, `inside`, `outside`. | `cover` |
| `gravity` (`g`) | `auto`, `smart`, `face`, `entropy`, `center`, compass corners. | `auto` |
| `fp` | Focal point `x,y` in `[0,1]` or percentages; `fp=auto` for inline detection. Stored analysis applies automatically when omitted. | — |
| `fp-z` (`fpZ`) | Focal zoom (`1`–`10`) — tighter crop around the focal point. | `1` |
| `fp-debug` | Draw a crosshair at the focal point. | `false` |
| `focal` | `json` — return focal metadata instead of an image. | — |
| `face-debug` | Draw detected face boxes while validating `gravity=face`. Use only during QA. | `false` |
| `crop` | Set to `smart` for content-aware crop. Same as `gravity=smart`. | — |
### Format and delivery
| Param | Value | Default |
| ----------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `q` | Output quality (`20`-`100`) or adaptive mode: `auto:eco`, `auto`, `auto:balanced`, `auto:best`. | `80` for raw URLs; SDK image adapters use `auto` |
| `format` (`f`) | `auto`, `webp`, `avif`, `jpeg`, `png`, `svg` (with `vectorize`). | `auto` |
| `jpgProgressive` | Progressive JPEG. Aliases: `jpeg-progressive`, `jpg-progressive`. | `1` for JPEG |
| `dl` (`download`) | Force download with `Content-Disposition: attachment`. Optional filename: `dl=hero.jpg`. | inline |
| `strip` | Metadata stripping: `all`, `icc`, or `1`. | preserve |
| `ch` | Client Hints sizing flags, e.g. `Width,Dpr`. | — |
| `preset` | Reference a [named preset](/docs/image-cdn/presets-and-signing#named-presets). | — |
| `s` | [HMAC signature](/docs/image-cdn/presets-and-signing#signed-urls) for gated content. | — |
See [Format & delivery](/docs/image-cdn/transforms/format-delivery) and [Download](/docs/image-cdn/transforms/format-download).
### Canvas, trim, and masks
| Param | Value | Default |
| ---------------------------------- | -------------------------------------------------------------------- | ----------- |
| `trim` (`trimAlpha`, `trim-alpha`) | Crop fully transparent borders. Accepts `1`, `true`, `yes`, or `on`. | `false` |
| `rotate` (`rot`) | Rotate by degrees (`-360` to `360`). | `0` |
| `flip` / `flop` | Vertical / horizontal mirror. | `false` |
| `bg` | Hex background for rotation/padding. Supports alpha. | transparent |
| `pad` | Equal padding around the image (`0`–`1000`). | `0` |
| `border` | Equal border (`0`–`400`). | `0` |
| `borderColor` | Hex border colour. Supports alpha. | `#000000` |
| `radius` (`r`) | Rounded-corner radius in pixels. | `0` |
| `mask` | Alpha mask from stored file ID or HTTPS URL. | — |
| `maskBg` | Background colour revealed through transparent mask areas. | — |
### Vector and SVG
| Param | Value | Default |
| --------------------- | -------------------------------------------------------------- | ----------- |
| `svgSanitize` | Strip unsafe markup from SVG sources. Aliases: `svg-sanitize`. | `1` for SVG |
| `vectorize` (`trace`) | Raster-to-SVG (`gradient` or `1`; use with `format=svg`). | — |
| `mono` | Single-colour trace when `vectorize` is enabled. | `false` |
| `svgColor` | Hex — recolour SVG fills/strokes before rasterize. | — |
See [Vector & SVG](/docs/image-cdn/transforms/vector-svg).
### Watermarks
| Param | Value | Default |
| ---------------------------------- | --------------------------------------------------------------- | ------------------ |
| `watermark` (`mark`) | Stored file ID or public HTTPS image URL. | — |
| `markW` | Watermark width in pixels. | 18% of image width |
| `markScale` (`mark-scale`) | Scale watermark to % of base width (`0`–`100`). | auto |
| `markRot` (`mark-rot`) | Rotate watermark counter-clockwise (`0`–`359`). | `0` |
| `markTile` (`mark-tile`) | Tile watermark. Valid value: `grid`. | single mark |
| `markOpacity` (`watermarkOpacity`) | Opacity (`0.05`–`1`). | `0.78` |
| `markPosition` | One of 7 anchor positions. | `bottom-right` |
| `markPad` | Margin from image edge. | `24` |
| `markBlend` | Compositing mode: `over`, `multiply`, `screen`, `overlay`, etc. | `over` |
See [Watermarks](/docs/image-cdn/transforms/watermarks).
### Text overlays
| Param | Value | Default |
| -------------- | ------------------------------------------------------------ | --------------- |
| `text` | URL-encoded text (max 500 chars). Use `%0A` for line breaks. | — |
| `textColor` | Hex colour for text. | `#ffffff` |
| `textSize` | Font size in pixels (8–256). | `48` |
| `textPosition` | One of 8 anchor positions. | `bottom-center` |
| `textFont` | `sans`, `serif`, `mono`, or aliases. | `sans` |
| `textAlign` | `left`, `center`, `right` for multiline text. | `center` |
| `textShadow` | Drop shadow as `dx,dy,blur,#color`. | none |
| `textBg` | Optional hex background pill behind text. | none |
See [Text overlays](/docs/image-cdn/transforms/text-overlays).
### Adjustments and effects
| Param | Value | Default |
| -------------------------- | ----------------------------------------------------------------- | ------- |
| `bri` (`brightness`) | Whole-image brightness (`0`–`200`, `100` = unchanged). | — |
| `con` (`contrast`) | Whole-image contrast (`0`–`200`). | — |
| `sat` (`saturation`) | Whole-image saturation (`0`–`200`). | — |
| `hue` | Hue rotation in degrees (`-180`–`180`). | — |
| `blur` | Gaussian blur on the full image (`0`–`100`). | — |
| `sharp` (`sharpen`, `usm`) | Unsharp mask strength (`0`–`100`). | — |
| `monochrome` | Hex — tint raster to one brand colour; preserves alpha. | — |
| `auto` | Comma-separated flags: `enhance`, `redeye`, `compress`, `format`. | — |
| `pixelate` (`px`) | Pixelate full image. `0` disables; `1`–`100` = block size. | `0` |
See [Adjustments & effects](/docs/image-cdn/transforms/adjustments).
### Face and plate privacy
| Param | Value | Default |
| ---------------- | --------------------------------------------------------------------------- | ------- |
| `blurFaces` | Blur detected faces. Accepts `1`, `true`, `yes`, or `on`. | `false` |
| `faceBlur` | Blur strength for `blurFaces` (`1`–`100`). | `32` |
| `faceBlurShape` | Mask shape: `round` (oval) or `square`. | `round` |
| `pixelateFaces` | Pixelate detected faces. | `false` |
| `facePixelate` | Pixel block size for `pixelateFaces` (`2`–`100`). | `16` |
| `blurPlates` | Blur detected license plates in image outputs. | `false` |
| `plateBlur` | Blur strength for `blurPlates` (`1`–`100`). | `40` |
| `pixelatePlates` | Pixelate detected license plates in images. | `false` |
| `platePixelate` | Pixel block size for `pixelatePlates` (`2`–`100`). | `14` |
| `plate-debug` | Draw detected plate boxes for testing. Use only while validating detection. | `false` |
| `blurRegion` | Blur explicit `x,y,w,h` output-pixel region. | — |
| `pixelateRegion` | Pixelate explicit `x,y,w,h` region. | — |
| `plateRegion` | Alias for license-plate blur region. | — |
| `regions` | Pipe-separated: `blur:…`, `pixelate:…`, `plate:…`. | — |
See [Face and plate privacy](/docs/image-cdn/transforms/face-privacy).
### Colour palette
| Param | Value | Default |
| --------- | ------------------------------------------------------------- | ------- |
| `palette` | `json` or `css` — return colour data instead of an image. | — |
| `colors` | Max swatches when `palette=json` or `palette=css` (`0`–`16`). | `6` |
| `prefix` | CSS class prefix when `palette=css`. | `image` |
See [Smart cropping & image analysis](/docs/image-cdn/smart-cropping#colour-palette-extraction).
### AI and ML
| Param | Value | Default |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `bgRemove` | ML background removal with alpha. | `false` |
| `blurFaces` / `pixelateFaces` | Automatic face privacy for image CDN outputs. | `false` |
| `blurPlates` / `pixelatePlates` | Automatic license-plate privacy for image CDN outputs. | `false` |
| `upscale` | Standard deterministic resampling and sharpening (`1`, `2`, or `4`; free). Forma AI detail recovery with `upscale=ai` (signed URL, Forma quota). | `false` |
| `bgReplace` | Forma background replacement prompt (signed URL). | — |
| `objectRemovalRect` | Forma object removal region `x,y,w,h` (signed URL). | — |
| `fill=gen` + `fillGenPrompt` | Forma generative outpaint (signed URL). | — |
| `ai=generate` + `aiPrompt` | Forma text-to-image (signed URL). | — |
See [Forma AI & ML](/docs/image-cdn/transforms/ai-ml).
### Video and documents
| Param | Value | Default |
| ---------------- | ------------------------------------------------ | ------- |
| `t` / `time` | Poster frame timestamp in seconds (video files). | `1` |
| `poster` | Set to `1` to extract a poster frame from video. | — |
| `so`, `du`, `eo` | Video clip start, duration, and end (seconds). | — |
| `page` | PDF page number (1-based). | — |
| `frame` | GIF frame index (0-based). | — |
See [Video transforms](/docs/image-cdn/transforms/video).
## How caching works
Every URL is deterministic. The endpoint sets long-lived immutable cache headers and varies on `Accept` and `Save-Data`:
```
Cache-Control: public, max-age=31536000, immutable, stale-while-revalidate=86400
Vary: Accept, Save-Data
```
Convertly uses two shared cache layers. A visitor-facing edge cache serves hot responses close to the requester. A persistent variant cache stores successful renders so a cold edge in another region can usually refill without re-encoding the source. Only a miss in both layers reaches the transform origin.
For a stable set of responsive image URLs, a 90-99% edge hit ratio is realistic after warm-up. Persistent variant hits further reduce transform-origin traffic when a regional edge is cold.
Responses expose cache diagnostics that work in a browser network panel or with `curl -I`:
| Header | Meaning |
| ------------------------------- | --------------------------------------------------------------- |
| `X-Convertly-CDN-Edge: hit` | Served from the visitor-facing edge cache. |
| `X-Convertly-CDN-Edge: variant` | Restored from the persistent variant cache without re-encoding. |
| `X-Convertly-CDN-Edge: miss` | Fetched or rendered at the transform origin. |
| `Cache-Status` | Standards-based equivalent of the cache state. |
| `Server-Timing` | CDN handling time for diagnostics. |
### Realistic cache ratios
The 95% number is achievable, not guaranteed. A few honest factors:
* **Edge caches are regional.** A globally popular image must warm at more than one edge. The persistent variant layer prevents most regional cold fills from repeating the original transform.
* **LRU eviction.** Edge caches evict less popular URLs under memory pressure. Long-tail content re-fetches more often than hot URLs.
* **Cache-busting URLs.** Anything like `?v=${Date.now()}` collapses the cache ratio to nearly zero. Use a content hash or an asset revision that changes only when the source bytes change.
* **Too many responsive widths.** Every unique width is a separate variant. Define a small width set that matches your layout instead of generating a new width for every device pixel value.
### What counts as a delivery
An origin request is a request that misses both Convertly cache layers and reaches the transform or source origin. These do **not** consume the origin-request allowance:
* Repeat hits served by an edge cache.
* Persistent variant hits used to refill a cold regional edge.
* Browser cache hits.
* Service worker cache hits.
The first request for a new `(file, canonical params, negotiated format)` variant normally counts. Later regional edge fills can reuse its persistent render. A request counts again only when both cache layers miss or a purge intentionally removes the reusable variant.