---
title: "Cloudflare Images - A new, consistent language across Images interfaces — Cloud Changelog"
description: "Cloudflare Images lets you dynamically compose, manipulate, and encode images using a broad set of optimizations, including resizing, face cropping, and b…"
url: "https://cloudchangelog.com/cloudflare/2026-11-18-consistent-optimization-interfaces"
updated: "2026-11-18"
---

[Back to feed](https://cloudchangelog.com/feed/2026-W47)

November 18, 2026 · Cloudflare

# Cloudflare Images - A new, consistent language across Images interfaces

- [Cloudflare Images](https://cloudchangelog.com/products/cloudflare/images)
- [Media, games and IoT](https://cloudchangelog.com/search?q=media-games-iot)

[Cloudflare Images](https://developers.cloudflare.com/images/) lets you dynamically compose, manipulate, and encode images using a broad set of optimizations, including [resizing](https://developers.cloudflare.com/images/optimization/features/#width--w), [face cropping](https://developers.cloudflare.com/images/optimization/features/#face), and [background removal](https://developers.cloudflare.com/images/optimization/features/#segment). You can configure optimizations directly in an image URL or programmatically through the [`cf.image` options](https://developers.cloudflare.com/images/optimization/transformations/transform-via-workers/) on a Worker [`fetch()` subrequest](https://developers.cloudflare.com/workers/runtime-apis/fetch/).

We redesigned the Images API to provide a consistent, predictable, and intuitive language for developers and AI agents to optimize and manipulate images.

Starting today, the URL interface and `cf.image` options in [Workers](https://developers.cloudflare.com/workers/) use the same parameter structure to [apply optimizations](https://developers.cloudflare.com/images/optimization/features/). A configurable optimization will have its corresponding settings nested underneath its top-level parameter. Existing syntax in URLs and Worker configurations continues to behave as before.

This release also makes adding [borders](https://developers.cloudflare.com/images/optimization/features/#border) and [overlays](https://developers.cloudflare.com/images/optimization/features/#draw) available in the URL interface. For example, you can now add a logo or text watermark directly in the URL instead of writing a Worker.

#### What changed

Optimization parameters are now represented in one of two ways: a compact form for single values and a structured form for related settings.

For example, `width=500` requests an exact width, while `trim=color` asks Images to automatically trim the sides of an image based on its border color. [Color-based trimming](https://developers.cloudflare.com/images/optimization/features/#trim-color) already supports configuring the border color, tolerance, and retained edge; these settings were previously applied as separate top-level parameters:

*Related `trim` settings appeared alongside independent parameters such as `width`.*

The new structure groups existing settings under a single top-level `trim` parameter:

*Related `trim` settings are nested, while `width=250` remains a top-level parameter.*

In the URL interface, color-based trimming uses the following syntax:

```
trim=(mode=color,color=red,tolerance=10,keep=5)
```

The same hierarchy maps directly to `cf.image` in Workers, where related values that were previously separate or inferred now live in the same object. The structured object uses `mode` to explicitly identify the selected behavior, while the remaining properties configure that behavior:

```
trim: {
	mode: "color",
	color: "white",
	tolerance: 10,
	keep: 5
}
```

#### A unified parameter model

In Images, optimizations are expressed as parameters, which form the language used to describe every optimization and its intended behavior. `width` sets the output width, `gravity` identifies the area that a crop should preserve, and `draw` defines how image or text overlays are rendered.

Many optimization features began as scalar parameters, pairing a parameter key with one value, such as `width=500`. As we introduced more capabilities, some parameters gained settings to configure how the optimization worked, such as [automatic width selection](https://developers.cloudflare.com/images/optimization/features/#widthauto). We added syntax to support each use case, gradually accumulating different forms for expressing related settings.

A given optimization might follow multiple conventions for different behaviors. For example, [color-based trimming](https://developers.cloudflare.com/images/optimization/features/#trim-color) relied on separate dotted parameters, while [side-based trimming](https://developers.cloudflare.com/images/optimization/features/#trim-side) encoded the top, right, bottom, and left settings as four unlabeled positional values:

```
trim=border,trim.border.color=white,trim.border.tolerance=10,trim.border.keep=5
trim=10;20;10;20
```

None of these forms were especially challenging in isolation. But together, they required developers to learn several parameter models and agents to infer the relationships between parameters and their settings to produce the correct syntax for each interface.

In the new structure, the Images API distinguishes between two core concepts: A **parameter** identifies an optimization feature, while a **setting** configures how that feature behaves.

The compact form continues to assign one value directly to a parameter. When an optimization has configurable behavior, the structured form organizes named settings, lists, and nested groups beneath the parameter, making the relationship between the optimization and its configuration explicit.

The unified parameter model follows these rules:

- **A parameter that needs one value uses the compact form.** When the relationship is unambiguous, existing forms like `width=500`, `width=auto` (with default settings), and `gravity=auto` continue to work with the same syntax.
- **A parameter with configurable behavior groups its settings beneath the top-level parameter.** When a parameter supports multiple behaviors, the `mode` setting identifies the selected behavior. Without `mode`, an expression such as `width=(desktop=1400)` would require Images to infer `auto` from the presence of `desktop`.
- **Across interfaces, groups and lists follow the same nesting rules.** A grouped URL parameter maps to an object in `cf.image`, while a URL list maps to an array. Previously, each feature needed a separate representation and translation rules for each interface. The shared hierarchy eliminates structural drift by using the same vocabulary and relationships in both interfaces.

For developers, a standard form for configuring parameters means fewer special-case conventions to remember and less translation between interfaces. Related settings stay together and a configuration expressed in a URL maps predictably to its `cf.image` object.

#### How this affects existing optimizations

The new structure is available for existing optimization features whose settings previously used separate top-level parameters, dotted names, or positional values. It also brings two previously Workers-only capabilities, borders and overlays, to the URL interface.

Use the new structured form to express the following optimizations and capabilities:

Optimization What it does What changed [`border`](https://developers.cloudflare.com/images/optimization/features/#border) Adds a border around the image. Now supported in the URL interface. Previously, this was available only in Workers. [`draw`](https://developers.cloudflare.com/images/optimization/features/#draw) Adds an image or text overlay to the source image. Now supported in the transformation URL interface for remote images. Previously, this was available only in Workers. [`gravity`](https://developers.cloudflare.com/images/optimization/features/#gravity) coordinates Sets the focal point using relative `x` and `y` coordinates. Uses named `x` and `y` settings in the URL interface. [`quality`](https://developers.cloudflare.com/images/optimization/features/#quality) Controls the compression quality of the output image. Groups the default quality and the quality for slow connections beneath `quality`. [`trim`](https://developers.cloudflare.com/images/optimization/features/#trim) Removes pixels around the sides of an image. Uses named settings beneath `trim` for individual sides, rectangular areas, and border-color detection. [`upscale`](https://developers.cloudflare.com/images/optimization/features/#upscale) Controls the algorithm used when an image is enlarged. Configured as the `upscale` setting beneath [`fit`](https://developers.cloudflare.com/images/optimization/features/#fit), alongside the selected mode. [`width=auto`](https://developers.cloudflare.com/images/optimization/features/#width) Automatically selects an appropriate output width using available information about the browser and device. Uses named settings under the `width` parameter for mobile, desktop, and breakpoint widths.

These structured forms are additive. Earlier forms, including `gravity=0.5x0.3`, dotted `trim` parameters, and separate top-level parameters continue to work.

Refer to [Features](https://developers.cloudflare.com/images/optimization/features/) for the complete reference of optimization features.

Free. Unsubscribe any time.

[Read on developers.cloudflare.com](https://developers.cloudflare.com/changelog/post/2026-11-18-consistent-optimization-interfaces/)

## Related updates

- Jun 16, 2026

  [Cloudflare Images - New optimization features in Images](https://cloudchangelog.com/cloudflare/2026-06-16-new-optimization-features)
- Feb 24, 2025

  [Cloudflare Images - Bind the Images API to your Worker](https://cloudchangelog.com/cloudflare/2025-02-21-images-bindings-in-workers)
- Sep 2, 2026

  [Cloudflare Images - New in Images: text rasterization and updates to the binding](https://cloudchangelog.com/cloudflare/2026-09-02-images-binding-updates)
- Jun 10, 2026

  [Cloudflare Images - Manage hosted images with the Images binding](https://cloudchangelog.com/cloudflare/2026-06-10-hosted-images-binding)
- Nov 17, 2026

  [Cloudflare Images - Optimize original TIFF files with Images](https://cloudchangelog.com/cloudflare/2026-11-17-tiff-input-support)

[All Cloudflare Images changes](https://cloudchangelog.com/products/cloudflare/images)

## Contact

- [YouTube](https://www.youtube.com/@cloudchangelog)
