-```
-
-## Enable transformations on your zone
-
-You can dynamically optimize images that are stored outside of Cloudflare Images and deliver them using [transformation URLs](/images/transform-images/transform-via-url/).
-
-Cloudflare will automatically cache every transformed image on our global network so that you store only the original image at your origin.
-
-To enable transformations on your zone:
-
-1. In the Cloudflare dashboard, go to the **Transformations** page.
-
-
-
-2. Go to the specific zone where you want to enable transformations.
-3. Select **Enable for zone**. This will allow you to optimize and deliver remote images.
-
-:::note
-
-With **Resize images from any origin** unchecked, only the initial URL passed will be checked. Any redirect returned will be followed, including if it leaves the zone, and the resulting image will be transformed.
-
-:::
-
-:::note
-
-If you are using transformations in a Worker, you need to include the appropriate logic in your Worker code to prevent resizing images from any origin. Unchecking this option in the dash does not apply to transformation requests coming from Cloudflare Workers.
-
-:::
diff --git a/src/content/docs/images/get-started/index.mdx b/src/content/docs/images/get-started/index.mdx
new file mode 100644
index 00000000000..76097906b17
--- /dev/null
+++ b/src/content/docs/images/get-started/index.mdx
@@ -0,0 +1,12 @@
+---
+pcx_content_type: navigation
+title: Get started
+sidebar:
+ order: 1
+ group:
+ hideIndex: true
+---
+
+import { DirectoryListing } from "~/components";
+
+
diff --git a/src/content/docs/images/get-started/introduction.mdx b/src/content/docs/images/get-started/introduction.mdx
new file mode 100644
index 00000000000..d859325ce83
--- /dev/null
+++ b/src/content/docs/images/get-started/introduction.mdx
@@ -0,0 +1,57 @@
+---
+pcx_content_type: concept
+title: Introduction
+sidebar:
+ order: 1
+---
+
+import { Render } from "~/components";
+
+Cloudflare provides a platform for building and scaling media applications with Images. On this page, we'll answer the following questions:
+
+- Why optimize images?
+- How do I get started with Images?
+- Should I store with Images or R2?
+
+---
+
+## Why optimize images?
+
+Loading images in their original resolution and format quickly becomes a bottleneck for app performance — especially on mobile.
+
+Meanwhile, creating and storing multiple versions of the same image adds complexity and overhead, along with storage costs.
+
+When you serve large amounts of media, image optimization provides:
+
+- **Streamlined infrastructure** — Simplify your workflow and reduce infrastructure costs by dynamically generating optimized versions on request.
+- **Smaller file sizes** — Automatically deliver images in modern formats like AVIF and WebP, which improves page speed and lowers bandwidth.
+- **Responsive sizing** — Crop and resize for any use case, from square thumbnails to landscape banners, using the same original image in storage.
+- **Visual effects** — Apply blur, overlays, background fills, and more at the edge.
+
+## How do I get started with Images?
+
+There are two ways to use Images, depending on where your images are stored:
+
+### Optimize remote images
+
+Keep your images on your own origin, in [R2](/r2), or with any storage provider. Cloudflare pulls the original image, applies optimizations at the edge, and caches the optimized image.
+
+You can define an [origin allowlist](/images/optimization/transformations/sources/) to control which source images can be transformed on your zone.
+
+To start, [enable transformations on your zone](/images/optimization/transformations/overview/).
+
+### Upload and deliver with Images
+
+Store, optimize, and deliver images globally with zero infrastructure management.
+
+If your app centers around user-uploaded content, then you can use the [Direct Creator Upload API](/images/storage/upload-images/direct-creator-upload/) to securely accept images directly from your users.
+
+To start, set up [predefined variants](/images/optimization/hosted-images/create-variants/) to configure how hosted images should be served.
+
+## Should I store with Images or R2?
+
+**Store in [R2](/r2/) and use Images for transformations** if you want to build your own custom image pipeline or need fine-grained control over storage, such as [bucket-level access management](/r2/buckets/) or [object lifecycle rules](/r2/buckets/object-lifecycles/). This is typically the most cost-effective approach for image optimization.
+
+**Store in Images** if you want a fully managed solution with the least configuration. Our built-in features include a [shared delivery domain](/images/optimization/hosted-images/serve-uploaded-images/), [predefined variants](/images/optimization/hosted-images/create-variants/), and automatic cache invalidation when you update original images in storage.
+
+Each use case has a separate pricing model. To learn more, refer to [Pricing](/images/pricing/).
diff --git a/src/content/docs/images/get-started/key-concepts.mdx b/src/content/docs/images/get-started/key-concepts.mdx
new file mode 100644
index 00000000000..1df41d96ff9
--- /dev/null
+++ b/src/content/docs/images/get-started/key-concepts.mdx
@@ -0,0 +1,17 @@
+---
+pcx_content_type: concept
+title: Key concepts
+sidebar:
+ order: 2
+---
+
+Here is a summary of the key terms that we use throughout our guides.
+
+| Term | What this means |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Remote image | An image that is stored outside of Images storage, including images in [R2](/r2/). |
+| Transformation | A request to optimize a remote image that is stored outside of Images. |
+| Origin | The location where your image is stored.
When you optimize a remote image, Cloudflare will pull the original image from the origin and store it in cache.
|
+| Hosted image | An image that is stored in Images.
Cloudflare dynamically serves copies of your original image, optimized based on your requirements.
|
+| Parameter / Option | A parameter is a type of optimization that you can perform on an image.
An option is the value for the parameter.
For example, you can set the `width` parameter to a value of `100` to resize an image to a width of 100.
|
+| Variant | A predefined way to specify how a hosted image should be resized.
For example, you can create a variant called "thumbnail" that sets image dimensions to 100x100.
When you serve images with this variant, Cloudflare will serve a version of the original image that is resized to 100x100.
Predefined variants specify a limited set of parameters: `width`, `height`, `fit`, and `blur`.
|
diff --git a/src/content/docs/images/get-started/limits.mdx b/src/content/docs/images/get-started/limits.mdx
new file mode 100644
index 00000000000..63bc3f69f6d
--- /dev/null
+++ b/src/content/docs/images/get-started/limits.mdx
@@ -0,0 +1,113 @@
+---
+pcx_content_type: reference
+title: Limits and formats
+sidebar:
+ order: 3
+---
+
+This section covers limits and supported formats for Images.
+
+---
+
+## Limits
+
+Here are limits to keep in mind when optimizing with Images.
+
+On an Enterprise plan, you can reach out to our account team to ensure that the limits align with your needs.
+
+### Remote images
+
+The following limits apply when transforming a remote image stored outside of Images:
+
+| Attribute | Limit |
+| ---------------------------------------- | ---------------------------------- |
+| Image file size | 100 MB |
+| Image area, excluding animated GIFs | 100 MP (e.g. 10,000x10,000 pixels) |
+| Image area for animated GIFs | 100 MP\* |
+| Image dimension, excluding WebP and AVIF | 12,000 pixels |
+| Image dimension, AVIF | 1,200 pixels |
+
+### Hosted images
+
+The following limits apply when uploading to your Images storage:
+
+| Attribute | Limit |
+| ---------------------------------------- | ---------------------------------- |
+| Image file size | 10 MB |
+| Image area, excluding animated GIFs | 100 MP (e.g. 10,000x10,000 pixels) |
+| Image area, animated GIFs | 100 MP\* |
+| Image dimension, excluding WebP and AVIF | 12,000 pixels |
+| Image dimension, AVIF | 1,200 pixels |
+| Image metadata | 1024 bytes |
+
+### Limits for animated images
+
+GIF/WebP animations are limited to the total megapixels across all frames, or the sum of areas of all frames. For example, a GIF with 500x500 dimensions and 10 frames has an image area of 2,500,000 pixels or 2.5 megapixels.
+
+The limit to deliver an animated GIF/WebP animation is 100 megapixels. However, any animations over 50 megapixels will be delivered without applying any transformations.
+
+When serving animations, we recommend using video formats like MP4 and WebM for best performance. As the GIF format has inefficient compression, high resolution animations typically have larger file sizes and take longer to compress.
+
+To optimize remote videos, you can use [media transformations](https://developers.cloudflare.com/stream/transform-videos/).
+
+## Supported formats
+
+### Input formats
+
+Images supports a wide range of input formats for both remote and hosted images:
+
+- PNG
+- JPEG
+- GIF (including animations)
+- WebP (including animations)
+- SVG
+- AVIF\*
+- HEIC
+
+\*Available on an Enterprise plan.
+
+### Output formats
+
+You can serve images in the following output formats:
+
+- PNG
+- JPEG
+- GIF (including animations)
+- WebP (including animations)
+- SVG
+- AVIF
+
+When detecting the most optimal output format for the requesting browser, Cloudflare balances the time to generate an image with the time to serve the image to the browser.
+
+In particular, AVIF encoding can be an order of magnitude slower than encoding to other formats. If the image is too large to be quickly encoded to AVIF, then Cloudflare will fall back to WebP or JPEG.
+
+### Progressive JPEG
+
+When transcoding to JPEG, Cloudflare generates images in an interlaced progressive JPEG format.
+
+You can use the [`format`](/images/optimization/features/#format) parameter to specify whether progressive or baseline JPEG should be used.
+
+However, we will always fall back to the baseline JPEG format — even when progressive JPEG is specified — if either:
+
+- The output image area dimensions are less than 50x50.
+- The output image area dimensions are greater than 3000x3000.
+
+### SVG
+
+Cloudflare does not resize SVG files and will ignore any optimization parameters.
+
+If you store in Images, then you can use any predefined variant as a placeholder to deliver a sanitized SVG. For example, applying the default public variant allows the SVG to be delivered without resizing or cropping:
+
+`imagedelivery.net/account_hash/svg_id/public`
+
+Similarly, you can use Images to serve a sanitized SVG that is stored in your own origin, like in [R2](/r2/).
+
+When SVG files are served, they are sanitized using [`svg-hush`](https://github.com/cloudflare/svg-hush), an open-source tool developed by Cloudflare to make SVGs as safe as possible. It streams the files without buffering, enabling us to quickly filter them on the fly. SVG files are XML documents and can contain links or Javascript features that may pose a security concern.
+
+The `svg-hush` tool filters SVGs and removes potentially risky features, such as:
+
+- Scripting. We prevent SVGs from being used for cross-site scripting attacks. Although browsers do not allow scripts in `![]()
` tags, they do allow scripting when SVGs are opened directly as a top-level document.
+- Hyperlinks to other documents. Removing hyperlinking makes
+ SVG files less attractive for SEO spam and phishing.
+- References to cross-origin resources. We stop third parties
+ from tracking who is viewing the image.
diff --git a/src/content/docs/images/images-api.mdx b/src/content/docs/images/images-api.mdx
index 9ccfe01ac8a..f1113f6b5b0 100644
--- a/src/content/docs/images/images-api.mdx
+++ b/src/content/docs/images/images-api.mdx
@@ -4,5 +4,4 @@ title: Images API Reference
external_link: /api/resources/images/subresources/v1/methods/list/
sidebar:
order: 8
-
---
diff --git a/src/content/docs/images/index.mdx b/src/content/docs/images/index.mdx
index f8069c95ce5..17986394d4c 100644
--- a/src/content/docs/images/index.mdx
+++ b/src/content/docs/images/index.mdx
@@ -1,7 +1,7 @@
---
-title: Cloudflare Images
+title: Images
pcx_content_type: overview
-description: Streamline your image infrastructure with Cloudflare Images. Store, transform, and deliver images efficiently using Cloudflare's global network.
+description: Images is a platform for creating scalable and reliable image pipelines, designed to help developers deploy media-rich applications faster.
sidebar:
order: 1
head:
@@ -9,63 +9,114 @@ head:
content: Overview
---
-import { CardGrid, Description, Feature, LinkTitleCard, Plan } from "~/components"
+import {
+ CardGrid,
+ Description,
+ Feature,
+ LinkCard,
+ LinkTitleCard,
+ Plan,
+} from "~/components";
-
-Store, transform, optimize, and deliver images at scale
+ Create scalable and reliable image pipelines without managing complex infrastructure.
-
+
-Cloudflare Images provides an end-to-end solution designed to help you streamline your image infrastructure from a single API and runs on [Cloudflare's global network](https://www.cloudflare.com/network/).
+Images is designed to help developers deploy media-rich applications faster.
-There are two different ways to use Images:
+With Images, you can dynamically resize, optimize, and manipulate images at Cloudflare's edge to serve the optimal version for each user in real time — without manually creating or storing multiple copies of the same image for different use cases, browsers, or device breakpoints.
-- **Efficiently store and deliver images.** You can upload images into Cloudflare Images and dynamically deliver multiple variants of the same original image.
-- **Optimize images that are stored outside of Images** You can make transformation requests to optimize any publicly available image on the Internet.
+
-Cloudflare Images is available on both [Free and Paid plans](/images/pricing/). By default, all users have access to the Images Free plan, which includes limited usage of the transformations feature to optimize images in remote sources.
+## Get started
-:::note[Image Resizing is now available as transformations]
+Cloudflare offers two integration paths for Images:
-All Image Resizing features are available as transformations with Images. Each unique transformation is billed only once per calendar month.
+
+
+
+
-If you are using a legacy plan with Image Resizing, visit the [dashboard](https://dash.cloudflare.com/) to switch to an Images plan.
+If you’re new to Images, start here to learn the essentials:
-:::
+- Understand how [image optimization](/images/get-started/introduction/) improves your user experience and website performance.
+- Familiarize yourself with the [terminology](/images/get-started/key-concepts/) used through our documentation.
+- Read about the [limits and supported formats](/images/optimization/features/) for image inputs and outputs.
-***
+---
## Features
-
-Use Cloudflare’s edge network to store your images.
-
-
+
+ Browse the various features for compressing, cropping, resizing, and manipulating images.
-
-Accept uploads directly and securely from your users by generating a one-time token.
+
+ Learn how Images can streamline uploads in your image pipeline.
-
-Add up to 100 variants to specify how images should be resized for various use cases.
+
+ Create predefined variants to specify how a hosted image should be resized on
+ request.
-
-Control access to your images by using signed URL tokens.
-
-
-***
+---
## More resources
-
-
-
-Engage with other users and the Images team on Cloudflare support forum.
-
-
+
+ Learn about Images pricing.
+
+
+
+ Engage with other users and the Images team on Community forum.
+
+
+
+ Ask questions, show what you're building, and discuss the platform with other developers.
+
+
+
+ Follow @CloudflareDev on Twitter to learn about product announcements from the Developer Platform.
+
+
diff --git a/src/content/docs/images/manage-images/index.mdx b/src/content/docs/images/manage-images/index.mdx
deleted file mode 100644
index 7d68a6147c2..00000000000
--- a/src/content/docs/images/manage-images/index.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-pcx_content_type: navigation
-title: Manage uploaded images
-sidebar:
- order: 4
- group:
- hideIndex: true
-
----
-
-import { DirectoryListing } from "~/components"
-
-
\ No newline at end of file
diff --git a/src/content/docs/images/manage-images/serve-images/index.mdx b/src/content/docs/images/manage-images/serve-images/index.mdx
deleted file mode 100644
index 6be1fb85934..00000000000
--- a/src/content/docs/images/manage-images/serve-images/index.mdx
+++ /dev/null
@@ -1,12 +0,0 @@
----
-pcx_content_type: concept
-title: Serve images
-sidebar:
- order: 15
- group:
- hideIndex: true
----
-
-import { DirectoryListing } from "~/components"
-
-
\ No newline at end of file
diff --git a/src/content/docs/images/optimization/features.mdx b/src/content/docs/images/optimization/features.mdx
new file mode 100644
index 00000000000..a75798447e0
--- /dev/null
+++ b/src/content/docs/images/optimization/features.mdx
@@ -0,0 +1,136 @@
+---
+pcx_content_type: concept
+title: Features
+sidebar:
+ order: 1
+---
+
+import { Details, Render, Tabs, TabItem } from "~/components";
+
+Cloudflare enables developers to optimize images at scale by dynamically generating different versions in real time.
+
+The guide describes all of the parameters that can be used to resize, crop, manipulate, and apply visual effects to images.
+
+## How to apply optimization
+
+Use Cloudflare's image optimization capabilities through:
+
+- **URL interface** — Apply parameters directly in the image URL to specify how images should be optimized when served to the browser.
+- **Workers** — Bind the Images API directly to your Worker or set the `cf.image` options on a `fetch` subrequest to build programmatic image workflows.
+
+### URL interface
+
+Cloudflare uses a different URL structure depending on whether you are optimizing a [remote](/images/optimization/transformations/overview/) or a [hosted](/images/optimization/hosted-images/serve-uploaded-images/) image:
+
+
+
+ When optimizing images outside of Images, the default transformation URL uses the following structure:
+
+ ```txt
+ https:///cdn-cgi/image//
+ ```
+
+
+
+
+
+
+
+ For images stored in Cloudflare Images, use the delivery URL with a variant or custom options:
+
+ ```txt
+ https://imagedelivery.net///
+ ```
+
+
+
+
+
+
+
+
+### Workers
+
+When using [Images with Workers](/images/optimization/transformations/transform-via-workers/), you can:
+
+- Apply custom logic to set the order for optimization operations. For example, by default, Images will apply `flip` before `rotate`; instead, you can use the Images binding to customize your optimization workflow to rotate the image before flipping it.
+- Use a custom URL scheme instead of the default URL structure.
+- Implement content negotiation to dynamically adapt image size, format, and quality based on the device and network condition.
+
+---
+
+## Parameters
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+## Recommended image sizes
+
+Ideally, image sizes should match the exact size that they are displayed on the page. If the page contains thumbnails with markup such as `![]()
`, then images should be resized to `width=200`.
+
+To [serve responsive images](/images/optimization/make-responsive-images/), you can use the HTML `srcset` attribute to let the provider pick the most optimal size. If you can't use the `![]()
` markup and have to hardcode specific maximum sizes, Cloudflare recommends the following sizes:
+
+- Maximum of 1920 pixels for desktop browsers.
+- Maximum of 960 pixels for tablets.
+- Maximum of 640 pixels for mobile phones.
+
+For example, `fit=scale-down,width=1920` sets a maximum size of 1920 px and ensures that the image will not be enlarged unnecessarily.
+
+You can detect device type by enabling the `CF-Device-Type` header [via Cache Rule](/cache/how-to/cache-rules/examples/cache-device-type/).
+
+## Caching
+
+When you optimize with Images, the original image will be fetched from the origin server and cached — following the usual rules of HTTP caching, `Cache-Control` header, etc.. Requests for multiple different image sizes are likely to reuse the cached original image without causing extra transfers from the origin server.
+
+If [Custom Cache Keys](/cache/how-to/cache-keys/) are used for the origin image, the origin image might not be cached and might result in more calls to the origin.
+
+Optimized images follow the same caching rules as the original image they were resized from, except the minimum cache time is one hour. If you need images to be updated more frequently, add `must-revalidate` to the `Cache-Control` header. The Images service supports cache revalidation, so we recommend serving images with the `Etag` header. Refer to the [Cache docs for more information](/cache/concepts/cache-control/#revalidation).
+
+Cloudflare does not support purging optimized images individually. URLs starting with `/cdn-cgi/` cannot be purged. However, purging of the original image's URL will also purge all of its optimized versions.
diff --git a/src/content/docs/images/manage-images/blur-variants.mdx b/src/content/docs/images/optimization/hosted-images/blur-variants.mdx
similarity index 72%
rename from src/content/docs/images/manage-images/blur-variants.mdx
rename to src/content/docs/images/optimization/hosted-images/blur-variants.mdx
index 1a26cf89dff..e375c1e5ba2 100644
--- a/src/content/docs/images/manage-images/blur-variants.mdx
+++ b/src/content/docs/images/optimization/hosted-images/blur-variants.mdx
@@ -9,11 +9,11 @@ import { DashButton } from "~/components";
You can apply blur to image variants by creating a specific variant for this effect first or by editing a previously created variant. Note that you cannot blur an SVG file.
-Refer to [Resize images](/images/manage-images/create-variants/) for help creating variants. You can also refer to the API to learn how to use blur using flexible variants.
+Refer to [Resize images](/images/optimization/hosted-images/create-variants/) for help creating variants. You can also refer to the API to learn how to use blur using flexible variants.
To blur an image:
-1. In the Cloudflare dashboard, got to the **Hosted Images** page.
+1. In the Cloudflare dashboard, go to the **Hosted Images** page.
diff --git a/src/content/docs/images/manage-images/browser-ttl.mdx b/src/content/docs/images/optimization/hosted-images/browser-ttl.mdx
similarity index 94%
rename from src/content/docs/images/manage-images/browser-ttl.mdx
rename to src/content/docs/images/optimization/hosted-images/browser-ttl.mdx
index 7c0ca35555d..93980ca5f45 100644
--- a/src/content/docs/images/manage-images/browser-ttl.mdx
+++ b/src/content/docs/images/optimization/hosted-images/browser-ttl.mdx
@@ -3,14 +3,13 @@ pcx_content_type: concept
title: Browser TTL
sidebar:
order: 18
-
---
Browser TTL controls how long an image stays in a browser's cache and specifically configures the `cache-control` response header.
### Default TTL
-By default, an image's TTL is set to two days to meet user needs, such as re-uploading an image under the same [Custom ID](/images/upload-images/upload-custom-path/).
+By default, an image's TTL is set to two days to meet user needs, such as re-uploading an image under the same [Custom ID](/images/storage/upload-images/upload-custom-path/).
## Custom setting
@@ -52,8 +51,6 @@ When the Browser TTL is set to one day for images requested with this variant, t
:::note
-
-[Private images](/images/manage-images/serve-images/serve-private-images/) do not respect default or custom TTL settings. The private images cache time is set according to the expiration time and can be as short as one hour.
-
+[Private images](/images/optimization/hosted-images/serve-private-images/) do not respect default or custom TTL settings. The private images cache time is set according to the expiration time and can be as short as one hour.
:::
diff --git a/src/content/docs/images/manage-images/create-variants.mdx b/src/content/docs/images/optimization/hosted-images/create-variants.mdx
similarity index 94%
rename from src/content/docs/images/manage-images/create-variants.mdx
rename to src/content/docs/images/optimization/hosted-images/create-variants.mdx
index 49e776d98b8..e543c3adbfb 100644
--- a/src/content/docs/images/manage-images/create-variants.mdx
+++ b/src/content/docs/images/optimization/hosted-images/create-variants.mdx
@@ -1,6 +1,6 @@
---
pcx_content_type: how-to
-title: Create variants
+title: Create predefined variants
sidebar:
order: 10
---
@@ -15,7 +15,7 @@ Cloudflare Images can deliver SVG files but will not resize them because it is a
Resize via the Cloudflare dashboard.
:::
-1. In the Cloudflare dashboard, got to the **Hosted Images** page.
+1. In the Cloudflare dashboard, go to the **Hosted Images** page.
@@ -57,4 +57,4 @@ Variants allow you to choose what to do with your image’s metadata information
## Public access
-When the **Always allow public access** option is selected, particular variants will always be publicly accessible, even when images are made private through the use of [signed URLs](/images/manage-images/serve-images/serve-private-images).
+When the **Always allow public access** option is selected, particular variants will always be publicly accessible, even when images are made private through the use of [signed URLs](/images/optimization/hosted-images/serve-private-images/).
diff --git a/src/content/docs/images/manage-images/delete-variants.mdx b/src/content/docs/images/optimization/hosted-images/delete-variants.mdx
similarity index 87%
rename from src/content/docs/images/manage-images/delete-variants.mdx
rename to src/content/docs/images/optimization/hosted-images/delete-variants.mdx
index dad2bafbf56..d2c1ebdec20 100644
--- a/src/content/docs/images/manage-images/delete-variants.mdx
+++ b/src/content/docs/images/optimization/hosted-images/delete-variants.mdx
@@ -17,7 +17,7 @@ Deleting a variant is a global action that will affect other images that contain
## Delete variants via the Cloudflare dashboard
-1. In the Cloudflare dashboard, got to the **Hosted Images** page.
+1. In the Cloudflare dashboard, go to the **Hosted Images** page.
@@ -30,7 +30,7 @@ Deleting a variant is a global action that will affect other images that contain
Make a `DELETE` request to the delete variant endpoint.
```bash
-curl --request DELETE https://api.cloudflare.com/client/v4/account/{account_id}/images/v1/variants/{variant_name} \
+curl --request DELETE https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/variants/{variant_name} \
--header "Authorization: Bearer "
```
diff --git a/src/content/docs/images/manage-images/enable-flexible-variants.mdx b/src/content/docs/images/optimization/hosted-images/enable-flexible-variants.mdx
similarity index 78%
rename from src/content/docs/images/manage-images/enable-flexible-variants.mdx
rename to src/content/docs/images/optimization/hosted-images/enable-flexible-variants.mdx
index 122019d677e..7ca9fcba2ac 100644
--- a/src/content/docs/images/manage-images/enable-flexible-variants.mdx
+++ b/src/content/docs/images/optimization/hosted-images/enable-flexible-variants.mdx
@@ -11,7 +11,7 @@ Flexible variants allow you to create variants with dynamic resizing which can p
## Enable flexible variants via the Cloudflare dashboard
-1. In the Cloudflare dashboard, got to the **Hosted Images** page.
+1. In the Cloudflare dashboard, go to the **Hosted Images** page.
@@ -30,12 +30,12 @@ curl --request PATCH https://api.cloudflare.com/client/v4/accounts/{account_id}/
--data '{"flexible_variants": true}'
```
-After activation, you can use [transformation parameters](/images/transform-images/transform-via-url/#options) on any Cloudflare image. For example,
+After activation, you can use [optimization parameters](/images/optimization/features/#parameters) on any Cloudflare image. For example,
`https://imagedelivery.net/{account_hash}/{image_id}/w=400,sharpen=3`
:::note
-Flexible variants cannot be used for images that require a [signed delivery URL](/images/manage-images/serve-images/serve-private-images).
+Flexible variants cannot be used for images that require a [signed delivery URL](/images/optimization/hosted-images/serve-private-images/).
:::
diff --git a/src/content/docs/images/optimization/hosted-images/index.mdx b/src/content/docs/images/optimization/hosted-images/index.mdx
new file mode 100644
index 00000000000..be0c4f37f7e
--- /dev/null
+++ b/src/content/docs/images/optimization/hosted-images/index.mdx
@@ -0,0 +1,12 @@
+---
+pcx_content_type: navigation
+title: Hosted images
+sidebar:
+ order: 3
+ group:
+ hideIndex: true
+---
+
+import { DirectoryListing } from "~/components";
+
+
diff --git a/src/content/docs/images/manage-images/serve-images/serve-from-custom-domains.mdx b/src/content/docs/images/optimization/hosted-images/serve-from-custom-domains.mdx
similarity index 94%
rename from src/content/docs/images/manage-images/serve-images/serve-from-custom-domains.mdx
rename to src/content/docs/images/optimization/hosted-images/serve-from-custom-domains.mdx
index 2b2ab28b317..33fa85f5ab0 100644
--- a/src/content/docs/images/manage-images/serve-images/serve-from-custom-domains.mdx
+++ b/src/content/docs/images/optimization/hosted-images/serve-from-custom-domains.mdx
@@ -4,6 +4,7 @@ title: Serve images from custom domains
sidebar:
order: 22
---
+
import { DashButton } from "~/components";
Image delivery is supported from all customer domains under the same Cloudflare account. To serve images through custom domains, an image URL should be adjusted to the following format:
@@ -28,7 +29,7 @@ In this example, ``, `` and `` are the sam
## Custom paths
-By default, Images are served from the `/cdn-cgi/imagedelivery/` path. You can use Transform Rules to rewrite URLs and serve images from custom paths.
+By default, Images are served from the `/cdn-cgi/imagedelivery/` path. You can use [Transform Rules](/rules/transform/) to rewrite URLs and serve images from custom paths.
### Basic version
@@ -50,7 +51,6 @@ To create a rule:
```
4. Under **Then rewrite the path and/or query** > **Path**, enter the following values (using your account hash):
-
- **Target path**: [`/`] `images/*`
- **Rewrite to**: [`/`] `cdn-cgi/imagedelivery//${1}`
@@ -86,4 +86,4 @@ regex_replace(
## Limitations
-When using a custom domain, it is not possible to directly set up WAF rules that act on requests hitting the `/cdn-cgi/imagedelivery/` path. If you need to set up WAF rules, you can use a Cloudflare Worker to access your images and a Route using your domain to execute the worker. For an example worker, refer to [Serve private images using signed URL tokens](/images/manage-images/serve-images/serve-private-images/).
+When using a custom domain, it is not possible to directly set up WAF rules that act on requests hitting the `/cdn-cgi/imagedelivery/` path. If you need to set up WAF rules, you can use a Cloudflare Worker to access your images and a Route using your domain to execute the worker. For an example worker, refer to [Serve private images using signed URL tokens](/images/optimization/hosted-images/serve-private-images/).
diff --git a/src/content/docs/images/manage-images/serve-images/serve-private-images.mdx b/src/content/docs/images/optimization/hosted-images/serve-private-images.mdx
similarity index 100%
rename from src/content/docs/images/manage-images/serve-images/serve-private-images.mdx
rename to src/content/docs/images/optimization/hosted-images/serve-private-images.mdx
diff --git a/src/content/docs/images/manage-images/serve-images/serve-uploaded-images.mdx b/src/content/docs/images/optimization/hosted-images/serve-uploaded-images.mdx
similarity index 82%
rename from src/content/docs/images/manage-images/serve-images/serve-uploaded-images.mdx
rename to src/content/docs/images/optimization/hosted-images/serve-uploaded-images.mdx
index 0f35dd4b628..06ca1c75501 100644
--- a/src/content/docs/images/manage-images/serve-images/serve-uploaded-images.mdx
+++ b/src/content/docs/images/optimization/hosted-images/serve-uploaded-images.mdx
@@ -2,15 +2,14 @@
pcx_content_type: how-to
title: Serve uploaded images
sidebar:
- order: 21
-
+ order: 1
---
To serve images uploaded to Cloudflare Images, you must have:
-* Your Images account hash
-* Image ID
-* Variant or flexible variant name
+- Your Images account hash
+- Image ID
+- Variant or flexible variant name
Assuming you have at least one image uploaded to Images, you will find the basic URL format from the Images dashboard under Developer Resources.
@@ -26,9 +25,9 @@ You can select **Preview** next to the image you want to serve to preview the im
In this example:
-* `ZWd9g1K7eljCn_KDTu_MWA` is the Images account hash.
-* `083eb7b2-5392-4565-b69e-aff66acddd00` is the image ID. You can also use Custom IDs instead of the generated ID.
-* `public` is the variant name.
+- `ZWd9g1K7eljCn_KDTu_MWA` is the Images account hash.
+- `083eb7b2-5392-4565-b69e-aff66acddd00` is the image ID. You can also use Custom IDs instead of the generated ID.
+- `public` is the variant name.
When a user requests an image, Cloudflare Images chooses the optimal format, which is determined by client headers and the image type.
@@ -36,4 +35,4 @@ When a user requests an image, Cloudflare Images chooses the optimal format, whi
Cloudflare Images automatically transcodes uploaded PNG, JPEG and GIF files to the more efficient AVIF and WebP formats. This happens whenever the customer browser supports them. If the browser does not support AVIF, Cloudflare Images will fall back to WebP. If there is no support for WebP, then Cloudflare Images will serve compressed files in the original format.
-Uploaded SVG files are served as [sanitized SVGs](/images/upload-images/).
+Uploaded SVG files are served as [sanitized SVGs](/images/get-started/limits/#svg).
diff --git a/src/content/docs/images/optimization/index.mdx b/src/content/docs/images/optimization/index.mdx
new file mode 100644
index 00000000000..d55bbaa8cf7
--- /dev/null
+++ b/src/content/docs/images/optimization/index.mdx
@@ -0,0 +1,12 @@
+---
+pcx_content_type: navigation
+title: Optimization
+sidebar:
+ order: 2
+ group:
+ hideIndex: true
+---
+
+import { DirectoryListing } from "~/components";
+
+
diff --git a/src/content/docs/images/transform-images/make-responsive-images.mdx b/src/content/docs/images/optimization/make-responsive-images.mdx
similarity index 82%
rename from src/content/docs/images/transform-images/make-responsive-images.mdx
rename to src/content/docs/images/optimization/make-responsive-images.mdx
index 5449ff22a6a..297ddd434f9 100644
--- a/src/content/docs/images/transform-images/make-responsive-images.mdx
+++ b/src/content/docs/images/optimization/make-responsive-images.mdx
@@ -4,10 +4,10 @@ title: Make responsive images
description: Learn how to serve responsive images using HTML srcset and width=auto for optimal display on various devices. Ideal for high-DPI and fluid layouts.
sidebar:
order: 7
-
---
You can serve responsive images in two different ways:
+
- Use the HTML `srcset` feature to allow browsers to choose the most optimal image. This is the most reliable solution to serve responsive images.
- Use the `width=auto` option to serve the most optimal image based on the available browser and device information. This is a server-side solution that is supported only by Chromium-based browsers.
@@ -19,8 +19,8 @@ The `srcset` [feature of HTML](https://developer.mozilla.org/en-US/docs/Learn/HT
There are two different scenarios where it is useful to use `srcset`:
-* Images with a fixed size in terms of CSS pixels, but adapting to high-DPI screens (also known as Retina displays). These images take the same amount of space on the page regardless of screen size, but are sharper on high-resolution displays. This is appropriate for icons, thumbnails, and most images on pages with fixed-width layouts.
-* Responsive images that stretch to fill a certain percentage of the screen (usually full width). This is best for hero images and pages with fluid layouts, including pages using media queries to adapt to various screen sizes.
+- Images with a fixed size in terms of CSS pixels, but adapting to high-DPI screens (also known as Retina displays). These images take the same amount of space on the page regardless of screen size, but are sharper on high-resolution displays. This is appropriate for icons, thumbnails, and most images on pages with fixed-width layouts.
+- Responsive images that stretch to fill a certain percentage of the screen (usually full width). This is best for hero images and pages with fluid layouts, including pages using media queries to adapt to various screen sizes.
### `srcset` for high-DPI displays
@@ -30,8 +30,8 @@ Assuming you have an image `product.jpg` in the `assets` folder and you want to
```html
```
@@ -49,24 +49,24 @@ By default, the browser assumes the image will be stretched to the full width of
```html
```
-In the previous case, the number followed by `x` described *screen* density. In this case the number followed by `w` describes the *image* size. There is no need to specify screen density here (`2x`, etc.), because the browser automatically takes it into account and picks a higher-resolution image when necessary.
+In the previous case, the number followed by `x` described _screen_ density. In this case the number followed by `w` describes the _image_ size. There is no need to specify screen density here (`2x`, etc.), because the browser automatically takes it into account and picks a higher-resolution image when necessary.
If the image is not displayed at full width of the screen (or browser window), you have two options:
-* If the image is displayed at full width of a fixed-width column, use the first technique that uses one specific image size.
-* If it takes a specific percentage of the screen, or stretches to full width only sometimes (using CSS media queries), then add the `sizes` attribute as described below.
+- If the image is displayed at full width of a fixed-width column, use the first technique that uses one specific image size.
+- If it takes a specific percentage of the screen, or stretches to full width only sometimes (using CSS media queries), then add the `sizes` attribute as described below.
#### The `sizes` attribute
@@ -80,14 +80,14 @@ The `vw` unit is a percentage of the viewport (screen or window) width. If the i
```html
![]()
```
@@ -101,12 +101,12 @@ HTML also [supports the `` element](https://developer.mozilla.org/en-US
If you want to use WebP images, but do not need resizing, you have two options:
-* You can enable the automatic [WebP conversion in Polish](/images/polish/activate-polish/). This will convert all images on the site.
-* Alternatively, you can change specific image paths on the site to start with `/cdn-cgi/image/format=auto/`. For example, change `https://example.com/assets/hero.jpg` to `https://example.com/cdn-cgi/image/format=auto/assets/hero.jpg`.
+- You can enable the automatic [WebP conversion in Polish](/images/polish/activate-polish/). This will convert all images on the site.
+- Alternatively, you can change specific image paths on the site to start with `/cdn-cgi/image/format=auto/`. For example, change `https://example.com/assets/hero.jpg` to `https://example.com/cdn-cgi/image/format=auto/assets/hero.jpg`.
## Transform with `width` parameter
-When setting up a [transformation URL](/images/transform-images/transform-via-url/#width), you can apply the `width=auto` option to serve the most optimal image based on the available information about the user's browser and device.
+When setting up a [transformation URL](/images/optimization/features/#width), you can apply the `width=auto` option to serve the most optimal image based on the available information about the user's browser and device.
This method can serve multiple sizes from a single URL. Currently, images will be served in one of four sizes:
diff --git a/src/content/docs/images/transform-images/bindings.mdx b/src/content/docs/images/optimization/transformations/bindings.mdx
similarity index 85%
rename from src/content/docs/images/transform-images/bindings.mdx
rename to src/content/docs/images/optimization/transformations/bindings.mdx
index ad0e889ba21..e8a20b75bc0 100644
--- a/src/content/docs/images/transform-images/bindings.mdx
+++ b/src/content/docs/images/optimization/transformations/bindings.mdx
@@ -7,7 +7,7 @@ sidebar:
import { WranglerConfig, TypeScriptExample } from "~/components";
-A [binding](/workers/runtime-apis/bindings/) connects your [Worker](/workers/) to external resources on the Developer Platform, like [Images](/images/transform-images/transform-via-workers/), [R2 buckets](/r2/buckets/), or [KV Namespaces](/kv/concepts/kv-namespaces/).
+A [binding](/workers/runtime-apis/bindings/) connects your [Worker](/workers/) to external resources on the Developer Platform, like [Images](/images/optimization/transformations/transform-via-workers/), [R2 buckets](/r2/buckets/), or [KV Namespaces](/kv/concepts/kv-namespaces/).
You can bind the Images API to your Worker to transform, resize, and encode images without requiring them to be accessible through a URL.
@@ -51,11 +51,11 @@ Within your Worker code, you can interact with this binding by using `env.IMAGES
### `.transform()`
-- Defines how an image should be optimized and manipulated through [parameters](/images/transform-images/transform-via-workers/#fetch-options) such as `width`, `height`, and `blur`.
+- Defines how an image should be optimized and manipulated through [parameters](/images/optimization/features/#parameters) such as `width`, `height`, and `blur`.
### `.draw()`
-- Allows [drawing an image](/images/transform-images/draw-overlays/) over another image.
+- Allows [drawing an image](/images/optimization/transformations/draw-overlays/) over another image.
- The drawn image can be a stream, or another image returned from `.input()` that has been manipulated.
- The overlaid image can be manipulated using `opacity`, `repeat`, `top`, `left`, `bottom`, and `right`. To apply other parameters, you can pass a child `.transform()` function inside this method.
@@ -86,10 +86,10 @@ return response;
### `.output()`
-- You must define [a supported format](/images/transform-images/#supported-output-formats) such as AVIF, WebP, or JPEG for the [transformed image](/images/transform-images/).
+- You must define [a supported format](/images/get-started/limits/#output-formats) such as AVIF, WebP, or JPEG for the transformed image.
- This is required since there is no default format to fallback to.
-- [Image quality](/images/transform-images/transform-via-url/#quality) can be altered by specifying `quality` on a 1-100 scale.
-- [Animation preservation](/images/transform-images/transform-via-url/#anim) can be controlled with the `anim` parameter. Set `anim: false` to reduce animations to still images.
+- [Image quality](/images/optimization/features/#quality) can be altered by specifying `quality` on a 1-100 scale.
+- [Animation preservation](/images/optimization/features/#anim) can be controlled with the `anim` parameter. Set `anim: false` to reduce animations to still images.
For example, to rotate, resize, and blur an image, then output the image as AVIF:
diff --git a/src/content/docs/images/transform-images/control-origin-access.mdx b/src/content/docs/images/optimization/transformations/control-origin-access.mdx
similarity index 98%
rename from src/content/docs/images/transform-images/control-origin-access.mdx
rename to src/content/docs/images/optimization/transformations/control-origin-access.mdx
index f2527645422..b36f2223fca 100644
--- a/src/content/docs/images/transform-images/control-origin-access.mdx
+++ b/src/content/docs/images/optimization/transformations/control-origin-access.mdx
@@ -2,12 +2,12 @@
pcx_content_type: reference
title: Control origin access
sidebar:
- order: 4
+ order: 5
---
You can serve resized images without giving access to the original image. Images can be hosted on another server outside of your zone, and the true source of the image can be entirely hidden. The origin server may require authentication to disclose the original image, without needing visitors to be aware of it. Access to the full-size image may be prevented by making it impossible to manipulate resizing parameters.
-All these behaviors are completely customizable, because they are handled by custom code of a script running [on the edge in a Cloudflare Worker](/images/transform-images/transform-via-workers/).
+All these behaviors are completely customizable, because they are handled by custom code of a script running [on the edge in a Cloudflare Worker](/images/optimization/transformations/transform-via-workers/).
```js
export default {
diff --git a/src/content/docs/images/transform-images/draw-overlays.mdx b/src/content/docs/images/optimization/transformations/draw-overlays.mdx
similarity index 83%
rename from src/content/docs/images/transform-images/draw-overlays.mdx
rename to src/content/docs/images/optimization/transformations/draw-overlays.mdx
index d0df7b52472..993c539e891 100644
--- a/src/content/docs/images/transform-images/draw-overlays.mdx
+++ b/src/content/docs/images/optimization/transformations/draw-overlays.mdx
@@ -2,12 +2,12 @@
pcx_content_type: reference
title: Draw overlays and watermarks
sidebar:
- order: 5
+ order: 6
---
You can draw additional images on top of a resized image, with transparency and blending effects. This enables adding of watermarks, logos, signatures, vignettes, and other effects to resized images.
-This feature is available only in [Workers](/images/transform-images/transform-via-workers/). To draw overlay images, add an array of drawing commands to options of `fetch()` requests. The drawing options are nested in `options.cf.image.draw`, like in the following example:
+This feature is available only in [Workers](/images/optimization/transformations/transform-via-workers/). To draw overlay images, add an array of drawing commands to options of `fetch()` requests. The drawing options are nested in `options.cf.image.draw`, like in the following example:
```js
fetch(imageURL, {
@@ -42,7 +42,7 @@ The `draw` property is an array. Overlays are drawn in the order they appear in
- Maximum size of the overlay image, in pixels. It must be an integer.
- `fit` and `gravity`
- - Affects interpretation of `width` and `height`. Same as [for the main image](/images/transform-images/transform-via-workers/#fetch-options).
+ - Affects interpretation of `width` and `height`. Same as [for the main image](/images/optimization/features/).
- `opacity`
- Floating-point number between `0` (transparent) and `1` (opaque). For example, `opacity: 0.5` makes overlay semitransparent.
@@ -60,14 +60,14 @@ The `draw` property is an array. Overlays are drawn in the order they appear in
If no position is specified, the image will be centered.
- `background`
- - Background color to add underneath the overlay image. Same as [for the main image](/images/transform-images/transform-via-workers/#fetch-options).
+ - Background color to add underneath the overlay image. Same as [for the main image](/images/optimization/features/).
- `rotate`
- - Number of degrees to rotate the overlay image by. Same as [for the main image](/images/transform-images/transform-via-workers/#fetch-options).
+ - Number of degrees to rotate the overlay image by. Same as [for the main image](/images/optimization/features/).
## Draw using the Images binding
-When [interacting with Images through a binding](/images/transform-images/bindings/), the Images API supports a `.draw()` method.
+When [interacting with Images through a binding](/images/optimization/transformations/bindings/), the Images API supports a `.draw()` method.
The accepted options for the overlaid image are `opacity`, `repeat`, `top`, `left`, `bottom`, and `right`.
@@ -86,7 +86,7 @@ const response = (
return response;
```
-To apply [parameters](/images/transform-images/transform-via-workers/) to the overlaid image, you can pass a child `.transform()` function inside the `.draw()` request.
+To apply [parameters](/images/optimization/features/#parameters) to the overlaid image, you can pass a child `.transform()` function inside the `.draw()` request.
In the example below, the watermark is manipulated with `rotate` and `width` before being drawn over the base image with the `opacity` and `rotate` options.
diff --git a/src/content/docs/images/optimization/transformations/index.mdx b/src/content/docs/images/optimization/transformations/index.mdx
new file mode 100644
index 00000000000..cb909d9ba4b
--- /dev/null
+++ b/src/content/docs/images/optimization/transformations/index.mdx
@@ -0,0 +1,12 @@
+---
+pcx_content_type: navigation
+title: Remote images (transformations)
+sidebar:
+ order: 2
+ group:
+ hideIndex: true
+---
+
+import { DirectoryListing } from "~/components";
+
+
diff --git a/src/content/docs/images/transform-images/integrate-with-frameworks.mdx b/src/content/docs/images/optimization/transformations/integrate-with-frameworks.mdx
similarity index 56%
rename from src/content/docs/images/transform-images/integrate-with-frameworks.mdx
rename to src/content/docs/images/optimization/transformations/integrate-with-frameworks.mdx
index 6ba9f48ec88..a3aedde9e70 100644
--- a/src/content/docs/images/transform-images/integrate-with-frameworks.mdx
+++ b/src/content/docs/images/optimization/transformations/integrate-with-frameworks.mdx
@@ -2,8 +2,7 @@
title: Integrate with frameworks
pcx_content_type: reference
sidebar:
- order: 6
-
+ order: 8
---
## Next.js
@@ -20,15 +19,15 @@ Image transformations will be responsible for caching and serving an optimal for
To use Images with **all** your app's images, define a global [loaderFile](https://nextjs.org/docs/pages/api-reference/components/image#loaderfile) for your app.
-Add the following settings to the **next.config.js** file located at the root our your Next.js application.
+Add the following settings to the **next.config.js** file located at the root of your Next.js application.
```ts
module.exports = {
- images: {
- loader: 'custom',
- loaderFile: './imageLoader.ts',
- },
-}
+ images: {
+ loader: "custom",
+ loaderFile: "./imageLoader.ts",
+ },
+};
```
Next, create the `imageLoader.ts` file in the specified path (relative to the root of your Next.js application).
@@ -37,22 +36,22 @@ Next, create the `imageLoader.ts` file in the specified path (relative to the ro
import type { ImageLoaderProps } from "next/image";
const normalizeSrc = (src: string) => {
- return src.startsWith("/") ? src.slice(1) : src;
+ return src.startsWith("/") ? src.slice(1) : src;
};
export default function cloudflareLoader({
- src,
- width,
- quality,
+ src,
+ width,
+ quality,
}: ImageLoaderProps) {
- const params = [`width=${width}`];
- if (quality) {
- params.push(`quality=${quality}`);
- }
- if (process.env.NODE_ENV === "development") {
- return `${src}?${params.join("&")}`;
- }
- return `/cdn-cgi/image/${params.join(",")}/${normalizeSrc(src)}`;
+ const params = [`width=${width}`];
+ if (quality) {
+ params.push(`quality=${quality}`);
+ }
+ if (process.env.NODE_ENV === "development") {
+ return `${src}?${params.join("&")}`;
+ }
+ return `/cdn-cgi/image/${params.join(",")}/${normalizeSrc(src)}`;
}
```
@@ -61,43 +60,41 @@ export default function cloudflareLoader({
Alternatively, define a loader for each `` component.
```js
-import Image from 'next/image';
+import Image from "next/image";
const normalizeSrc = (src) => {
- return src.startsWith('/') ? src.slice(1) : src;
+ return src.startsWith("/") ? src.slice(1) : src;
};
const cloudflareLoader = ({ src, width, quality }) => {
- const params = [`width=${width}`];
- if (quality) {
- params.push(`quality=${quality}`);
- }
- if (process.env.NODE_ENV === "development") {
- return `${src}?${params.join("&")}`;
- }
- return `/cdn-cgi/image/${params.join(",")}/${normalizeSrc(src)}`;
+ const params = [`width=${width}`];
+ if (quality) {
+ params.push(`quality=${quality}`);
+ }
+ if (process.env.NODE_ENV === "development") {
+ return `${src}?${params.join("&")}`;
+ }
+ return `/cdn-cgi/image/${params.join(",")}/${normalizeSrc(src)}`;
};
const MyImage = (props) => {
- return (
-
- );
+ return (
+
+ );
};
```
:::note
-
-For local development, you can enable [Resize images from any origin checkbox](/images/get-started/) for your zone. Then, replace `/cdn-cgi/image/${paramsString}/${normalizeSrc(src)}` with an absolute URL path:
+For local development, you can enable [Resize images from any origin checkbox](/images/optimization/transformations/sources/) for your zone. Then, replace `/cdn-cgi/image/${paramsString}/${normalizeSrc(src)}` with an absolute URL path:
`https:///cdn-cgi/image/${paramsString}/${normalizeSrc(src)}`
-
:::
diff --git a/src/content/docs/images/optimization/transformations/overview.mdx b/src/content/docs/images/optimization/transformations/overview.mdx
new file mode 100644
index 00000000000..7cad182e688
--- /dev/null
+++ b/src/content/docs/images/optimization/transformations/overview.mdx
@@ -0,0 +1,42 @@
+---
+pcx_content_type: concept
+title: Overview
+sidebar:
+ order: 1
+---
+
+import { Description, Render } from "~/components";
+
+
+ Transformations are requests to optimize and manipulate remote images that are stored outside of Images.
+
+
+When you ship applications on Cloudflare, you can use Images to automatically optimize and cache your images from any origin.
+
+Our image optimization pipeline provides a rich set of [features](/images/optimization/features) that can be applied across entire media libraries to compress images at scale, transcode files into efficient formats for delivery, and resize and crop images for different use cases and devices.
+
+## How it works
+
+You can request transformations by using a specially-formatted URL to serve images on your Cloudflare zone or through Workers.
+
+To serve transformations on your zone, you must first enable the feature:
+
+1. In the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/images/transformations), go to **Images** > **Transformations**.
+2. Select the zone where you want to serve transformations.
+3. Enable **transformations** on your zone.
+
+When the browser requests a transformed image, Cloudflare checks the edge cache for a previously optimized version with the same parameters:
+
+**On a cache hit** — Cloudflare serves the optimized image directly from the edge without contacting the origin or re-applying the optimization parameters.
+
+**On a cache miss** — Cloudflare fetches the original image from the source origin, applies the requested parameters (e.g. `format`, `width`, `quality`), caches the transformed result, and serves it to the browser. The original image is also cached to speed up future transformations of the same source.
+
+Each unique combination of source image and parameters is cached and billed separately. The first request for each unique version within a calendar month is billed as one [unique transformation](/images/optimization/features), regardless of cache status. Subsequent requests for this transformation do not incur billable usage within the same calendar month.
+
+## Configure your zone
+
+After enabling transformations on your zone, you can configure how Cloudflare handles transformation requests:
+
+- **[Define source origins](/images/optimization/transformations/sources)** — Specify which origins Cloudflare can pull source images from. By default, Cloudflare only accepts source images from the same zone where transformations are served.
+- **[Control origin access](/images/optimization/transformations/control-origin-access)** — Use Workers to add custom logic for validating and controlling access to source images.
+- **[Set up rewrite rules](/images/optimization/transformations/rewrite-rules)** — Use Transform Rules to rewrite image URLs and serve transformations from custom paths.
diff --git a/src/content/docs/images/transform-images/preserve-content-credentials.mdx b/src/content/docs/images/optimization/transformations/preserve-content-credentials.mdx
similarity index 93%
rename from src/content/docs/images/transform-images/preserve-content-credentials.mdx
rename to src/content/docs/images/optimization/transformations/preserve-content-credentials.mdx
index f6ea312e950..335c80845d9 100644
--- a/src/content/docs/images/transform-images/preserve-content-credentials.mdx
+++ b/src/content/docs/images/optimization/transformations/preserve-content-credentials.mdx
@@ -2,8 +2,7 @@
pcx_content_type: reference
title: Preserve Content Credentials
sidebar:
- order: 5
-
+ order: 7
---
[Content Credentials](https://contentcredentials.org/) (or C2PA metadata) are a type of metadata that includes the full provenance chain of a digital asset. This provides information about an image's creation, authorship, and editing flow. This data is cryptographically authenticated and can be verified using an [open-source verification service](https://contentcredentials.org/verify).
@@ -18,7 +17,7 @@ In the Cloudflare dashboard under **Images** > **Transformations**, navigate to
-The behavior of this setting is determined by the [`metadata`](/images/transform-images/transform-via-url/#metadata) parameter for each transformation.
+The behavior of this setting is determined by the [`metadata`](/images/optimization/features/#metadata) parameter for each transformation.
For example, if a transformation specifies `metadata=copyright`, then the EXIF copyright tag and all Content Credentials will be preserved in the resulting image and all other metadata will be discarded.
diff --git a/src/content/docs/images/transform-images/serve-images-custom-paths.mdx b/src/content/docs/images/optimization/transformations/rewrite-rules.mdx
similarity index 98%
rename from src/content/docs/images/transform-images/serve-images-custom-paths.mdx
rename to src/content/docs/images/optimization/transformations/rewrite-rules.mdx
index 39efe86f0f6..4775e6a3e68 100644
--- a/src/content/docs/images/transform-images/serve-images-custom-paths.mdx
+++ b/src/content/docs/images/optimization/transformations/rewrite-rules.mdx
@@ -1,12 +1,13 @@
---
pcx_content_type: reference
-title: Serve images from custom paths
+title: Set up rewrite rules
sidebar:
- order: 8
+ order: 9
head:
- tag: title
content: Serve images from custom paths
---
+
import { DashButton } from "~/components";
You can use Transform Rules to rewrite URLs for every image that you transform through Images.
@@ -18,6 +19,7 @@ This page covers examples for the following scenarios:
- Transform every image requested on your zone with Images
To create a rule:
+
1. In the Cloudflare dashboard, go to the **Rules Overview** page.
diff --git a/src/content/docs/images/transform-images/sources.mdx b/src/content/docs/images/optimization/transformations/sources.mdx
similarity index 70%
rename from src/content/docs/images/transform-images/sources.mdx
rename to src/content/docs/images/optimization/transformations/sources.mdx
index 1341dfe11c3..f6eced556c4 100644
--- a/src/content/docs/images/transform-images/sources.mdx
+++ b/src/content/docs/images/optimization/transformations/sources.mdx
@@ -1,6 +1,6 @@
---
pcx_content_type: how-to
-title: Define source origin
+title: Define source origins
sidebar:
order: 2
---
@@ -10,7 +10,7 @@ When optimizing remote images, you can specify which origins can be used as the
On this page, you will learn how to define and manage the origins for the source images that you want to optimize.
:::note
-The allowed origins setting applies to requests from Cloudflare Workers.
+The allowed origins setting applies to requests from [Workers](/workers/).
If you use a Worker to optimize remote images via a `fetch()` subrequest, then this setting may conflict with existing logic that handles source images.
:::
@@ -19,7 +19,7 @@ If you use a Worker to optimize remote images via a `fetch()` subrequest, then t
In the Cloudflare dashboard, go to **Images** > **Transformations** and select the zone where you want to serve transformations.
-To get started, you must have [transformations enabled on your zone](/images/get-started/#enable-transformations-on-your-zone).
+To get started, you must have [transformations enabled on your zone](/images/optimization/transformations/overview/#how-it-works).
In **Sources**, you can configure the origins for transformations on your zone.
@@ -40,17 +40,17 @@ To define a new origin:
- When you add a root domain, subdomains are not accepted. In other words, if you add `b.com`, then source images from `media.b.com` will be rejected.
+When you add a root domain, subdomains are not accepted. In other words, if you add `b.com`, then source images from `media.b.com` will be rejected.
- To support individual subdomains, define an additional origin such as `media.b.com`. If you add only `media.b.com` and not the root domain, then source images from the root domain (`b.com`) and other subdomains (`cdn.b.com`) will be rejected.
+To support individual subdomains, define an additional origin such as `media.b.com`. If you add only `media.b.com` and not the root domain, then source images from the root domain (`b.com`) and other subdomains (`cdn.b.com`) will be rejected.
- To support all subdomains, use the `*` wildcard at the beginning of the root domain. For example, `*.b.com` will accept source images from the root domain (like `b.com/image.png`) as well as from subdomains (like `media.b.com/image.png` or `cdn.b.com/image.png`).
+To support all subdomains, use the `*` wildcard at the beginning of the root domain. For example, `*.b.com` will accept source images from the root domain (like `b.com/image.png`) as well as from subdomains (like `media.b.com/image.png` or `cdn.b.com/image.png`).
3. Optionally, you can specify the **Path** for the source image. If no path is specified, then source images from all paths on this domain are accepted.
- Cloudflare checks whether the defined path is at the beginning of the source path. If the defined path is not present at the beginning of the path, then the source image will be rejected.
+Cloudflare checks whether the defined path is at the beginning of the source path. If the defined path is not present at the beginning of the path, then the source image will be rejected.
- For example, if you define an origin with domain `b.com` and path `/themes`, then `b.com/themes/image.png` will be accepted but `b.com/media/themes/image.png` will be rejected.
+For example, if you define an origin with domain `b.com` and path `/themes`, then `b.com/themes/image.png` will be accepted but `b.com/media/themes/image.png` will be rejected.
4. Select **Add**. Your origin will now appear in your list of allowed origins.
5. Select **Save**. These changes will take effect immediately.
diff --git a/src/content/docs/images/transform-images/transform-via-workers.mdx b/src/content/docs/images/optimization/transformations/transform-via-workers.mdx
similarity index 79%
rename from src/content/docs/images/transform-images/transform-via-workers.mdx
rename to src/content/docs/images/optimization/transformations/transform-via-workers.mdx
index 0a5bef52bc2..30e5daa665e 100644
--- a/src/content/docs/images/transform-images/transform-via-workers.mdx
+++ b/src/content/docs/images/optimization/transformations/transform-via-workers.mdx
@@ -2,126 +2,22 @@
pcx_content_type: how-to
title: Transform via Workers
sidebar:
- order: 2
+ order: 3
---
import { Render } from "~/components";
-Using Cloudflare Workers to transform with a custom URL scheme gives you powerful programmatic control over every image request.
+Using Workers to transform with a custom URL scheme gives you powerful programmatic control over every image request.
-Here are a few examples of the flexibility Workers give you:
+Here are a few examples of the flexibility that Workers give you:
- **Use a custom URL scheme**. Instead of specifying pixel dimensions in image URLs, use preset names such as `thumbnail` and `large`.
- **Hide the actual location of the original image**. You can store images in an external S3 bucket or a hidden folder on your server without exposing that information in URLs.
- **Implement content negotiation**. This is useful to adapt image sizes, formats and quality dynamically based on the device and condition of the network.
-The resizing feature is accessed via the [options](/workers/runtime-apis/request/#the-cf-property-requestinitcfproperties) of a `fetch()` [subrequest inside a Worker](/workers/runtime-apis/fetch/).
+## How it works
-:::note
-
-You can use Cloudflare Images to sanitize SVGs but not to resize them.
-
-:::
-
-## Fetch options
-
-The `fetch()` function accepts parameters in the second argument inside the `{cf: {image: {…}}}` object.
-
-### `anim`
-
-
-
-### `background`
-
-
-
-### `blur`
-
-
-
-### `border`
-
-
-
-### `brightness`
-
-
-
-### `compression`
-
-
-
-### `contrast`
-
-
-
-### `dpr`
-
-
-
-### `fit`
-
-
-
-### `flip`
-
-
-
-### `format`
-
-
-
-### `gamma`
-
-
-
-### `gravity`
-
-
-
-### `height`
-
-
-
-### `metadata`
-
-
-
-### `onerror`
-
-
-
-### `quality`
-
-
-
-### `rotate`
-
-
-
-### `saturation`
-
-
-
-### `segment`
-
-
-
-### `sharpen`
-
-
-
-### `trim`
-
-
-
-### `width`
-
-
-
-### `zoom`
-
-
+The resizing feature is accessed via the [options](/workers/runtime-apis/request/#the-cf-property-requestinitcfproperties) of a `fetch()` [subrequest inside a Worker](/workers/runtime-apis/fetch/). The `fetch()` function accepts parameters in the second argument inside the `{cf: {image: {…}}}` object.
In your worker, where you would fetch the image using `fetch(request)`, add options like in the following example:
@@ -145,7 +41,7 @@ Create a new script in the Workers section of the Cloudflare dashboard. Scope yo
:::caution[Warning]
-Do not set up the Image Resizing worker for the entire zone (`/*`). This will block all non-image requests and make your website inaccessible.
+Do not set up the image optimization worker for the entire zone (`/*`). This will block all non-image requests and make your website inaccessible.
:::
@@ -175,7 +71,7 @@ export default {
:::note[Note]
-Image transformations are not simulated in the preview of in the Workers dashboard editor.
+Image transformations are not simulated in the preview of the Workers dashboard editor.
:::
diff --git a/src/content/docs/images/platform/changelog.mdx b/src/content/docs/images/platform/changelog.mdx
index 7cd806f1a1e..1cf70f1c17b 100644
--- a/src/content/docs/images/platform/changelog.mdx
+++ b/src/content/docs/images/platform/changelog.mdx
@@ -9,4 +9,4 @@ import { ProductReleaseNotes } from "~/components";
{/* */}
-
\ No newline at end of file
+
diff --git a/src/content/docs/images/platform/index.mdx b/src/content/docs/images/platform/index.mdx
index f103eb2a29f..323087a65d7 100644
--- a/src/content/docs/images/platform/index.mdx
+++ b/src/content/docs/images/platform/index.mdx
@@ -4,9 +4,8 @@ title: Platform
sidebar:
group:
hideIndex: true
-
---
-import { DirectoryListing } from "~/components"
+import { DirectoryListing } from "~/components";
-
\ No newline at end of file
+
diff --git a/src/content/docs/images/polish/activate-polish.mdx b/src/content/docs/images/polish/activate-polish.mdx
index 8c867627a94..26aba9da010 100644
--- a/src/content/docs/images/polish/activate-polish.mdx
+++ b/src/content/docs/images/polish/activate-polish.mdx
@@ -3,18 +3,15 @@ pcx_content_type: how-to
title: Activate Polish
sidebar:
order: 1
-
---
-import { Render,DashButton } from "~/components"
+import { Render, DashButton } from "~/components";
Images in the [cache must be purged](/cache/how-to/purge-cache/) or expired before seeing any changes in Polish settings.
:::caution
-
-Do not activate Polish and [image transformations](/images/transform-images/) simultaneously. Image transformations already apply lossy compression, which makes Polish redundant.
-
+Do not activate Polish and [image transformations](/images/optimization/transformations/overview) simultaneously. Image transformations already apply lossy compression, which makes Polish redundant.
:::
@@ -23,8 +20,8 @@ Do not activate Polish and [image transformations](/images/transform-images/) si
2. Select the domain where you want to activate Polish.
-3. Select ****Speed** > **Settings**** > **Image Optimization**.
-4. Under **Polish**, select *Lossy* or *Lossless* from the drop-down menu. [*Lossy*](/images/polish/compression/#lossy) gives greater file size savings.
+3. Select **Speed** > **Settings** > **Image Optimization**.
+4. Under **Polish**, select _Lossy_ or _Lossless_ from the drop-down menu. [_Lossy_](/images/polish/compression/#lossy) gives greater file size savings.
5. (Optional) Select **WebP**. Enable this option if you want to further optimize PNG and JPEG images stored in the origin server, and serve them as WebP files to browsers that support this format.
To ensure WebP is not served from cache to a browser without WebP support, disable any WebP conversion utilities at your origin web server when using Polish.
diff --git a/src/content/docs/images/polish/cf-polished-statuses.mdx b/src/content/docs/images/polish/cf-polished-statuses.mdx
index b0e7aa33761..5aad3cf956a 100644
--- a/src/content/docs/images/polish/cf-polished-statuses.mdx
+++ b/src/content/docs/images/polish/cf-polished-statuses.mdx
@@ -5,14 +5,13 @@ title: Cf-Polished statuses
description: Learn about Cf-Polished statuses in Cloudflare Images. Understand how to handle missing headers, optimize image formats, and troubleshoot common issues.
sidebar:
order: 8
-
---
If a `Cf-Polished` header is not returned, try [using single-file cache purge](/cache/how-to/purge-cache) to purge the image. The `Cf-Polished` header may also be missing if the origin is sending non-image `Content-Type`, or non-cacheable `Cache-Control`.
-* `input_too_large`: The input image is too large or complex to process, and needs a lower resolution. Cloudflare recommends using PNG or JPEG images that are less than 4,000 pixels in any dimension, and smaller than 20 MB.
-* `not_compressed` or `not_needed`: The image was fully optimized at the origin server and no compression was applied.
-* `webp_bigger`: Polish attempted to convert to WebP, but the WebP image was not better than the original format. Because the WebP version does not exist, the status is set on the JPEG/PNG version of the response. Refer to [the reasons why Polish chooses not to use WebP](/images/polish/no-webp/).
-* `cannot_optimize` or `internal_error`: The input image is corrupted or incomplete at the origin server. Upload a new version of the image to the origin server.
-* `format_not_supported`: The input image format is not supported (for example, BMP or TIFF) or the origin server is using additional optimization software that is not compatible with Polish. Try converting the input image to a web-compatible format (like PNG or JPEG) and/or disabling additional optimization software at the origin server.
-* `vary_header_present`: The origin web server has sent a `Vary` header with a value other than `accept-encoding`. If the origin web server is attempting to support WebP, disable WebP at the origin web server and let Polish perform the WebP conversion. Polish will still work if `accept-encoding` is the only header listed within the `Vary` header. Polish skips image URLs processed by [Cloudflare Images](/images/transform-images/).
+- `input_too_large`: The input image is too large or complex to process, and needs a lower resolution. Cloudflare recommends using PNG or JPEG images that are less than 4,000 pixels in any dimension, and smaller than 20 MB.
+- `not_compressed` or `not_needed`: The image was fully optimized at the origin server and no compression was applied.
+- `webp_bigger`: Polish attempted to convert to WebP, but the WebP image was not better than the original format. Because the WebP version does not exist, the status is set on the JPEG/PNG version of the response. Refer to [the reasons why Polish chooses not to use WebP](/images/polish/no-webp/).
+- `cannot_optimize` or `internal_error`: The input image is corrupted or incomplete at the origin server. Upload a new version of the image to the origin server.
+- `format_not_supported`: The input image format is not supported (for example, BMP or TIFF) or the origin server is using additional optimization software that is not compatible with Polish. Try converting the input image to a web-compatible format (like PNG or JPEG) and/or disabling additional optimization software at the origin server.
+- `vary_header_present`: The origin web server has sent a `Vary` header with a value other than `accept-encoding`. If the origin web server is attempting to support WebP, disable WebP at the origin web server and let Polish perform the WebP conversion. Polish will still work if `accept-encoding` is the only header listed within the `Vary` header. Polish skips image URLs processed by [Cloudflare Images](/images/optimization/transformations/overview).
diff --git a/src/content/docs/images/polish/compression.mdx b/src/content/docs/images/polish/compression.mdx
index d29cd25eff8..c15f03762b1 100644
--- a/src/content/docs/images/polish/compression.mdx
+++ b/src/content/docs/images/polish/compression.mdx
@@ -4,7 +4,6 @@ title: Polish compression
description: Learn about Cloudflare's Polish compression options, including Lossless, Lossy, and WebP, to optimize image file sizes while managing metadata effectively.
sidebar:
order: 2
-
---
With Lossless and Lossy modes, Cloudflare attempts to strip as much metadata as possible. However, Cloudflare cannot guarantee stripping all metadata because other factors, such as caching status, might affect which metadata is finally sent in the response.
diff --git a/src/content/docs/images/polish/index.mdx b/src/content/docs/images/polish/index.mdx
index b434a4c783b..c36a6c80a67 100644
--- a/src/content/docs/images/polish/index.mdx
+++ b/src/content/docs/images/polish/index.mdx
@@ -3,10 +3,9 @@ pcx_content_type: concept
title: Cloudflare Polish
sidebar:
order: 7
-
---
-import { FeatureTable } from "~/components"
+import { FeatureTable } from "~/components";
Cloudflare Polish is a one-click image optimization product that automatically optimizes images in your site. Polish strips metadata from images and reduces image size through lossy or lossless compression to accelerate the speed of image downloads.
@@ -16,8 +15,14 @@ When an image is fetched from your origin, our systems automatically optimize it
## Comparison
-* Polish automatically optimizes all images served from your origin server. It keeps the same image URLs, and does not require changing markup of your pages.
-* Cloudflare Images API allows you to create new images with resizing, cropping, watermarks, and other processing applied. These images get their own new URLs, and you need to embed them on your pages to take advantage of this service. Images created this way are already optimized, and there is no need to apply Polish to them.
+- Polish automatically optimizes all images served from your origin
+ server. It keeps the same image URLs, and does not require changing markup of
+ your pages.
+- Cloudflare Images API allows you to create new images with resizing,
+ cropping, watermarks, and other processing applied. These images get their own
+ new URLs, and you need to embed them on your pages to take advantage of this
+ service. Images created this way are already optimized, and there is no need
+ to apply Polish to them.
## Availability
diff --git a/src/content/docs/images/polish/no-webp.mdx b/src/content/docs/images/polish/no-webp.mdx
index 97e8fa89aad..53b0f128742 100644
--- a/src/content/docs/images/polish/no-webp.mdx
+++ b/src/content/docs/images/polish/no-webp.mdx
@@ -1,7 +1,6 @@
---
pcx_content_type: troubleshooting
title: WebP may be skipped
-
---
Polish avoids converting images to the WebP format when such conversion would increase the file size, or significantly degrade image quality.
@@ -43,7 +42,7 @@ The WebP format does not support progressive rendering. With [HTTP/2 prioritizat
## Beware of compression that is not better, only more of the same
-With a lossy format like JPEG or WebP, it is always possible to take an existing image, save it with a slightly lower quality, and get an image that looks *almost* the same, but has a smaller file size.
+With a lossy format like JPEG or WebP, it is always possible to take an existing image, save it with a slightly lower quality, and get an image that looks _almost_ the same, but has a smaller file size.
It is the [heap paradox](https://en.wikipedia.org/wiki/Sorites_paradox): you can remove a grain of sand from a heap, and still have a heap of sand. There is no point when you can not make the heap smaller, except when there is no sand left. It is always possible to make an image with a slightly lower quality, all the way until all the accumulated losses degrade the image beyond recognition.
Avoid applying multiple lossy optimization tools to images, before or after Polish. Multiple lossy operations degrade quality disproportionally more than what they save in file sizes.
diff --git a/src/content/docs/images/pricing.mdx b/src/content/docs/images/pricing.mdx
index 13259052cef..823a05ad564 100644
--- a/src/content/docs/images/pricing.mdx
+++ b/src/content/docs/images/pricing.mdx
@@ -3,19 +3,18 @@ pcx_content_type: reference
title: Pricing
sidebar:
order: 6
-
---
-By default, all users are on the Images Free plan. The Free plan includes access to the transformations feature, which lets you optimize images stored outside of Images, like in R2.
+By default, all users are on the Images Free plan. The Free plan includes access to the transformations feature, which lets you optimize images stored outside of Images, like in [R2](/r2/).
The Paid plan allows transformations, as well as access to storage in Images.
Pricing is dependent on which features you use. The table below shows which metrics are used for each use case.
-| Use case | Metrics | Availability |
-|----------|---------|--------------|
-| Optimize images stored outside of Images | Images Transformed | Free and Paid plans |
-| Optimized images that are stored in Cloudflare Images | Images Stored, Images Delivered | Only Paid plans |
+| Use case | Metrics | Availability |
+| ----------------------------------------------------- | ------------------------------- | ------------------- |
+| Optimize images stored outside of Images | Images Transformed | Free and Paid plans |
+| Optimized images that are stored in Cloudflare Images | Images Stored, Images Delivered | Only Paid plans |
## Images Free
@@ -24,7 +23,7 @@ On the Free plan, you can request up to 5,000 unique transformations each month
Once you exceed 5,000 unique transformations:
- Existing transformations in cache will continue to be served as expected.
-- New transformations will return a `9422` error. If your source image is from the same domain where the transformation is served, then you can use the [`onerror` parameter](/images/transform-images/transform-via-url/#onerror) to redirect to the original image.
+- New transformations will return a `9422` error. If your source image is from the same domain where the transformation is served, then you can use the [`onerror` parameter](/images/optimization/features/#onerror) to redirect to the original image.
- You will not be charged for exceeding the limits in the Free plan.
To request more than 5,000 unique transformations each month, you can purchase an Images Paid plan.
@@ -33,11 +32,11 @@ To request more than 5,000 unique transformations each month, you can purchase a
When you purchase an Images Paid plan, you can choose your own storage or add storage in Images.
-| Metric | Pricing |
-|--------|---------|
+| Metric | Pricing |
+| ------------------ | ------------------------------------------------------------------------------------------ |
| Images Transformed | First 5,000 unique transformations included + $0.50 / 1,000 unique transformations / month |
-| Images Stored | $5 / 100,000 images stored / month |
-| Images Delivered | $1 / 100,000 images delivered / month |
+| Images Stored | $5 / 100,000 images stored / month |
+| Images Delivered | $1 / 100,000 images delivered / month |
If you optimize an image stored outside of Images, then you will be billed only for Images Transformed.
@@ -47,8 +46,8 @@ Alternatively, Images Stored and Images Delivered apply only to images that are
### Images Transformed
-A unique transformation is a request to transform an original image based on a set of [supported parameters](/images/transform-images/transform-via-url/#options). This metric is used only when optimizing images that are stored outside of Images.
-When using the [Images binding](/images/transform-images/bindings/) in Workers, every call to the binding counts as a transformation, regardless of whether the image or parameters are unique.
+A unique transformation is a request to transform an original image based on a set of [supported parameters](/images/optimization/features/). This metric is used only when optimizing images that are stored outside of Images.
+When using the [Images binding](/images/optimization/transformations/bindings/) in Workers, every call to the binding counts as a transformation, regardless of whether the image or parameters are unique.
For example, if you transform `thumbnail.jpg` as 100x100, then this counts as one unique transformation. If you transform the same `thumbnail.jpg` as 200x200, then this counts as a separate unique transformation.
@@ -60,9 +59,9 @@ The `format` parameter counts as only one billable transformation, even if multi
If you serve 2,000 remote images in five different sizes each month, then this results in 10,000 unique transformations. Your estimated cost for the month would be:
-| |Usage |Included |Billable quantity |Price |
-|-----------------------|-----------------------|-----------------------|-------------------------|-------------------------|
-|Transformations |10,000 unique transformations [^5] |5,000 |5,000 |$2.50 [^6]|
+| | Usage | Included | Billable quantity | Price |
+| --------------- | ---------------------------------- | -------- | ----------------- | ---------- |
+| Transformations | 10,000 unique transformations [^5] | 5,000 | 5,000 | $2.50 [^6] |
#### Example #2
@@ -70,13 +69,13 @@ If you use [R2](/r2/) for storage then your estimated monthly costs will be the
For example, if you upload 5,000 images to R2 with an average size of 5 MB, and serve 2,000 of those images in five different sizes, then your estimated cost for the month would be:
-| |Usage |Included |Billable quantity |Price |
-|-----------------------|-----------------------|-----------------------|-------------------------|-------------------------|
-|Storage |25 GB [^1] |10 GB |15 GB |$0.22 [^7] |
-|Class A operations |5,000 writes [^2]|1 million |0 |$0.00 [^8] |
-|Class B operations |10,000 reads [^3] |10 million |0 |$0.00 [^9] |
-|Transformations |10,000 unique transformations [^4] |5,000 | 5,000 | $2.50 [^10] |
-|**Total** | |||**$2.72**|
+| | Usage | Included | Billable quantity | Price |
+| ------------------ | ---------------------------------- | ---------- | ----------------- | ----------- |
+| Storage | 25 GB [^1] | 10 GB | 15 GB | $0.22 [^7] |
+| Class A operations | 5,000 writes [^2] | 1 million | 0 | $0.00 [^8] |
+| Class B operations | 10,000 reads [^3] | 10 million | 0 | $0.00 [^9] |
+| Transformations | 10,000 unique transformations [^4] | 5,000 | 5,000 | $2.50 [^10] |
+| **Total** | | | | **$2.72** |
### Images Stored
@@ -97,12 +96,21 @@ Every image requested by the browser counts as one billable request.
A retail website has a product page that uses Images to serve 10 images. If the page was visited 10,000 times this month, then this results in 100,000 images delivered — or $1.00 in billable usage.
[^1]: 5,000 objects × 5 MB per object
+
[^2]: 5,000 objects × 1 write per object
+
[^3]: 2,000 objects × 5 reads per object
+
[^4]: 2,000 original images × 5 sizes
+
[^5]: 2,000 original images × 5 sizes
+
[^6]: (5,000 transformations / 1,000) × $0.50
-[^7]: 15 GB × $0.015 / GB-month
-[^8]: 0 × $4.50 / million requests
-[^9]: 0 × $0.36 / million requests
+
+[^7]: 15 GB × $0.015 / GB-month
+
+[^8]: 0 × $4.50 / million requests
+
+[^9]: 0 × $0.36 / million requests
+
[^10]: (5,000 transformations / 1,000) × $0.50
diff --git a/src/content/docs/images/reference/security.mdx b/src/content/docs/images/reference/security.mdx
index 6dcd2cf7b7e..3ebd4afa76d 100644
--- a/src/content/docs/images/reference/security.mdx
+++ b/src/content/docs/images/reference/security.mdx
@@ -6,7 +6,6 @@ sidebar:
head:
- tag: title
content: Security | Image Optimization
-
---
To further ensure the security and efficiency of image optimization services, you can adopt Cloudflare products that safeguard against malicious activities.
diff --git a/src/content/docs/images/reference/troubleshooting.mdx b/src/content/docs/images/reference/troubleshooting.mdx
index b01d5497633..c2b144378c8 100644
--- a/src/content/docs/images/reference/troubleshooting.mdx
+++ b/src/content/docs/images/reference/troubleshooting.mdx
@@ -7,63 +7,63 @@ sidebar:
head:
- tag: title
content: Troubleshooting | Image Resizing
-
---
## Requests without resizing enabled
Does the response have a `Cf-Resized` header? If not, then resizing has not been attempted. Possible causes:
-* The feature is not enabled in the Cloudflare Dashboard.
-* There is another Worker running on the same request. Resizing is "forgotten" as soon as one Worker calls another. Do not use Workers scoped to the entire domain `/*`.
-* Preview in the Editor in Cloudflare Dashboard does not simulate image resizing. You must deploy the Worker and test from another browser tab instead.
+- The feature is not enabled in the Cloudflare Dashboard.
+- There is another Worker running on the same request. Resizing is "forgotten" as soon as one Worker calls another. Do not use Workers scoped to the entire domain `/*`.
+- Preview in the Editor in Cloudflare Dashboard does not simulate image resizing. You must deploy the Worker and test from another browser tab instead.
-***
+---
## Error responses from resizing
When resizing fails, the response body contains an error message explaining the reason, as well as the `Cf-Resized` header containing `err=code`:
-* 9401 — The required arguments in `{cf:image{…}}` options are missing or are invalid. Try again. Refer to [Fetch options](/images/transform-images/transform-via-workers/#fetch-options) for supported arguments.
-* 9402 — The image was too large or the connection was interrupted. Refer to [Supported formats and limitations](/images/transform-images/) for more information.
-* 9403 — A [request loop](/images/transform-images/transform-via-workers/#prevent-request-loops) occurred because the image was already resized or the Worker fetched its own URL. Verify your Worker path and image path on the server do not overlap.
-* 9406 & 9419 — The image URL is a non-HTTPS URL or the URL has spaces or unescaped Unicode. Check your URL and try again.
-* 9407 — A lookup error occurred with the origin server's domain name. Check your DNS settings and try again.
-* 9404 — The image does not exist on the origin server or the URL used to resize the image is wrong. Verify the image exists and check the URL.
-* 9408 — The origin server returned an HTTP 4xx status code and may be denying access to the image. Confirm your image settings and try again.
-* 9509 — The origin server returned an HTTP 5xx status code. This is most likely a problem with the origin server-side software, not the resizing.
-* 9412 — The origin server returned a non-image, for example, an HTML page. This usually happens when an invalid URL is specified or server-side software has printed an error or presented a login page.
-* 9413 — The image exceeds the maximum image area of 100 megapixels. Use a smaller image and try again.
-* 9420 — The origin server redirected to an invalid URL. Confirm settings at your origin and try again.
-* 9421 — The origin server redirected too many times. Confirm settings at your origin and try again.
-* 9422 - The transformation request is rejected because the usage limit was reached. If you need to request more than 5,000 unique transformations, upgrade to an Images Paid plan.
-* 9432 — The Images Binding is not available using legacy billing. Your account is using the legacy Image Resizing subscription. To bind Images to your Worker, you will need to update your plan to the Images subscription in the dashboard.
-* 9504, 9505, & 9510 — The origin server could not be contacted because the origin server may be down or overloaded. Try again later.
-* 9523 — The `/cdn-cgi/image/` resizing service could not perform resizing. This may happen when an image has invalid format. Use correctly formatted image and try again.
-* 9524 — The `/cdn-cgi/image/` resizing service could not perform resizing. This may happen when an image URL is intercepted by a Worker. As an alternative you can [resize within the Worker](/images/transform-images/transform-via-workers/). This can also happen when using a `pages.dev` URL of a [Cloudflare Pages](/pages/) project. In that case, you can use a [Custom Domain](/pages/configuration/custom-domains/) instead.
-* 9520 — The image format is not supported. Refer to [Supported formats and limitations](/images/transform-images/) to learn about supported input and output formats.
-* 9522 — The image exceeded the processing limit. This may happen briefly after purging an entire zone or when files with very large dimensions are requested. If the problem persists, contact support.
-* 9529 - The image timed out while processing. This may happen when files with very large dimensions are requested or the server is overloaded.
-* 9422, 9424, 9516, 9517, 9518, 9522 & 9523 — Internal errors. Please contact support if you encounter these errors.
-
-***
+- 9401 — The required arguments in `{cf:image{…}}` options are missing or are invalid. Try again. Refer to [Fetch options](/images/optimization/features/#parameters) for supported arguments.
+- 9402 — The image was too large or the connection was interrupted. Refer to [Supported formats and limitations](/images/get-started/limits/) for more information.
+- 9403 — A [request loop](/images/optimization/transformations/transform-via-workers/#prevent-request-loops) occurred because the image was already resized or the Worker fetched its own URL. Verify your Worker path and image path on the server do not overlap.
+- 9406 & 9419 — The image URL is a non-HTTPS URL or the URL has spaces or unescaped Unicode. Check your URL and try again.
+- 9407 — A lookup error occurred with the origin server's domain name. Check your DNS settings and try again.
+- 9404 — The image does not exist on the origin server or the URL used to resize the image is wrong. Verify the image exists and check the URL.
+- 9408 — The origin server returned an HTTP 4xx status code and may be denying access to the image. Confirm your image settings and try again.
+- 9509 — The origin server returned an HTTP 5xx status code. This is most likely a problem with the origin server-side software, not the resizing.
+- 9412 — The origin server returned a non-image, for example, an HTML page. This usually happens when an invalid URL is specified or server-side software has printed an error or presented a login page.
+- 9413 — The image exceeds the maximum image area of 100 megapixels. Use a smaller image and try again.
+- 9420 — The origin server redirected to an invalid URL. Confirm settings at your origin and try again.
+- 9421 — The origin server redirected too many times. Confirm settings at your origin and try again.
+- 9422 - The transformation request is rejected because the usage limit was reached. If you need to request more than 5,000 unique transformations, upgrade to an Images Paid plan.
+- 9432 — The Images Binding is not available using legacy billing. Your account is using the legacy Image Resizing subscription. To bind Images to your Worker, you will need to update your plan to the Images subscription in the dashboard.
+- 9504, 9505, & 9510 — The origin server could not be contacted because the origin server may be down or overloaded. Try again later.
+- 9523 — The `/cdn-cgi/image/` resizing service could not perform resizing. This may happen when an image has invalid format. Use correctly formatted image and try again.
+- 9524 — The `/cdn-cgi/image/` resizing service could not perform resizing. This may happen when an image URL is intercepted by a Worker. As an alternative you can [resize within the Worker](/images/optimization/transformations/transform-via-workers/). This can also happen when using a `pages.dev` URL of a [Cloudflare Pages](/pages/) project. In that case, you can use a [Custom Domain](/pages/configuration/custom-domains/) instead.
+- 9520 — The image format is not supported. Refer to [Supported formats and limitations](/images/get-started/limits/) to learn about supported input and output formats.
+- 9522 — The image exceeded the processing limit. This may happen briefly after purging an entire zone or when files with very large dimensions are requested. If the problem persists, contact support.
+- 9529 - The image timed out while processing. This may happen when files with very large dimensions are requested or the server is overloaded.
+- 9424, 9516, 9517, 9518 — Internal errors. Please contact support if you encounter these errors.
+
+---
## Limits
These are the limits for images that are stored outside of Images:
-* Maximum image size is 100 megapixels (for example, 10,000×10,000 pixels large). Maximum file size is 70 megabytes (MB). GIF/WebP animations are limited to 50 megapixels total (sum of sizes of all frames).
-* Image Resizing is not compatible with [Bring Your Own IP (BYOIP)](/byoip/).
-* When Polish can't optimize an image the Response Header `Warning: cf-images 299 "original is smaller"` is returned.
-***
+- Maximum image size is 100 megapixels (for example, 10,000×10,000 pixels large). Maximum file size is 100 megabytes (MB). GIF/WebP animations are limited to 50 megapixels total (sum of sizes of all frames).
+- [Bring Your Own IP (BYOIP)](/byoip/) is not compatible with Images when optimizing remote images (transformations).
+- When [Polish](/images/polish/) can't optimize an image the Response Header `Warning: cf-images 299 "original is smaller"` is returned.
+
+---
## Authorization and cookies are not supported
Image requests to the origin will be anonymized (no cookies, no auth, no custom headers). This is because we have to have one public cache for resized images, and it would be unsafe to share images that are personalized for individual visitors.
-However, in cases where customers agree to store such images in public cache, Cloudflare supports resizing images through Workers [on authenticated origins](/images/transform-images/transform-via-workers/).
+However, in cases where customers agree to store such images in public cache, Cloudflare supports resizing images through Workers [on authenticated origins](/images/optimization/transformations/transform-via-workers/).
-***
+---
## Caching and purging
@@ -71,6 +71,6 @@ Changes to image dimensions or other resizing options always take effect immedia
Image requests consists of two parts: running Worker code, and image processing. The Worker code is always executed and uncached. Results of image processing are cached for one hour or longer if origin server's `Cache-Control` header allows. Source image is cached using regular caching rules. Resizing follows redirects internally, so the redirects are cached too.
-Because responses from Workers themselves are not cached at the edge, purging of *Worker URLs* does nothing. Resized image variants are cached together under their source’s URL. When purging, use the (full-size) source image’s URL, rather than URLs of the Worker that requested resizing.
+Because responses from Workers themselves are not cached at the edge, purging of _Worker URLs_ does nothing. Resized image variants are cached together under their source’s URL. When purging, use the (full-size) source image’s URL, rather than URLs of the Worker that requested resizing.
If the origin server sends an `Etag` HTTP header, the resized images will have an `Etag` HTTP header that has a format `cf-:`. You can compare the second part with the `Etag` header of the source image URL to check if the resized image is up to date.
diff --git a/src/content/docs/images/storage/index.mdx b/src/content/docs/images/storage/index.mdx
new file mode 100644
index 00000000000..a9452732381
--- /dev/null
+++ b/src/content/docs/images/storage/index.mdx
@@ -0,0 +1,12 @@
+---
+pcx_content_type: navigation
+title: Storage
+sidebar:
+ order: 3
+ group:
+ hideIndex: true
+---
+
+import { DirectoryListing } from "~/components";
+
+
diff --git a/src/content/docs/images/manage-images/delete-images.mdx b/src/content/docs/images/storage/manage-images/delete-images.mdx
similarity index 88%
rename from src/content/docs/images/manage-images/delete-images.mdx
rename to src/content/docs/images/storage/manage-images/delete-images.mdx
index 798dc624a45..df6c9c23bb8 100644
--- a/src/content/docs/images/manage-images/delete-images.mdx
+++ b/src/content/docs/images/storage/manage-images/delete-images.mdx
@@ -11,9 +11,9 @@ You can delete an image from the Cloudflare Images storage using the dashboard o
## Delete images via the Cloudflare dashboard
-1. In the Cloudflare dashboard, go to **Transformations** page.
+1. In the Cloudflare dashboard, go to the **Hosted Images** page.
-
+
2. Find the image you want to remove and select **Delete**.
3. (Optional) To delete more than one image, select the checkbox next to the images you want to delete and then **Delete selected**.
diff --git a/src/content/docs/images/manage-images/edit-images.mdx b/src/content/docs/images/storage/manage-images/edit-images.mdx
similarity index 79%
rename from src/content/docs/images/manage-images/edit-images.mdx
rename to src/content/docs/images/storage/manage-images/edit-images.mdx
index a6c98026446..ac1543ee26b 100644
--- a/src/content/docs/images/manage-images/edit-images.mdx
+++ b/src/content/docs/images/storage/manage-images/edit-images.mdx
@@ -15,8 +15,8 @@ The Edit option provides you available options to modify a specific image. After
To edit an image:
-1. In the Cloudflare dashboard, go to the **Transformations** page.
+1. In the Cloudflare dashboard, go to the **Hosted Images** page.
-
+
2. Locate the image you want to modify and select **Edit**.
diff --git a/src/content/docs/images/manage-images/export-images.mdx b/src/content/docs/images/storage/manage-images/export-images.mdx
similarity index 85%
rename from src/content/docs/images/manage-images/export-images.mdx
rename to src/content/docs/images/storage/manage-images/export-images.mdx
index cdf6de1b144..96556b2b0d1 100644
--- a/src/content/docs/images/manage-images/export-images.mdx
+++ b/src/content/docs/images/storage/manage-images/export-images.mdx
@@ -11,9 +11,9 @@ Cloudflare Images supports image exports via the Cloudflare dashboard and API wh
## Export images via the Cloudflare dashboard
-1. In the Cloudflare dashboard, go to the **Transformations** page.
+1. In the Cloudflare dashboard, go to the **Hosted Images** page.
-
+
2. Find the image or images you want to export.
3. To export a single image, select **Export** from its menu. To export several images, select the checkbox next to each image and then select **Export selected**.
diff --git a/src/content/docs/images/storage/manage-images/index.mdx b/src/content/docs/images/storage/manage-images/index.mdx
new file mode 100644
index 00000000000..16b7501b951
--- /dev/null
+++ b/src/content/docs/images/storage/manage-images/index.mdx
@@ -0,0 +1,12 @@
+---
+pcx_content_type: navigation
+title: Manage hosted images
+sidebar:
+ order: 2
+ group:
+ hideIndex: true
+---
+
+import { DirectoryListing } from "~/components";
+
+
diff --git a/src/content/docs/images/manage-images/configure-webhooks.mdx b/src/content/docs/images/storage/upload-images/configure-webhooks.mdx
similarity index 92%
rename from src/content/docs/images/manage-images/configure-webhooks.mdx
rename to src/content/docs/images/storage/upload-images/configure-webhooks.mdx
index 78535f122fe..5b753adeba5 100644
--- a/src/content/docs/images/manage-images/configure-webhooks.mdx
+++ b/src/content/docs/images/storage/upload-images/configure-webhooks.mdx
@@ -1,16 +1,19 @@
---
pcx_content_type: how-to
title: Configure webhooks
+sidebar:
+ order: 8
---
+
import { DashButton } from "~/components";
You can set up webhooks to receive notifications about your upload workflow. This will send an HTTP POST request to a specified endpoint when an image either successfully uploads or fails to upload.
-Currently, webhooks are supported only for [direct creator uploads](/images/upload-images/direct-creator-upload/).
+Currently, webhooks are supported only for [direct creator uploads](/images/storage/upload-images/direct-creator-upload/).
To receive notifications for direct creator uploads:
-1. In the Cloudflare dashboard, go to the **Notifications** pages.
+1. In the Cloudflare dashboard, go to the **Notifications** pages.
diff --git a/src/content/docs/images/upload-images/direct-creator-upload.mdx b/src/content/docs/images/storage/upload-images/direct-creator-upload.mdx
similarity index 62%
rename from src/content/docs/images/upload-images/direct-creator-upload.mdx
rename to src/content/docs/images/storage/upload-images/direct-creator-upload.mdx
index dece555f4d3..5f3c0d9f6c1 100644
--- a/src/content/docs/images/upload-images/direct-creator-upload.mdx
+++ b/src/content/docs/images/storage/upload-images/direct-creator-upload.mdx
@@ -2,20 +2,19 @@
pcx_content_type: how-to
title: Accept user-uploaded images
sidebar:
- order: 5
-
+ order: 4
---
The Direct Creator Upload feature in Cloudflare Images lets your users upload images with a one-time upload URL without exposing your API key or token to the client. Using a direct creator upload also eliminates the need for an intermediary storage bucket and the storage/egress costs associated with it.
-You can set up [webhooks](/images/manage-images/configure-webhooks/) to receive notifications on your direct creator upload workflow.
+You can set up [webhooks](/images/storage/upload-images/configure-webhooks/) to receive notifications on your direct creator upload workflow.
## Request a one-time upload URL
Make a `POST` request to the `direct_upload` endpoint using the example below as reference.
:::note
-The `metadata` included in the request is never shared with end users.
+The `metadata` included in the request is never shared with end-users.
:::
```bash
@@ -30,14 +29,14 @@ After a successful request, you will receive a response similar to the example b
```json
{
- "result": {
- "id": "2cdc28f0-017a-49c4-9ed7-87056c83901",
- "uploadURL": "https://upload.imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/2cdc28f0-017a-49c4-9ed7-87056c83901"
- },
- "result_info": null,
- "success": true,
- "errors": [],
- "messages": []
+ "result": {
+ "id": "2cdc28f0-017a-49c4-9ed7-87056c83901",
+ "uploadURL": "https://upload.imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/2cdc28f0-017a-49c4-9ed7-87056c83901"
+ },
+ "result_info": null,
+ "success": true,
+ "errors": [],
+ "messages": []
}
```
@@ -56,22 +55,22 @@ After a successful request, you should receive a response similar to the example
```json
{
- "result": {
- "id": "2cdc28f0-017a-49c4-9ed7-87056c83901",
- "metadata": {
- "key": "value"
- },
- "uploaded": "2022-01-31T16:39:28.458Z",
- "requireSignedURLs": true,
- "variants": [
- "https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/2cdc28f0-017a-49c4-9ed7-87056c83901/public",
- "https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/2cdc28f0-017a-49c4-9ed7-87056c83901/thumbnail"
- ],
- "draft": true
- },
- "success": true,
- "errors": [],
- "messages": []
+ "result": {
+ "id": "2cdc28f0-017a-49c4-9ed7-87056c83901",
+ "metadata": {
+ "key": "value"
+ },
+ "uploaded": "2022-01-31T16:39:28.458Z",
+ "requireSignedURLs": true,
+ "variants": [
+ "https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/2cdc28f0-017a-49c4-9ed7-87056c83901/public",
+ "https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/2cdc28f0-017a-49c4-9ed7-87056c83901/thumbnail"
+ ],
+ "draft": true
+ },
+ "success": true,
+ "errors": [],
+ "messages": []
}
```
@@ -82,16 +81,16 @@ Below is an example of an HTML page that takes a one-time upload URL and uploads
```html
-
-
-
+
+
+
```
@@ -105,7 +104,7 @@ The expiry value must be a minimum of two minutes and maximum of six hours in th
## Direct Creator Upload with custom ID
-You can specify a [custom ID](/images/upload-images/upload-custom-path/) when you first request a one-time upload URL, instead of using the automatically generated ID for your image. Note that images with a custom ID cannot be made private with the [signed URL tokens](/images/manage-images/serve-images/serve-private-images) feature (`--requireSignedURLs=true`).
+You can specify a [custom ID](/images/storage/upload-images/upload-custom-path/) when you first request a one-time upload URL, instead of using the automatically generated ID for your image. Note that images with a custom ID cannot be made private with the [signed URL tokens](/images/optimization/hosted-images/serve-private-images/) feature (`--requireSignedURLs=true`).
To specify a custom ID, pass a form field with the name ID and corresponding custom ID value as shown in the example below.
diff --git a/src/content/docs/images/upload-images/images-batch.mdx b/src/content/docs/images/storage/upload-images/images-batch.mdx
similarity index 99%
rename from src/content/docs/images/upload-images/images-batch.mdx
rename to src/content/docs/images/storage/upload-images/images-batch.mdx
index a912368d8ce..89b6e9b34bc 100644
--- a/src/content/docs/images/upload-images/images-batch.mdx
+++ b/src/content/docs/images/storage/upload-images/images-batch.mdx
@@ -1,6 +1,8 @@
---
pcx_content_type: reference
title: Upload via batch API
+sidebar:
+ order: 5
---
The Images batch API lets you make several requests in sequence while bypassing Cloudflare’s global API rate limits.
diff --git a/src/content/docs/images/storage/upload-images/index.mdx b/src/content/docs/images/storage/upload-images/index.mdx
new file mode 100644
index 00000000000..bfe318fc6e5
--- /dev/null
+++ b/src/content/docs/images/storage/upload-images/index.mdx
@@ -0,0 +1,12 @@
+---
+pcx_content_type: navigation
+title: Upload images
+sidebar:
+ order: 1
+ group:
+ hideIndex: true
+---
+
+import { DirectoryListing } from "~/components";
+
+
diff --git a/src/content/docs/images/storage/upload-images/methods.mdx b/src/content/docs/images/storage/upload-images/methods.mdx
new file mode 100644
index 00000000000..a4c3c17938d
--- /dev/null
+++ b/src/content/docs/images/storage/upload-images/methods.mdx
@@ -0,0 +1,54 @@
+---
+pcx_content_type: concept
+title: Methods
+sidebar:
+ order: 1
+---
+
+Cloudflare gives you the option to [transform remote images](/images/optimization/transformations/overview), or upload into Images storage.
+
+If you have a [paid Images plan](/images/pricing#images-paid), you can upload an image using the following methods:
+
+- Upload directly through the dashboard. This is primarily used for one-off uploads.
+- Upload using API endpoints.
+- Import images from S3 using Sourcing Kit.
+
+---
+
+## Upload via dashboard
+
+To upload an image from the dashboard, follow these steps:
+
+1. Log in to the Cloudflare dashboard and select your account.
+2. Go to the **Images & Stream** → **Hosted images** tab.
+3. Drag and drop your image in the **Quick Upload** section. Alternatively, you can browse to select your image from your local disk.
+4. When your image successfully uploads, your image will appear in the list of files.
+
+## Upload using API
+
+Upload, manage, and delete hosted images from the Images API.
+
+The Images API endpoint uses the following format:
+
+```txt
+ https://api.cloudflare.com/client/v4/accounts//images/v1
+```
+
+When uploading through the API, you can use the following features:
+
+- Upload an image from your local machine or from [a URL](/images/storage/upload-images/upload-url).
+- Upload your image to a [custom ID path](/images/storage/upload-images/upload-custom-path/) rather than the path automatically generated by our Universal Unique Identifier (UUID).
+- The [Direct Creator API](/images/storage/upload-images/direct-creator-upload/) lets you accept image uploads from your users without exposing your API token.
+- The [Batch API](/images/storage/upload-images/images-batch/) returns a batch token that you can use to upload, manage, and delete images while bypassing Cloudflare’s global rate limits.
+
+## Import from S3
+
+Sourcing Kit is a data migration service that lets you copy objects from your Amazon S3 bucket to your Images storage.
+
+With Sourcing Kit, you can:
+
+- Define repositories of images to bulk import.
+- Reuse existing sources and import only new images, skipping any other images that were already imported.
+- Define target paths and prefixes for imported images.
+
+Learn more about [Sourcing Kit](/images/storage/upload-images/sourcing-kit).
diff --git a/src/content/docs/images/upload-images/sourcing-kit/credentials.mdx b/src/content/docs/images/storage/upload-images/sourcing-kit/credentials.mdx
similarity index 65%
rename from src/content/docs/images/upload-images/sourcing-kit/credentials.mdx
rename to src/content/docs/images/storage/upload-images/sourcing-kit/credentials.mdx
index fdfc08bd492..c0554ca115c 100644
--- a/src/content/docs/images/upload-images/sourcing-kit/credentials.mdx
+++ b/src/content/docs/images/storage/upload-images/sourcing-kit/credentials.mdx
@@ -3,7 +3,6 @@ pcx_content_type: how-to
title: Credentials
sidebar:
order: 10
-
---
To migrate images from Amazon S3, Sourcing Kit requires access permissions to your bucket. While you can use any AWS Identity and Access Management (IAM) user credentials with the correct permissions to create a Sourcing Kit source, Cloudflare recommends that you create a user with a narrow set of permissions.
@@ -16,23 +15,20 @@ To create the correct Sourcing Kit permissions:
```json
{
- "Version": "2012-10-17",
- "Statement": [
- {
- "Effect": "Allow",
- "Action": [
- "s3:Get*",
- "s3:List*"
- ],
- "Resource": [
- "arn:aws:s3:::",
- "arn:aws:s3:::/*"
- ]
- }
- ]
+ "Version": "2012-10-17",
+ "Statement": [
+ {
+ "Effect": "Allow",
+ "Action": ["s3:Get*", "s3:List*"],
+ "Resource": [
+ "arn:aws:s3:::",
+ "arn:aws:s3:::/*"
+ ]
+ }
+ ]
}
```
3. Next, create a new user and attach the created policy to that user.
-You can now use both the Access Key ID and Secret Access Key to create a new source in Sourcing Kit. Refer to [Enable Sourcing Kit](/images/upload-images/sourcing-kit/enable/) to learn more.
+You can now use both the Access Key ID and Secret Access Key to create a new source in Sourcing Kit. Refer to [Enable Sourcing Kit](/images/storage/upload-images/sourcing-kit/enable/) to learn more.
diff --git a/src/content/docs/images/upload-images/sourcing-kit/edit.mdx b/src/content/docs/images/storage/upload-images/sourcing-kit/edit.mdx
similarity index 100%
rename from src/content/docs/images/upload-images/sourcing-kit/edit.mdx
rename to src/content/docs/images/storage/upload-images/sourcing-kit/edit.mdx
diff --git a/src/content/docs/images/upload-images/sourcing-kit/enable.mdx b/src/content/docs/images/storage/upload-images/sourcing-kit/enable.mdx
similarity index 89%
rename from src/content/docs/images/upload-images/sourcing-kit/enable.mdx
rename to src/content/docs/images/storage/upload-images/sourcing-kit/enable.mdx
index fda0a6e2866..2fec3f75673 100644
--- a/src/content/docs/images/upload-images/sourcing-kit/enable.mdx
+++ b/src/content/docs/images/storage/upload-images/sourcing-kit/enable.mdx
@@ -19,7 +19,7 @@ Enabling Sourcing Kit will set it up with the necessary information to start imp
3. Select **Import images** to create an import job.
4. In **Source name** give your source an appropriate name.
5. In **Amazon S3 bucket information** enter the S3's bucket name where your images are stored.
-6. In **Required credentials**, enter your Amazon S3 credentials. This is required to connect Cloudflare Images to your source and import your images. Refer to [Credentials](/images/upload-images/sourcing-kit/credentials/) to learn more about how to set up credentials.
+6. In **Required credentials**, enter your Amazon S3 credentials. This is required to connect Cloudflare Images to your source and import your images. Refer to [Credentials](/images/storage/upload-images/sourcing-kit/credentials/) to learn more about how to set up credentials.
7. Select **Next**.
8. In **Basic rules** define the Amazon S3 path to import your images from, and the path you want to copy your images to in your Cloudflare Images account. This is optional, and you can leave these fields blank.
9. On the same page, in **Overwrite images**, you need to choose what happens when the files in your source change. The recommended action is to copy the new images and overwrite the old ones on your Cloudflare Images account. You can also choose to skip the import, and keep what you already have on your Cloudflare Images account.
@@ -62,4 +62,4 @@ Repeat steps 8-11 in [Create your first import job](#create-your-first-import-jo
## Next steps
-Refer to [Edit source details](/images/upload-images/sourcing-kit/edit/) to learn more about editing details for import jobs you have already created, or to learn how to abort running import jobs.
+Refer to [Edit source details](/images/storage/upload-images/sourcing-kit/edit/) to learn more about editing details for import jobs you have already created, or to learn how to abort running import jobs.
diff --git a/src/content/docs/images/upload-images/sourcing-kit/index.mdx b/src/content/docs/images/storage/upload-images/sourcing-kit/index.mdx
similarity index 87%
rename from src/content/docs/images/upload-images/sourcing-kit/index.mdx
rename to src/content/docs/images/storage/upload-images/sourcing-kit/index.mdx
index 835169453b9..91bbacd9156 100644
--- a/src/content/docs/images/upload-images/sourcing-kit/index.mdx
+++ b/src/content/docs/images/storage/upload-images/sourcing-kit/index.mdx
@@ -2,8 +2,7 @@
pcx_content_type: concept
title: Upload via Sourcing Kit
sidebar:
- order: 9
-
+ order: 6
---
With Sourcing Kit you can define one or multiple repositories of images to bulk import from Amazon S3. Once you have these set up, you can reuse those sources and import only new images to your Cloudflare Images account. This helps you make sure that only usable images are imported, and skip any other objects or files that might exist in that source.
@@ -14,5 +13,5 @@ Sourcing Kit also lets you target paths, define prefixes for imported images, an
Sourcing Kit can be a good choice if the Amazon S3 bucket you are importing consists primarily of images stored using non-archival storage classes, as images stored using [archival storage classes](https://aws.amazon.com/s3/storage-classes/#Archive) will be skipped and need to be imported separately. Specifically:
-* Images stored using S3 Glacier tiers (not including Glacier Instant Retrieval) will be skipped and logged in the migration log.
-* Images stored using S3 Intelligent Tiering and placed in Deep Archive tier will be skipped and logged in the migration log.
+- Images stored using S3 Glacier tiers (not including Glacier Instant Retrieval) will be skipped and logged in the migration log.
+- Images stored using S3 Intelligent Tiering and placed in Deep Archive tier will be skipped and logged in the migration log.
diff --git a/src/content/docs/images/upload-images/upload-URL.mdx b/src/content/docs/images/storage/upload-images/upload-URL.mdx
similarity index 55%
rename from src/content/docs/images/upload-images/upload-URL.mdx
rename to src/content/docs/images/storage/upload-images/upload-URL.mdx
index 81704186798..205cebc87d0 100644
--- a/src/content/docs/images/upload-images/upload-URL.mdx
+++ b/src/content/docs/images/storage/upload-images/upload-URL.mdx
@@ -2,18 +2,17 @@
pcx_content_type: how-to
title: Upload via URL
sidebar:
- order: 3
-
+ order: 2
---
-Before you upload an image, check the list of [supported formats and dimensions](/images/upload-images/#supported-image-formats) to confirm your image will be accepted.
+Before you upload an image, check the list of [supported formats and dimensions](/images/get-started/limits) to confirm your image will be accepted.
You can use the Images API to use a URL of an image instead of uploading the data.
Make a `POST` request using the example below as reference. Keep in mind that the `--form 'file='` and `--form 'url='` fields are mutually exclusive.
:::note
-The `metadata` included in the request is never shared with end users.
+The `metadata` included in the request is never shared with end-users.
:::
```bash
@@ -29,22 +28,22 @@ After successfully uploading the image, you will receive a response similar to t
```json
{
- "result": {
- "id": "2cdc28f0-017a-49c4-9ed7-87056c83901",
- "filename": "image.jpeg",
- "metadata": {
- "key": "value"
- },
- "uploaded": "2022-01-31T16:39:28.458Z",
- "requireSignedURLs": false,
- "variants": [
- "https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/2cdc28f0-017a-49c4-9ed7-87056c83901/public",
- "https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/2cdc28f0-017a-49c4-9ed7-87056c83901/thumbnail"
- ]
- },
- "success": true,
- "errors": [],
- "messages": []
+ "result": {
+ "id": "2cdc28f0-017a-49c4-9ed7-87056c83901",
+ "filename": "image.jpeg",
+ "metadata": {
+ "key": "value"
+ },
+ "uploaded": "2022-01-31T16:39:28.458Z",
+ "requireSignedURLs": false,
+ "variants": [
+ "https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/2cdc28f0-017a-49c4-9ed7-87056c83901/public",
+ "https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/2cdc28f0-017a-49c4-9ed7-87056c83901/thumbnail"
+ ]
+ },
+ "success": true,
+ "errors": [],
+ "messages": []
}
```
diff --git a/src/content/docs/images/upload-images/upload-custom-path.mdx b/src/content/docs/images/storage/upload-images/upload-custom-path.mdx
similarity index 54%
rename from src/content/docs/images/upload-images/upload-custom-path.mdx
rename to src/content/docs/images/storage/upload-images/upload-custom-path.mdx
index 15f3f0d8fa2..a2756ab5c0f 100644
--- a/src/content/docs/images/upload-images/upload-custom-path.mdx
+++ b/src/content/docs/images/storage/upload-images/upload-custom-path.mdx
@@ -2,21 +2,20 @@
pcx_content_type: how-to
title: Upload via custom path
sidebar:
- order: 4
-
+ order: 3
---
You can use a custom ID path to upload an image instead of the path automatically generated by Cloudflare Images’ Universal Unique Identifier (UUID).
Custom paths support:
-* Up to 1,024 characters.
-* Any number of subpaths.
-* The [UTF-8 encoding standard](https://en.wikipedia.org/wiki/UTF-8) for characters.
+- Up to 1,024 characters.
+- Any number of subpaths.
+- The [UTF-8 encoding standard](https://en.wikipedia.org/wiki/UTF-8) for characters.
:::note
-Images with custom ID paths cannot be made private using [signed URL tokens](/images/manage-images/serve-images/serve-private-images). Additionally, when [serving images](/images/manage-images/serve-images/), any `%` characters present in Custom IDs must be encoded to `%25` in the image delivery URLs.
+Images with custom ID paths cannot be made private using [signed URL tokens](/images/optimization/hosted-images/serve-private-images/). Additionally, when [serving images](/images/optimization/hosted-images/serve-uploaded-images/), any `%` characters present in Custom IDs must be encoded to `%25` in the image delivery URLs.
:::
Make a `POST` request using the example below as reference. You can use custom ID paths when you upload via a URL or with a direct file upload.
@@ -32,16 +31,18 @@ After successfully uploading the image, you will receive a response similar to t
```json
{
- "result": {
- "id": "",
- "filename": "",
- "uploaded": "2022-04-20T09:51:09.559Z",
- "requireSignedURLs": false,
- "variants": ["https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q//public"]
- },
- "result_info": null,
- "success": true,
- "errors": [],
- "messages": []
+ "result": {
+ "id": "",
+ "filename": "",
+ "uploaded": "2022-04-20T09:51:09.559Z",
+ "requireSignedURLs": false,
+ "variants": [
+ "https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q//public"
+ ]
+ },
+ "result_info": null,
+ "success": true,
+ "errors": [],
+ "messages": []
}
```
diff --git a/src/content/docs/images/upload-images/upload-file-worker.mdx b/src/content/docs/images/storage/upload-images/upload-file-worker.mdx
similarity index 98%
rename from src/content/docs/images/upload-images/upload-file-worker.mdx
rename to src/content/docs/images/storage/upload-images/upload-file-worker.mdx
index bbc041e6b46..e68b544c341 100644
--- a/src/content/docs/images/upload-images/upload-file-worker.mdx
+++ b/src/content/docs/images/storage/upload-images/upload-file-worker.mdx
@@ -2,6 +2,8 @@
pcx_content_type: how-to
title: Upload via a Worker
description: Learn how to upload images to Cloudflare using Workers. This guide provides code examples for uploading both standard and AI-generated images efficiently.
+sidebar:
+ order: 6
---
import { TypeScriptExample } from "~/components";
@@ -63,4 +65,3 @@ const response = await fetch(API_URL, {
```
-
diff --git a/src/content/docs/images/transform-images/index.mdx b/src/content/docs/images/transform-images/index.mdx
deleted file mode 100644
index aa4d5b61597..00000000000
--- a/src/content/docs/images/transform-images/index.mdx
+++ /dev/null
@@ -1,98 +0,0 @@
----
-pcx_content_type: concept
-title: Transform images
-sidebar:
- order: 5
----
-
-import { Render } from "~/components";
-
-Transformations let you optimize and manipulate images stored outside of the Cloudflare Images product. Transformed images are served from one of your zones on Cloudflare.
-
-To transform an image, you must [enable transformations for your zone](/images/get-started/#enable-transformations-on-your-zone).
-
-You can transform an image by using a [specially-formatted URL](/images/transform-images/transform-via-url/) or [through Workers](/images/transform-images/transform-via-workers/).
-
-Learn about [pricing and limits for image transformation](/images/pricing/).
-
-## Supported formats and limitations
-
-### Supported input formats
-
-- JPEG
-- PNG
-- GIF (including animations)
-- WebP (including animations)
-- SVG
-- HEIC
-
-:::note
-
-Cloudflare can ingest HEIC images for decoding, but they must be served in web-safe formats such as AVIF, WebP, JPG, or PNG.
-
-:::
-
-### Supported output formats
-
-- JPEG
-- PNG
-- GIF (including animations)
-- WebP (including animations)
-- SVG
-- AVIF
-
-### Supported features
-
-Transformations can:
-
-- Resize and generate JPEG and PNG images, and optionally AVIF or WebP.
-- Save animations as GIF or animated WebP.
-- Support ICC color profiles in JPEG and PNG images.
-- Preserve JPEG metadata (metadata of other formats is discarded).
-- Convert the first frame of GIF/WebP animations to a still image.
-
-
-
-### Format limitations
-
-Since some image formats require longer computational times than others, Cloudflare has to find a proper balance between the time it takes to generate an image and to transfer it over the Internet.
-
-Resizing requests might not be fulfilled with the format the user expects due to these trade-offs Cloudflare has to make. Images differ in size, transformations, codecs and all of these different aspects influence what compression codecs are used.
-
-Cloudflare tries to choose the requested codec, but we operate on a best-effort basis and there are limits that our system needs to follow to satisfy all customers.
-
-AVIF encoding, in particular, can be an order of magnitude slower than encoding to other formats. Cloudflare will fall back to WebP or JPEG if the image is too large to be encoded quickly.
-
-#### Limits per format
-
-Hard limits refers to the maximum image size to process. Soft limits refers to the limits existing when the system is overloaded.
-
-| File format | Hard limits on the longest side (width or height) | Soft limits on the longest side (width or height) |
-| ----------- | ------------------------------------------------- | ------------------------------------------------- |
-| AVIF | 1,200 pixels1 | 640 pixels |
-| Other | 12,000 pixels | N/A |
-| WebP | N/A | 2,560 pixels for lossy; 1920 pixels for lossless |
-
-1Hard limit is 1,600 pixels when `format=avif` is explicitly used
-with [image transformations](/images/transform-images/).
-
-All images have to be less than 70 MB. The maximum image area is limited to 100 megapixels (for example, 10,000 x 10,000 pixels large).
-
-GIF/WebP animations are limited to a total of 50 megapixels (the sum of sizes of all frames). Animations that exceed this will be passed through unchanged without applying any transformations. Note that GIF is an outdated format and has very inefficient compression. High-resolution animations will be slow to process and will have very large file sizes. For video clips, Cloudflare recommends using [video formats like MP4 and WebM instead](/stream/).
-
-:::caution[Important]
-
-SVG files are passed through without resizing. This format is inherently scalable and does not need resizing.
-
-AVIF format is supported on a best-effort basis. Images that cannot be compressed as AVIF will be served as WebP instead.
-
-:::
-
-#### Progressive JPEG
-
-While you can use the `format=jpeg` option to generate images in an interlaced progressive JPEG format, we will fallback to the baseline JPEG format for small and large images specified when:
-
-- The area calculated by width x height is less than 150 x 150.
-- The area calculated by width x height is greater than 3000 x 3000.
-
-For example, a 50 x 50 tiny image is always formatted by `baseline-jpeg` even if you specify progressive jpeg (`format=jpeg`).
diff --git a/src/content/docs/images/transform-images/transform-via-url.mdx b/src/content/docs/images/transform-images/transform-via-url.mdx
deleted file mode 100644
index 4341403b3dd..00000000000
--- a/src/content/docs/images/transform-images/transform-via-url.mdx
+++ /dev/null
@@ -1,174 +0,0 @@
----
-pcx_content_type: how-to
-title: Transform via URL
-sidebar:
- order: 1
----
-
-import { Render, Tabs, TabItem } from "~/components";
-
-You can convert and resize images by requesting them via a specially-formatted URL. This way you do not need to write any code, only change HTML markup of your website to use the new URLs. The format is:
-
-```txt
-https:///cdn-cgi/image//
-```
-
-Here is a breakdown of each part of the URL:
-
-- ``
- - Your domain name on Cloudflare. Unlike other third-party image resizing services, image transformations do not use a separate domain name for an API. Every Cloudflare zone with image transformations enabled can handle resizing itself. In URLs used on your website this part can be omitted, so that URLs start with `/cdn-cgi/image/`.
-
-- `/cdn-cgi/image/`
- - A fixed prefix that identifies that this is a special path handled by Cloudflare's built-in Worker.
-
-- ``
- - A comma-separated list of options such as `width`, `height`, and `quality`.
-
-- ``
- - An absolute path on the origin server, or an absolute URL (starting with `https://` or `http://`), pointing to an image to resize. The path is not URL-encoded, so the resizing URL can be safely constructed by concatenating `/cdn-cgi/image/options` and the original image URL. For example: `/cdn-cgi/image/width=100/https://s3.example.com/bucket/image.png`.
-
-Here is an example of an URL with `` set to `width=80,quality=75` and a `` of `uploads/avatar1.jpg`:
-
-```html
-
-```
-
-
-
-## Options
-
-You must specify at least one option. Options are comma-separated (spaces are not allowed anywhere). Names of options can be specified in full or abbreviated.
-
-### `anim`
-
-
-
-### `background`
-
-
-
-### `blur`
-
-
-
-### `border`
-
-
-
-### `brightness`
-
-
-
-### `compression`
-
-
-
-### `contrast`
-
-
-
-### `dpr`
-
-
-
-### `fit`
-
-
-
-### `flip`
-
-
-
-### `format`
-
-
-
-### `gamma`
-
-
-
-### `gravity`
-
-
-
-### `height`
-
-
-
-### `metadata`
-
-
-
-### `onerror`
-
-
-
-### `quality`
-
-
-
-### `rotate`
-
-
-
-### `saturation`
-
-
-
-### `segment`
-
-
-
-### `sharpen`
-
-
-
-### `slow-connection-quality`
-
-
-
-### `trim`
-
-
-
-### `width`
-
-
-
-### `zoom`
-
-
-
-## Recommended image sizes
-
-Ideally, image sizes should match exactly the size they are displayed on the page. If the page contains thumbnails with markup such as `![]()
`, then images should be resized to `width=200`. If the exact size is not known ahead of time, use the [responsive images technique](/images/manage-images/create-variants/).
-
-If you cannot use the `![]()
` markup, and have to hardcode specific maximum sizes, Cloudflare recommends the following sizes:
-
-- Maximum of 1920 pixels for desktop browsers.
-- Maximum of 960 pixels for tablets.
-- Maximum of 640 pixels for mobile phones.
-
-Here is an example of markup to configure a maximum size for your image:
-
-```txt
-/cdn-cgi/image/fit=scale-down,width=1920/
-```
-
-The `fit=scale-down` option ensures that the image will not be enlarged unnecessarily.
-
-You can detect device type by enabling the `CF-Device-Type` header [via Cache Rule](/cache/how-to/cache-rules/examples/cache-device-type/).
-
-## Caching
-
-Resizing causes the original image to be fetched from the origin server and cached — following the usual rules of HTTP caching, `Cache-Control` header, etc.. Requests for multiple different image sizes are likely to reuse the cached original image, without causing extra transfers from the origin server.
-
-:::note
-
-If Custom Cache Keys are used for the origin image, the origin image might not be cached and might result in more calls to the origin.
-
-:::
-
-Resized images follow the same caching rules as the original image they were resized from, except the minimum cache time is one hour. If you need images to be updated more frequently, add `must-revalidate` to the `Cache-Control` header. Resizing supports cache revalidation, so we recommend serving images with the `Etag` header. Refer to the [Cache docs for more information](/cache/concepts/cache-control/#revalidation).
-
-Cloudflare Images does not support purging resized variants individually. URLs starting with `/cdn-cgi/` cannot be purged. However, purging of the original image's URL will also purge all of its resized variants.
\ No newline at end of file
diff --git a/src/content/docs/images/tutorials/index.mdx b/src/content/docs/images/tutorials/index.mdx
index 5a3a0dca95f..6678624d537 100644
--- a/src/content/docs/images/tutorials/index.mdx
+++ b/src/content/docs/images/tutorials/index.mdx
@@ -9,4 +9,4 @@ sidebar:
import { DirectoryListing } from "~/components";
-
\ No newline at end of file
+
diff --git a/src/content/docs/images/tutorials/optimize-mobile-viewing.mdx b/src/content/docs/images/tutorials/optimize-mobile-viewing.mdx
index e5a88b2c39d..a888d29ff99 100644
--- a/src/content/docs/images/tutorials/optimize-mobile-viewing.mdx
+++ b/src/content/docs/images/tutorials/optimize-mobile-viewing.mdx
@@ -10,10 +10,11 @@ reviewed: 2025-07-07
You can use lazy loading to optimize the images on your webpages for mobile viewing. This helps address common challenges of mobile viewing, like slow network connections or weak processing capabilities.
Lazy loading has two main advantages:
-* **Faster page load times** — Images are loaded as the user scrolls down the page, instead of all at once when the page is opened.
-* **Lower costs for image delivery** — When using Cloudflare Images, you only pay to load images that the user actually sees. With lazy loading, images that are not scrolled into view do not count toward your billable Images requests.
-Lazy loading is natively supported on all Chromium-based browsers like Chrome, Safari, Firefox, Opera, and Edge.
+- **Faster page load times** — Images are loaded as the user scrolls down the page, instead of all at once when the page is opened.
+- **Lower costs for image delivery** — When using Cloudflare Images, you only pay to load images that the user actually sees. With lazy loading, images that are not scrolled into view do not count toward your billable Images requests.
+
+Lazy loading is natively supported on all major browsers, including Chrome, Safari, Firefox, Opera, and Edge.
:::note
If you use older methods, involving custom JavaScript or a JavaScript library, lazy loading may increase the initial load time of the page since the browser needs to download, parse, and execute JavaScript.
@@ -23,7 +24,7 @@ If you use older methods, involving custom JavaScript or a JavaScript library, l
Without modifying your loading attribute, most browsers will fetch all images on a page, prioritizing the images that are closest to the viewport by default. You can override this by modifying your `loading` attribute.
-There are two possible `loading` attributes for your `![]()
` tags: `lazy` and `eager`.
+There are two possible `loading` attributes for your `![]()
` tags: `lazy` and `eager`.
### Lazy loading
@@ -32,7 +33,7 @@ Lazy loading is recommended for most images. With Lazy loading, resources like i
Example of modifying the `loading` attribute of your `![]()
` tags to be `"lazy"`:
```html
-
+
```
### Eager loading
@@ -42,5 +43,5 @@ If you have images that are in the viewport, eager loading, instead of lazy load
Example of modifying the `loading` attribute of your `![]()
` tags to be `"eager"`:
```html
-
+
```
diff --git a/src/content/docs/images/tutorials/optimize-user-uploaded-image.mdx b/src/content/docs/images/tutorials/optimize-user-uploaded-image.mdx
index 18eb61cfb85..d5cfa17f9a7 100644
--- a/src/content/docs/images/tutorials/optimize-user-uploaded-image.mdx
+++ b/src/content/docs/images/tutorials/optimize-user-uploaded-image.mdx
@@ -33,7 +33,7 @@ If you are new, review how to [create your first Worker](/workers/get-started/gu
To start, you will need to set up your project to use the following resources on the Developer Platform:
-- [Images](/images/transform-images/bindings/) to transform, resize, and encode images directly from your Worker.
+- [Images](/images/optimization/transformations/bindings/) to transform, resize, and encode images directly from your Worker.
- [R2](/r2/api/workers/workers-api-usage/) to connect the bucket for storing transformed images.
- [Assets](/workers/static-assets/binding/) to access a static image that will be used as the visual watermark.
@@ -384,4 +384,4 @@ export default {
In this tutorial, you learned how to connect your Worker to various resources on the Developer Platform to build an app that accepts image uploads, transform images, and uploads the output to R2.
-Next, you can [set up a transformation URL](/images/transform-images/transform-via-url/) to dynamically optimize images that are stored in R2.
+Next, you can [set up a transformation URL](/images/optimization/features/#url-interface) to dynamically optimize images that are stored in R2.
diff --git a/src/content/docs/images/upload-images/index.mdx b/src/content/docs/images/upload-images/index.mdx
deleted file mode 100644
index 779ceb28707..00000000000
--- a/src/content/docs/images/upload-images/index.mdx
+++ /dev/null
@@ -1,38 +0,0 @@
----
-pcx_content_type: concept
-title: Upload images
-sidebar:
- order: 3
-
----
-
-Cloudflare Images allows developers to upload images using different methods, for a wide range of use cases.
-
-## Supported image formats
-
-You can upload the following image formats to Cloudflare Images:
-
-* PNG
-* GIF (including animations)
-* JPEG
-* WebP (Cloudflare Images also supports uploading animated WebP files)
-* SVG
-* HEIC
-
-:::note
-
-
-Cloudflare can ingest HEIC images for decoding, but they must be served in web-safe formats such as AVIF, WebP, JPG, or PNG.
-
-
-:::
-
-## Dimensions and sizes
-
-These are the maximum allowed sizes and dimensions when uploading to Images:
-
-* Maximum image dimension is 12,000 pixels.
-* Maximum image area is limited to 100 megapixels (for example, 10,000×10,000 pixels).
-* Image metadata is limited to 1024 bytes (when uploaded and stored in Cloudflare).
-* Images have a 10 megabyte (MB) size limit (when uploaded and stored in Cloudflare).
-* Animated GIFs/WebP, including all frames, are limited to 50 megapixels (MP).
diff --git a/src/content/docs/images/upload-images/upload-dashboard.mdx b/src/content/docs/images/upload-images/upload-dashboard.mdx
deleted file mode 100644
index fc719c9e4ab..00000000000
--- a/src/content/docs/images/upload-images/upload-dashboard.mdx
+++ /dev/null
@@ -1,19 +0,0 @@
----
-pcx_content_type: how-to
-title: Upload via dashboard
-sidebar:
- order: 2
----
-
-import { DashButton } from "~/components";
-
-Before you upload an image, check the list of [supported formats and dimensions](/images/upload-images/#supported-image-formats) to confirm your image will be accepted.
-
-To upload an image from the Cloudflare dashboard:
-
-1. In the Cloudflare dashboard, go to the **Transformations** page.
-
-
-
-2. Drag and drop your image into the **Quick Upload** section. Alternatively, you can select **Drop images here** or browse to select your image locally.
-3. After the upload finishes, your image appears in the list of files.
diff --git a/src/content/docs/reference-architecture/architectures/cdn.mdx b/src/content/docs/reference-architecture/architectures/cdn.mdx
index c54c1d88496..ce9e49d113f 100644
--- a/src/content/docs/reference-architecture/architectures/cdn.mdx
+++ b/src/content/docs/reference-architecture/architectures/cdn.mdx
@@ -231,7 +231,7 @@ When combined with Tiered Caching and Argo Smart Routing, Cache Reserve can be a
:::note
-Using [Image Resizing](/images/transform-images/) with Cache Reserve will not result in resized images being stored in Cache Reserve since Image Resizing takes place after reading from Cache Reserve. Resized images will be cached in other available tiers when they are served after resizing.
+Using [Image Resizing](/images/optimization/transformations/overview/) with Cache Reserve will not result in resized images being stored in Cache Reserve since Image Resizing takes place after reading from Cache Reserve. Resized images will be cached in other available tiers when they are served after resizing.
:::
diff --git a/src/content/docs/reference-architecture/diagrams/content-delivery/distributed-web-performance-architecture.mdx b/src/content/docs/reference-architecture/diagrams/content-delivery/distributed-web-performance-architecture.mdx
index fe046f16562..dba07003b95 100644
--- a/src/content/docs/reference-architecture/diagrams/content-delivery/distributed-web-performance-architecture.mdx
+++ b/src/content/docs/reference-architecture/diagrams/content-delivery/distributed-web-performance-architecture.mdx
@@ -95,8 +95,8 @@ The performance journey begins at the client's device. Device hardware, [browser
Once the request reaches the network edge, Cloudflare processes and optimizes the content before it is served or fetched from the cache.
- **Traffic Management:** The request is inspected. [URL Normalization](/rules/normalization/) ensures consistency, while [Redirect Rules](/rules/url-forwarding/) or [Transform Rules](/rules/transform/) handle path modifications efficiently. [Waiting Room](/waiting-room/) protects the backend during [massive traffic surges](/learning-paths/surge-readiness/concepts/), maintaining availability.
-- **Programmatic Customization:** For advanced use cases where standard rules are insufficient, [Snippets and Workers](/rules/snippets/when-to-use/) allow for programmatic customization. This enables executing custom code logic to modify headers, rewrite URLs, [image optimizations](/images/transform-images/transform-via-workers/), or implement unique caching logic directly at the edge. Utilize [Service Bindings](/workers/runtime-apis/bindings/service-bindings/) to facilitate low-latency, zero-overhead communication between these Workers.
-- **Content Optimization:** Text assets are compressed using [Compression Rules](/rules/compression-rules/) (Brotli/Gzip). Images are processed on-the-fly via [Image Transformations](/images/transform-images/) or [Polish](/images/polish/) to ensure they are served in the optimal format (AVIF/WebP) and size for the device, significantly improving LCP and CLS.
+- **Programmatic Customization:** For advanced use cases where standard rules are insufficient, [Snippets and Workers](/rules/snippets/when-to-use/) allow for programmatic customization. This enables executing custom code logic to modify headers, rewrite URLs, [image optimizations](/images/optimization/transformations/transform-via-workers/), or implement unique caching logic directly at the edge. Utilize [Service Bindings](/workers/runtime-apis/bindings/service-bindings/) to facilitate low-latency, zero-overhead communication between these Workers.
+- **Content Optimization:** Text assets are compressed using [Compression Rules](/rules/compression-rules/) (Brotli/Gzip). Images are processed on-the-fly via [Image Transformations](/images/optimization/transformations/overview/) or [Polish](/images/polish/) to ensure they are served in the optimal format (AVIF/WebP) and size for the device, significantly improving LCP and CLS.
- **Font & Tag Optimization:** [Cloudflare Fonts](/speed/optimization/content/fonts/) eliminates DNS lookups and TLS connections to Google Fonts by serving them inline from the domain. [Google Tag Gateway](/google-tag-gateway/) improves ad signal measurement and privacy.
- **Routing, Availability & Protocol Intelligence:** Cloudflare operates one of the most [interconnected networks](https://blog.cloudflare.com/network-performance-update-birthday-week-2025/) in the world, peering with over 13,000 networks, operating a [global backbone](https://blog.cloudflare.com/backbone2024/), and participating in a leading number of [Internet Exchange Points (IXPs)](https://bgp.he.net/report/exchanges#_participants) globally. We leverage the [unique intelligence](https://blog.cloudflare.com/how-cloudflare-uses-the-worlds-greatest-collection-of-performance-data/) derived from this massive dataset to dynamically optimize Congestion Control (CC) at the protocol level - automatically selecting the optimal algorithm and tuning adequate parameters for every connection based on real-time network conditions. For dynamic requests that cannot be cached, [Argo Smart Routing](/argo-smart-routing/) finds the fastest path through the network to the origin. [Custom Errors](/rules/custom-errors/) provide a consistent brand experience during failures.
diff --git a/src/content/docs/reference-architecture/diagrams/content-delivery/optimizing-image-delivery-with-cloudflare-image-resizing-and-r2.mdx b/src/content/docs/reference-architecture/diagrams/content-delivery/optimizing-image-delivery-with-cloudflare-image-resizing-and-r2.mdx
index e7501f2098e..9f3c10c9e34 100644
--- a/src/content/docs/reference-architecture/diagrams/content-delivery/optimizing-image-delivery-with-cloudflare-image-resizing-and-r2.mdx
+++ b/src/content/docs/reference-architecture/diagrams/content-delivery/optimizing-image-delivery-with-cloudflare-image-resizing-and-r2.mdx
@@ -45,7 +45,7 @@ https://www.mywebsite.com/cdn-cgi/image/width=80,quality=75/uploads/image.jpg
## Related Resources
-- [Image Resizing Documentation](/images/transform-images/)
+- [Image Resizing Documentation](/images/optimization/transformations/overview/)
- [Cloudflare R2 Developer Docs](/r2/)
- [URL Rewrite Rules](/rules/transform/url-rewrite/)
- [Serverless image content management platform](/reference-architecture/diagrams/serverless/serverless-image-content-management/)
diff --git a/src/content/docs/reference-architecture/diagrams/serverless/serverless-image-content-management.mdx b/src/content/docs/reference-architecture/diagrams/serverless/serverless-image-content-management.mdx
index 3e33274e72c..ee902e002c9 100644
--- a/src/content/docs/reference-architecture/diagrams/serverless/serverless-image-content-management.mdx
+++ b/src/content/docs/reference-architecture/diagrams/serverless/serverless-image-content-management.mdx
@@ -39,7 +39,7 @@ The ultimate goal is to create a scalable and accessible platform for storing an
### 1. Image servicing
-Clients request images with [HMAC signatures](/workers/examples/signing-requests/) and any necessary transformations. Transformation parameters can be included in the [src-set](/images/transform-images/make-responsive-images/#srcset-for-high-dpi-displays) for HTML content or directly sent alongside [HTTP requests](/images/transform-images/transform-via-url/).
+Clients request images with [HMAC signatures](/workers/examples/signing-requests/) and any necessary transformations. Transformation parameters can be included in the [src-set](/images/optimization/make-responsive-images/#srcset-for-high-dpi-displays) for HTML content or directly sent alongside [HTTP requests](/images/optimization/features/).
### 2. Volumetric protection
diff --git a/src/content/docs/rules/snippets/when-to-use.mdx b/src/content/docs/rules/snippets/when-to-use.mdx
index c6df30a9570..91913469920 100644
--- a/src/content/docs/rules/snippets/when-to-use.mdx
+++ b/src/content/docs/rules/snippets/when-to-use.mdx
@@ -80,7 +80,7 @@ Snippets are ideal for fast, cost-free request and response modifications at the
| Route traffic dynamically between [origin servers](/rules/snippets/examples/serve-different-origin/) | ✅ | ✅ |
| [Authenticate](/rules/snippets/examples/auth-with-headers/) requests, [pre-sign](/cache/interaction-cloudflare-products/waf-snippets/) URLs, run [A/B testing](/rules/snippets/examples/ab-testing-same-url/) | ✅ | ✅ |
| Define logic using [JavaScript and Web APIs](/workers/languages/javascript/) | ✅ | ✅ |
-| Perform compute-heavy tasks (for example, [AI](/workers-ai/), [image transformations](/images/transform-images/transform-via-workers/)) | ❌ | ✅ |
+| Perform compute-heavy tasks (for example, [AI](/workers-ai/), [image transformations](/images/optimization/transformations/transform-via-workers/)) | ❌ | ✅ |
| Store persistent data (for example, [KV](/kv/), [Durable Objects](/durable-objects/), and [D1](/d1/)) | ❌ | ✅ |
| Build [APIs](/d1/tutorials/build-a-comments-api/) and [full-stack applications](/pages/framework-guides/deploy-an-astro-site/#video-tutorial) | ❌ | ✅ |
| Use TypeScript, Python, Rust, or other programming [languages](/workers/languages/) | ❌ | ✅ |
@@ -555,7 +555,7 @@ You should migrate from Snippets to Workers if your logic:
- Performs compute-intensive operations, including:
- [AI inference](/workers-ai/)
- [Vector search](/vectorize/)
- - [Image transformations](/images/transform-images/transform-via-workers/)
+ - [Image transformations](/images/optimization/transformations/transform-via-workers/)
- Interacts with Cloudflare's [Developer Platform](/learning-paths/workers/devplat/intro-to-devplat/).
- Requires [unit testing](/workers/testing/).
- Needs deployment automation via CLI ([Wrangler](/workers/wrangler/)).
diff --git a/src/content/docs/rules/transform/url-rewrite/index.mdx b/src/content/docs/rules/transform/url-rewrite/index.mdx
index 071302ae534..102afef1cb6 100644
--- a/src/content/docs/rules/transform/url-rewrite/index.mdx
+++ b/src/content/docs/rules/transform/url-rewrite/index.mdx
@@ -40,7 +40,7 @@ Create URL Rewrite Rules [in the dashboard](/rules/transform/url-rewrite/create-
## Serve images from custom paths
-When using Cloudflare Images, you can use URL Rewrite Rules to serve images from a custom path. For more information, refer to [Serve images from custom domains](/images/manage-images/serve-images/serve-from-custom-domains/).
+When using Cloudflare Images, you can use URL Rewrite Rules to serve images from a custom path. For more information, refer to [Serve images from custom domains](/images/optimization/hosted-images/serve-from-custom-domains/).
-
+
Transform images on Cloudflare's edge platform: resize, adjust quality, and convert images to WebP or AVIF format on demand.
diff --git a/src/content/docs/speed/optimization/images/image-resizing.mdx b/src/content/docs/speed/optimization/images/image-resizing.mdx
index e2738894a71..e2be2bd132f 100644
--- a/src/content/docs/speed/optimization/images/image-resizing.mdx
+++ b/src/content/docs/speed/optimization/images/image-resizing.mdx
@@ -1,7 +1,7 @@
---
pcx_content_type: navigation
title: Image Resizing
-external_link: /images/transform-images/
+external_link: /images/optimization/transformations/overview/
sidebar:
order: 2
diff --git a/src/content/docs/speed/optimization/images/mirage.mdx b/src/content/docs/speed/optimization/images/mirage.mdx
index a69a31c5d37..3e4e003ba11 100644
--- a/src/content/docs/speed/optimization/images/mirage.mdx
+++ b/src/content/docs/speed/optimization/images/mirage.mdx
@@ -15,7 +15,7 @@ sidebar:
:::caution[Deprecation notice]
Mirage was deprecated on September 15, 2025 and is no longer available.
-As an alternative, Cloudflare recommends using [lazy loading](/images/tutorials/optimize-mobile-viewing/) and [responsive images](/images/transform-images/make-responsive-images/) to optimize image performance for all devices.
+As an alternative, Cloudflare recommends using [lazy loading](/images/tutorials/optimize-mobile-viewing/) and [responsive images](/images/optimization/make-responsive-images/) to optimize image performance for all devices.
:::
## What was Mirage?
@@ -41,6 +41,6 @@ Modern web standards and browser capabilities have evolved to provide native sup
Instead of Mirage, use:
- **[Polish](/images/polish/)** - Seamlessly optimizes images for all browsers, not only mobile, and keeps images at full resolution.
-- **[Image Resizing](/images/transform-images/)** - Combined with `loading="lazy"` and `srcset` HTML attributes, provides modern responsive image delivery.
+- **[Image Resizing](/images/optimization/transformations/overview/)** - Combined with `loading="lazy"` and `srcset` HTML attributes, provides modern responsive image delivery.
- **[Lazy loading guide](/images/tutorials/optimize-mobile-viewing/)** - Learn how to implement native lazy loading.
-- **[Responsive images guide](/images/transform-images/make-responsive-images/)** - Create images that adapt to different devices.
+- **[Responsive images guide](/images/optimization/make-responsive-images/)** - Create images that adapt to different devices.
diff --git a/src/content/docs/stream/transform-videos/bindings.mdx b/src/content/docs/stream/transform-videos/bindings.mdx
index 145fdc24b36..0dcb3625d38 100644
--- a/src/content/docs/stream/transform-videos/bindings.mdx
+++ b/src/content/docs/stream/transform-videos/bindings.mdx
@@ -49,7 +49,7 @@ Within your Worker code, you can interact with this binding by using `env.MEDIA.
## Methods
-The Media Transformations binding is similar to the [Images binding](/images/transform-images/bindings/), except the method chain order is fixed and the result of an `input()` cannot be reused across multiple transformations.
+The Media Transformations binding is similar to the [Images binding](/images/optimization/transformations/bindings/), except the method chain order is fixed and the result of an `input()` cannot be reused across multiple transformations.
### `.input()`
diff --git a/src/content/docs/tenant/reference/subscriptions.mdx b/src/content/docs/tenant/reference/subscriptions.mdx
index aa4bc2026af..10cff7cae0f 100644
--- a/src/content/docs/tenant/reference/subscriptions.mdx
+++ b/src/content/docs/tenant/reference/subscriptions.mdx
@@ -42,7 +42,7 @@ The following table lists sample values for various Developer platform subscript
| Feature | Subscription IDs |
| -------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [Images](/images/) | `IMAGES_ENT`,`IMAGES_BASIC` |
-| [Image transformations](/images/transform-images/) | `IMAGE_RESIZING_ENT`, `IMAGE_RESIZING_BASIC` |
+| [Image transformations](/images/optimization/transformations/overview/) | `IMAGE_RESIZING_ENT`, `IMAGE_RESIZING_BASIC` |
| [Stream](/stream/) | `PARTNERS_STREAM_ENT`, `PARTNERS_STREAM_BASIC`, `STREAM_BASIC` |
| [Workers](/workers) | `PARTNERS_WORKERS_ENT`, `WORKERS_PAID`, `PARTNERS_WORKERS_SS`, `PARTNERS_WORKERS_BASIC` |
diff --git a/src/content/docs/use-cases/media-streaming/image-optimization.mdx b/src/content/docs/use-cases/media-streaming/image-optimization.mdx
index d990bdd3f03..43fff97d662 100644
--- a/src/content/docs/use-cases/media-streaming/image-optimization.mdx
+++ b/src/content/docs/use-cases/media-streaming/image-optimization.mdx
@@ -28,4 +28,4 @@ Automatic image compression without quality loss. [Learn more about Polish](/ima
1. [Images get started](/images/get-started/)
2. [Enable Polish](/images/polish/)
-3. [Transform images via URL](/images/transform-images/)
+3. [Transform images via URL](/images/optimization/transformations/overview/)
diff --git a/src/content/docs/use-cases/media-streaming/index.mdx b/src/content/docs/use-cases/media-streaming/index.mdx
index f5979772434..e23add746e1 100644
--- a/src/content/docs/use-cases/media-streaming/index.mdx
+++ b/src/content/docs/use-cases/media-streaming/index.mdx
@@ -48,13 +48,13 @@ Handle media uploads from users at scale:
### Create a new application
- A [Cloudflare account](https://dash.cloudflare.com/sign-up). Stream and R2 are account-level offerings. You do not need a domain added to Cloudflare to upload, encode, or store media.
-- For Image Transformations: enable the feature per domain from the [Transformations page](https://dash.cloudflare.com/?to=/:account/images/transformations) in the dashboard. Refer to [Image Transformations](/images/transform-images/).
+- For Image Transformations: enable the feature per domain from the [Transformations page](https://dash.cloudflare.com/?to=/:account/images/transformations) in the dashboard. Refer to [Image Transformations](/images/optimization/transformations/overview/).
### Use an existing application
- A [Cloudflare account](https://dash.cloudflare.com/sign-up).
- A domain [added to Cloudflare](/fundamentals/manage-domains/add-site/) with DNS records proxied through Cloudflare. This is required for CDN caching, image optimization (Polish), and cache rules.
-- For Image Transformations on an existing domain: enable the feature from the [Transformations page](https://dash.cloudflare.com/?to=/:account/images/transformations) in the dashboard. Refer to [Image Transformations](/images/transform-images/).
+- For Image Transformations on an existing domain: enable the feature from the [Transformations page](https://dash.cloudflare.com/?to=/:account/images/transformations) in the dashboard. Refer to [Image Transformations](/images/optimization/transformations/overview/).
---
diff --git a/src/content/docs/workers/development-testing/index.mdx b/src/content/docs/workers/development-testing/index.mdx
index 0dbcbaff341..0f7921d78b4 100644
--- a/src/content/docs/workers/development-testing/index.mdx
+++ b/src/content/docs/workers/development-testing/index.mdx
@@ -212,7 +212,7 @@ To verify that the certificate exchange and validation process work as expected.
#### [Images](/workers/wrangler/configuration/#images):
-To connect to a high-fidelity version of the Images API, and verify that all transformations work as expected. Local simulation for Cloudflare Images is [limited with only a subset of features](/images/transform-images/bindings/#interact-with-your-images-binding-locally).
+To connect to a high-fidelity version of the Images API, and verify that all transformations work as expected. Local simulation for Cloudflare Images is [limited with only a subset of features](/images/optimization/transformations/bindings/#interact-with-your-images-binding-locally).
```jsonc title="wrangler.jsonc"
diff --git a/src/content/docs/workers/observability/traces/spans-and-attributes.mdx b/src/content/docs/workers/observability/traces/spans-and-attributes.mdx
index 86c3addf720..5276a84e5a8 100644
--- a/src/content/docs/workers/observability/traces/spans-and-attributes.mdx
+++ b/src/content/docs/workers/observability/traces/spans-and-attributes.mdx
@@ -513,9 +513,9 @@ The legacy KV-backed API allows you to modify embedded storage within a Durable
---
-### [Images](/images/transform-images/bindings/)
+### [Images](/images/optimization/transformations/bindings/)
-### [`images_output`](/images/transform-images/bindings/#output)
+### [`images_output`](/images/optimization/transformations/bindings/#output)
- `cloudflare.binding.type`
- `cloudflare.images.options.format`
@@ -525,7 +525,7 @@ The legacy KV-backed API allows you to modify embedded storage within a Durable
- `cloudflare.images.options.transforms`
- `cloudflare.images.error.code`
-### [`images_info`](/images/transform-images/bindings/#info)
+### [`images_info`](/images/optimization/transformations/bindings/#info)
- `cloudflare.binding.type`
- `cloudflare.images.options.encoding`
diff --git a/src/content/docs/workers/platform/limits.mdx b/src/content/docs/workers/platform/limits.mdx
index 7ed884164eb..3b39674f46e 100644
--- a/src/content/docs/workers/platform/limits.mdx
+++ b/src/content/docs/workers/platform/limits.mdx
@@ -353,7 +353,7 @@ Refer to the [Workers Trace Event Logpush documentation](/workers/observability/
## Image Resizing with Workers
-Refer to the [Image Resizing documentation](/images/transform-images/) for limits that apply when using Image Resizing with Workers.
+Refer to the [Image Resizing documentation](/images/optimization/transformations/overview/) for limits that apply when using Image Resizing with Workers.
---
diff --git a/src/content/docs/workers/reference/migrate-to-module-workers.mdx b/src/content/docs/workers/reference/migrate-to-module-workers.mdx
index 86d5fe2c4d6..5cc9a297b84 100644
--- a/src/content/docs/workers/reference/migrate-to-module-workers.mdx
+++ b/src/content/docs/workers/reference/migrate-to-module-workers.mdx
@@ -16,7 +16,7 @@ There are several reasons to migrate your Workers to the ES modules format:
1. Your Worker will run faster. With service workers, bindings are exposed as globals. This means that for every request, the Workers runtime must create a new JavaScript execution context, which adds overhead and time. Workers written using ES modules can reuse the same execution context across multiple requests.
2. Implementing [Durable Objects](/durable-objects/) requires Workers that use ES modules.
-3. Bindings for [D1](/d1/), [Workers AI](/workers-ai/), [Vectorize](/vectorize/), [Workflows](/workflows/), and [Images](/images/transform-images/bindings/) can only be used from Workers that use ES modules.
+3. Bindings for [D1](/d1/), [Workers AI](/workers-ai/), [Vectorize](/vectorize/), [Workflows](/workflows/), and [Images](/images/optimization/transformations/bindings/) can only be used from Workers that use ES modules.
4. You can [gradually deploy changes to your Worker](/workers/configuration/versions-and-deployments/gradual-deployments/) when you use the ES modules format.
5. You can easily publish Workers using ES modules to `npm`, allowing you to import and reuse Workers within your codebase.
diff --git a/src/content/docs/workers/runtime-apis/bindings/images.mdx b/src/content/docs/workers/runtime-apis/bindings/images.mdx
index 07940238d6a..a4c2e06ce6d 100644
--- a/src/content/docs/workers/runtime-apis/bindings/images.mdx
+++ b/src/content/docs/workers/runtime-apis/bindings/images.mdx
@@ -1,7 +1,7 @@
---
pcx_content_type: navigation
title: Images
-external_link: /images/transform-images/bindings/
+external_link: /images/optimization/transformations/bindings/
head: []
description: Store, transform, optimize, and deliver images at scale.
diff --git a/src/content/docs/workers/runtime-apis/request.mdx b/src/content/docs/workers/runtime-apis/request.mdx
index 99007d7830d..6b12a73840d 100644
--- a/src/content/docs/workers/runtime-apis/request.mdx
+++ b/src/content/docs/workers/runtime-apis/request.mdx
@@ -132,7 +132,7 @@ Invalid or incorrectly-named keys in the `cf` object will be silently ignored. C
* `image` Object | null optional
- * Enables [Image Resizing](/images/transform-images/) for this request. The possible values are described in [Transform images via Workers](/images/transform-images/transform-via-workers/) documentation.
+ * Enables [Image Resizing](/images/optimization/transformations/overview/) for this request. The possible values are described in [Transform images via Workers](/images/optimization/transformations/transform-via-workers/) documentation.
* `polish`
diff --git a/src/content/docs/workers/static-assets/migration-guides/migrate-from-pages.mdx b/src/content/docs/workers/static-assets/migration-guides/migrate-from-pages.mdx
index 2ad8800f940..b2611686bfe 100644
--- a/src/content/docs/workers/static-assets/migration-guides/migrate-from-pages.mdx
+++ b/src/content/docs/workers/static-assets/migration-guides/migrate-from-pages.mdx
@@ -443,7 +443,7 @@ This compatibility matrix compares the features of Workers and Pages. Unless oth
| [Email Workers](/email-routing/email-workers/send-email-workers/) | ✅ | ❌ |
| [Environment Variables](/workers/configuration/environment-variables/) | ✅ | ✅ |
| [Hyperdrive](/hyperdrive/) | ✅ | ✅ |
-| [Image Resizing](/images/transform-images/bindings/) | ✅ | ❌ |
+| [Image Resizing](/images/optimization/transformations/bindings/) | ✅ | ❌ |
| [KV](/kv/) | ✅ | ✅ |
| [mTLS](/workers/runtime-apis/bindings/mtls/) | ✅ | ✅ |
| [Queue Producers](/queues/configuration/configure-queues/#producer-worker-configuration) | ✅ | ✅ |
diff --git a/src/content/docs/workers/tutorials/generate-youtube-thumbnails-with-workers-and-images.mdx b/src/content/docs/workers/tutorials/generate-youtube-thumbnails-with-workers-and-images.mdx
index 33179f9804a..18766dc4ef0 100644
--- a/src/content/docs/workers/tutorials/generate-youtube-thumbnails-with-workers-and-images.mdx
+++ b/src/content/docs/workers/tutorials/generate-youtube-thumbnails-with-workers-and-images.mdx
@@ -20,7 +20,7 @@ import {
In this tutorial, you will learn how to programmatically generate a custom YouTube thumbnail using Cloudflare Workers and Cloudflare Image Resizing. You may want to generate a custom YouTube thumbnail to customize the thumbnail's design, call-to-actions and images used to encourage more viewers to watch your video.
-This tutorial will help you understand how to work with [Images](/images/),[Image Resizing](/images/transform-images/) and [Cloudflare Workers](/workers/).
+This tutorial will help you understand how to work with [Images](/images/),[Image Resizing](/images/optimization/transformations/overview/) and [Cloudflare Workers](/workers/).
@@ -53,7 +53,7 @@ To upload an image using the Cloudflare dashboard:
### Upload with the API
-To upload your image with the [Upload via URL](/images/upload-images/upload-url/) API, refer to the example below:
+To upload your image with the [Upload via URL](/images/storage/upload-images/upload-url/) API, refer to the example below:
```sh
curl --request POST \
@@ -412,7 +412,7 @@ Run your Worker and go to the `/original-image` route to review your image.
## Add custom text on your image
-You will now use [Cloudflare image transformations](/images/transform-images/), with the `fetch` method, to add your dynamic text image as an overlay on top of your background image. Start by displaying the resulting image on a different route. Call the new route `/thumbnail`.
+You will now use [Cloudflare image transformations](/images/optimization/transformations/overview/), with the `fetch` method, to add your dynamic text image as an overlay on top of your background image. Start by displaying the resulting image on a different route. Call the new route `/thumbnail`.
```js null {11}
export default {
@@ -484,7 +484,7 @@ if (url.pathname === "/thumbnail") {
}
```
-Next, add overlay options in the image object. Resize the image to the preferred width and height for YouTube thumbnails and use the [draw](/images/transform-images/draw-overlays/) option to add overlay text using the deployed URL of your `text-to-image` Worker.
+Next, add overlay options in the image object. Resize the image to the preferred width and height for YouTube thumbnails and use the [draw](/images/optimization/transformations/draw-overlays/) option to add overlay text using the deployed URL of your `text-to-image` Worker.
```js null {3,4,5,6,7,8,9,10,11,12}
fetch(imageURL, {
@@ -566,4 +566,4 @@ By completing this tutorial, you have successfully made a custom YouTube thumbna
## Related resources
-In this tutorial, you learned how to use Cloudflare Workers and Cloudflare image transformations to generate custom YouTube thumbnails. To learn more about Cloudflare Workers and image transformations, refer to [Resize an image with a Worker](/images/transform-images/transform-via-workers/).
+In this tutorial, you learned how to use Cloudflare Workers and Cloudflare image transformations to generate custom YouTube thumbnails. To learn more about Cloudflare Workers and image transformations, refer to [Resize an image with a Worker](/images/optimization/transformations/transform-via-workers/).
diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx
index be9547ea7ce..562eb30d2bb 100644
--- a/src/content/docs/workers/wrangler/configuration.mdx
+++ b/src/content/docs/workers/wrangler/configuration.mdx
@@ -765,7 +765,7 @@ Example:
### Images
-[Cloudflare Images](/images/transform-images/transform-via-workers/) lets you make transformation requests to optimize, resize, and manipulate images stored in remote sources.
+[Cloudflare Images](/images/optimization/transformations/transform-via-workers/) lets you make transformation requests to optimize, resize, and manipulate images stored in remote sources.
To bind Images to your Worker, assign an array of the below object to the `images` key.
diff --git a/src/content/partials/cache/cache-reserve-eligibility.mdx b/src/content/partials/cache/cache-reserve-eligibility.mdx
index 498e0d7b1c3..4222abac1e7 100644
--- a/src/content/partials/cache/cache-reserve-eligibility.mdx
+++ b/src/content/partials/cache/cache-reserve-eligibility.mdx
@@ -7,4 +7,4 @@ Not all assets are eligible for Cache Reserve. To be admitted into Cache Reserve
- Be cacheable, according to Cloudflare's standard [cacheability factors](/cache/).
- Have a freshness time-to-live (TTL) of at least 10 hours (set by any means such as Cache-Control / [CDN-Cache-Control](/cache/concepts/cache-control/) origin response headers, [Edge Cache TTL](/cache/how-to/edge-browser-cache-ttl/#edge-cache-ttl), [Cache TTL By Status](/cache/how-to/configure-cache-status-code/), or [Cache Rules](/cache/how-to/cache-rules/)),
- Have a Content-Length response header.
-- When using [Image transformations](/images/manage-images/create-variants/), original files are eligible for Cache Reserve, but resized file variants are not eligible because transformations happen after Cache Reserve in the response flow.
\ No newline at end of file
+- When using [Image transformations](/images/optimization/hosted-images/create-variants/), original files are eligible for Cache Reserve, but resized file variants are not eligible because transformations happen after Cache Reserve in the response flow.
\ No newline at end of file
diff --git a/src/content/partials/images/anim.mdx b/src/content/partials/images/anim.mdx
index 7d1f86ec2aa..3e1e4040992 100644
--- a/src/content/partials/images/anim.mdx
+++ b/src/content/partials/images/anim.mdx
@@ -1,9 +1,37 @@
---
{}
---
-import { Tabs, TabItem } from "~/components"
+import { Tabs, TabItem} from "~/components"
+import animGif from "~/assets/images/images/examples/anim.gif";
+import animPng from "~/assets/images/images/examples/anim.png";
-Whether to preserve animation frames from input files. Default is `true`. Setting it to `false` reduces animations to still images. This setting is recommended when enlarging images or processing arbitrary user content, because large GIF animations can weigh tens or even hundreds of megabytes. It is also useful to set `anim:false` when using `format:"json"` to get the response quicker without the number of frames.
+### `anim`
+
+Specifies whether to preserve animation frames from input files.
+
+- `true` (default) — Outputs the animated image with all frames.
+- `false` — Converts the first frame of an animated input to a still image.
+
+This setting is recommended when enlarging images or processing arbitrary user-uploaded content, as animated GIFs can have large file sizes and increase page load times. When using `format=json`, it is also useful to set `anim=false` to get a quicker response without the number of frames.
+
+
+
+
+ 
+ |
+
+ 
+ |
+
+
+ |
+ Original
+ |
+
+ anim=false
+ |
+
+
diff --git a/src/content/partials/images/background.mdx b/src/content/partials/images/background.mdx
index 6c963854d24..45533d146eb 100644
--- a/src/content/partials/images/background.mdx
+++ b/src/content/partials/images/background.mdx
@@ -2,33 +2,55 @@
{}
---
-import { Tabs, TabItem } from "~/components";
-
-Background color to add underneath the image. Applies to images with transparency (for example, PNG) and images resized with `fit=pad`. Accepts any CSS color using CSS4 modern syntax, such as `rgb(255 255 0)` and `rgba(255 255 0 100)`.
+import { Tabs, TabItem} from "~/components";
+import originalImg from "~/assets/images/images/examples/original.jpg";
+import backgroundImg from "~/assets/images/images/examples/background-red.jpg";
+
+### `background`
+
+Specifies an opaque or transparent color to fill blank or transparent pixels in the image. The default is `%23FFFFFF` (white).
+
+Accepts the following properties:
+
+- A HEX color code, formatted as `%23RRGGBB`.
+- A CSS color name, e.g. `white` or `red`.
+- An `rgb()` or `rgba()` CSS color function, e.g. `rgba(250,40,145,0.5)`.
+
+The background color is visible in images with transparent pixels, including images that are resized with `fit=pad`.
+
+
+
+
+ 
+ |
+
+ 
+ |
+
+
+
+ Original
+ 1080 x 720
+ |
+
+ Output
+ 1080 x 900
+ |
+
+
```txt
-background=%23RRGGBB
-
-OR
-
+background=%23ff0000
background=red
-
-OR
-
background=rgb%28240%2C40%2C145%29
-
```
```js
cf: {image: {background: "#RRGGBB"}}
-
-OR
-
-cf:{image: {background: "rgba(240,40,145,0)"}}
+cf: {image: {background: "rgba(240,40,145,0)"}}
```
-
diff --git a/src/content/partials/images/blur.mdx b/src/content/partials/images/blur.mdx
index 8731c3ed6e9..e59cf803ffb 100644
--- a/src/content/partials/images/blur.mdx
+++ b/src/content/partials/images/blur.mdx
@@ -1,9 +1,35 @@
---
{}
---
-import { Tabs, TabItem } from "~/components"
+import { Tabs, TabItem} from "~/components"
+import originalImg from "~/assets/images/images/examples/original.jpg";
+import blurImg from "~/assets/images/images/examples/blur-50.jpg";
-Blur radius between `1` (slight blur) and `250` (maximum). Be aware that you cannot use this option to reliably obscure image content, because savvy users can modify an image's URL and remove the blur option. Use Workers to control which options can be set.
+### `blur`
+
+Applies a blur radius to the image. Accepts an integer from `0` (no blur) to `250` (maximum blur). The default is `0`.
+
+This parameter should not be used to reliably obscure image content when optimizing via URL, as the URL can be modified to remove the blur parameter. Instead, you can [restrict access to the original image](/images/optimization/transformations/transform-via-workers/) through Workers.
+
+
+
+ |
+
+ |
+
+ 
+ |
+
+
+ |
+ Original
+ |
+
+
+ blur=50
+ |
+
+
@@ -16,4 +42,4 @@ Blur radius between `1` (slight blur) and `250` (maximum). Be aware that you can
cf: {image: {blur: 50}}
```
-
\ No newline at end of file
+
diff --git a/src/content/partials/images/border.mdx b/src/content/partials/images/border.mdx
index ddcd3dddb66..ac24c24817d 100644
--- a/src/content/partials/images/border.mdx
+++ b/src/content/partials/images/border.mdx
@@ -1,9 +1,23 @@
---
{}
---
-import { Tabs, TabItem } from "~/components"
+import { Tabs, TabItem} from "~/components"
-Adds a border around the image. The border is added after resizing. Border width takes `dpr` into account, and can be specified either using a single `width` property, or individually for each side.
+### `border`
+
+Adds a border around the image.
+
+:::note
+This feature is available only in Workers.
+:::
+
+Accepts the following properties:
+
+- `color` — Sets the color of the border. Accepts any valid CSS color value, for example `#FF0000`, `rgb(0,0,0)`, or `red`.
+- `width` — Sets the uniform border, in pixels, on all four sides.
+- `top`, `right`, `bottom`, `left` — Sets the border width, in pixels, for individual sides.
+
+The border is applied after the image has been resized. The border width automatically scales with the [`dpr`](/images/optimization/features#dpr) parameter to ensure sharpness on high-resolution screens.
@@ -12,4 +26,4 @@ Adds a border around the image. The border is added after resizing. Border width
cf: {image: {border: {color: "#FFFFFF", width: 10}}}
```
-
\ No newline at end of file
+
diff --git a/src/content/partials/images/brightness.mdx b/src/content/partials/images/brightness.mdx
index fc853072c40..26d7269500e 100644
--- a/src/content/partials/images/brightness.mdx
+++ b/src/content/partials/images/brightness.mdx
@@ -1,9 +1,45 @@
---
{}
---
-import { Tabs, TabItem } from "~/components"
+import { Tabs, TabItem} from "~/components"
+import originalImg from "~/assets/images/images/examples/original.jpg";
+import brightnessLowImg from "~/assets/images/images/examples/brightness-0.5.jpg";
+import brightnessHighImg from "~/assets/images/images/examples/brightness-2.jpg";
-Increase brightness by a factor. A value of `1.0` equals no change, a value of `0.5` equals half brightness, and a value of `2.0` equals twice as bright. `0` is ignored.
+### `brightness`
+
+Adjusts the image's overall luminance using a multiplier.
+
+- `1` (default) — No change to the original brightness.
+- `< 1.0` — Darkens the image, e.g. `0.5` is half as bright.
+- `> 1.0` — Lightens the image, e.g. `2` is twice as bright.
+
+
+
+ |
+
+ |
+
+ 
+ |
+
+ 
+ |
+
+
+ |
+ Original
+ |
+
+
+ brightness=0.5
+ |
+
+
+ brightness=2
+ |
+
+
@@ -16,4 +52,4 @@ Increase brightness by a factor. A value of `1.0` equals no change, a value of `
cf: {image: {brightness: 0.5}}
```
-
\ No newline at end of file
+
diff --git a/src/content/partials/images/compression.mdx b/src/content/partials/images/compression.mdx
index 7cd0c993a12..abe20f248a1 100644
--- a/src/content/partials/images/compression.mdx
+++ b/src/content/partials/images/compression.mdx
@@ -1,9 +1,15 @@
---
{}
---
-import { Tabs, TabItem } from "~/components"
+import { Tabs, TabItem} from "~/components"
-Slightly reduces latency on a cache miss by selecting a quickest-to-compress file format, at a cost of increased file size and lower image quality. It will usually override the `format` option and choose JPEG over WebP or AVIF. We do not recommend using this option, except in unusual circumstances like resizing uncacheable dynamically-generated images.
+### `compression`
+
+Selects the output format that is quickest to compress. Accepts `fast`. The default is none.
+
+The `compression=fast` option prioritizes encoding speed over output quality and file size, and will usually override the `format` parameter to choose JPEG over more efficient formats like AVIF or WebP. This slightly reduces latency on a cache miss, but may result in increased file size and lower image quality.
+
+This option is not recommended, except in unusual circumstances like resizing uncacheable, dynamically-generated images.
@@ -16,4 +22,4 @@ Slightly reduces latency on a cache miss by selecting a quickest-to-compress fil
cf: {image: {compression: "fast"}}
```
-
\ No newline at end of file
+
diff --git a/src/content/partials/images/contrast.mdx b/src/content/partials/images/contrast.mdx
index fd866058b9c..f839a530c97 100644
--- a/src/content/partials/images/contrast.mdx
+++ b/src/content/partials/images/contrast.mdx
@@ -1,9 +1,45 @@
---
{}
---
-import { Tabs, TabItem } from "~/components"
+import { Tabs, TabItem} from "~/components"
+import originalImg from "~/assets/images/images/examples/original.jpg";
+import contrastLowImg from "~/assets/images/images/examples/contrast-0.5.jpg";
+import contrastHighImg from "~/assets/images/images/examples/contrast-2.jpg";
-Increase contrast by a factor. A value of `1.0` equals no change, a value of `0.5` equals low contrast, and a value of `2.0` equals high contrast. `0` is ignored.
+### `contrast`
+
+Adjusts the image's overall difference between the darkest and lightest parts using a multiplier.
+
+- `1` (default) — No change to the original contrast.
+- `< 1.0` — Decreases contrast, which makes shadows lighter and highlights darker.
+- `> 1.0` — Increases contrast, which pushes shadows toward black and highlights toward white.
+
+
+
+ |
+
+ |
+
+ 
+ |
+
+ 
+ |
+
+
+ |
+ Original
+ |
+
+
+ contrast=0.5
+ |
+
+
+ contrast=2
+ |
+
+
@@ -16,4 +52,4 @@ Increase contrast by a factor. A value of `1.0` equals no change, a value of `0.
cf: {image: {contrast: 0.5}}
```
-
\ No newline at end of file
+
diff --git a/src/content/partials/images/delivery-url-breakdown.mdx b/src/content/partials/images/delivery-url-breakdown.mdx
new file mode 100644
index 00000000000..01151e413e9
--- /dev/null
+++ b/src/content/partials/images/delivery-url-breakdown.mdx
@@ -0,0 +1,10 @@
+---
+{}
+---
+
+| Part | Description |
+| --- | --- |
+| `imagedelivery.net` | A shared, Cloudflare-owned domain for optimizing images that are hosted in Images. As an alternative, you can also [serve images from your own domain](/images/optimization/hosted-images/serve-from-custom-domains/). |
+| `` | A unique identifier for your Cloudflare account. You can find your account hash in the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/images/hosted) under **Images** > **Developer Resources**. |
+| `` | The unique identifier for a hosted image. When you upload to Images, Cloudflare automatically generates an image ID. You can also set a [custom ID](/images/storage/upload-images/upload-custom-path/) to use your own path structure. |
+| `` | Here, you can specify a [predefined variant](/images/optimization/hosted-images/create-variants/) or a list of optimization parameters, separated by a comma. A valid URL must specify either a variant or at least one parameter. |
diff --git a/src/content/partials/images/dpr.mdx b/src/content/partials/images/dpr.mdx
index 9221cb07dcb..8aef41a2af1 100644
--- a/src/content/partials/images/dpr.mdx
+++ b/src/content/partials/images/dpr.mdx
@@ -1,9 +1,38 @@
---
{}
---
-import { Tabs, TabItem } from "~/components"
+import { Tabs, TabItem} from "~/components"
+import dpr1Img from "~/assets/images/images/examples/dpr-1.jpg";
+import dpr2Img from "~/assets/images/images/examples/dpr-2.jpg";
-Device Pixel Ratio. Default is `1`. Multiplier for `width`/`height` that makes it easier to specify higher-DPI sizes in `![]()
`.
+### `dpr`
+
+Scales the output resolution by a multiplier to match a user's specific screen density (for example, Retina or 4K). The default is `1`, which delivers the image at the exact width and height requested. The maximum supported value is `2`.
+
+Modern devices have more physical pixels than CSS pixels. If you serve a 300 px image in a 300 px container on a high-DPR smartphone, then it will look blurry. Using `dpr=2` tells Cloudflare to send a 600 px image for the same 300 px container, which results in a clearer, crisper image.
+
+The `dpr` parameter can be used with `srcset` to [serve responsive images](/images/optimization/make-responsive-images/).
+
+
+
+
+ 
+ |
+
+ 
+ |
+
+
+
+
+ width=300,height=200,dpr=1
+ |
+
+
+ width=300,height=200,dpr=2
+ |
+
+
@@ -16,4 +45,4 @@ Device Pixel Ratio. Default is `1`. Multiplier for `width`/`height` that makes i
cf: {image: {dpr: 1}}
```
-
\ No newline at end of file
+
diff --git a/src/content/partials/images/fit.mdx b/src/content/partials/images/fit.mdx
index 358c090a4b0..b792f3d8c3e 100644
--- a/src/content/partials/images/fit.mdx
+++ b/src/content/partials/images/fit.mdx
@@ -2,22 +2,31 @@
{}
---
-import { Tabs, TabItem } from "~/components";
-
-Affects interpretation of `width` and `height`. All resizing modes preserve aspect ratio. Used as a string in Workers integration. Available modes are:
-
-- `scale-down`\
- Similar to `contain`, but the image is never enlarged. If the image is larger than given `width` or `height`, it will be resized. Otherwise its original size will be kept.
-- `contain`\
- Image will be resized (shrunk or enlarged) to be as large as possible within the given `width` or `height` while preserving the aspect ratio. If you only provide a single dimension (for example, only `width`), the image will be shrunk or enlarged to exactly match that dimension.
-- `cover`\
- Resizes (shrinks or enlarges) to fill the entire area of `width` and `height`. If the image has an aspect ratio different from the ratio of `width` and `height`, it will be cropped to fit.
-- `crop`\
- Image will be shrunk and cropped to fit within the area specified by `width` and `height`. The image will not be enlarged. For images smaller than the given dimensions, it is the same as `scale-down`. For images larger than the given dimensions, it is the same as `cover`. See also [`trim`](#trim)
-- `pad`\
- Resizes to the maximum size that fits within the given `width` and `height`, and then fills the remaining area with a `background` color (white by default). This mode is not recommended, since you can achieve the same effect more efficiently with the `contain` mode and the CSS `object-fit: contain` property.
-- `squeeze`
- Resizes the image to the exact width and height specified. This mode does not preserve the original aspect ratio and will cause the image to appear stretched or squashed.
+import { Tabs, TabItem} from "~/components";
+import lg from "~/assets/images/images/examples/fit/1296x1296.png";
+import peteContain from "~/assets/images/images/examples/fit/pete-contain.png";
+import peteCover from "~/assets/images/images/examples/fit/pete-cover.png";
+import petePad from "~/assets/images/images/examples/fit/pete-pad.png";
+import originalAbstract from "~/assets/images/images/examples/fit/abstract.jpg";
+import squeezeAbstract from "~/assets/images/images/examples/fit/abstract-squeeze.jpg";
+import originalPete from "~/assets/images/images/examples/fit/pete-landscape.jpg";
+import squeezePete from "~/assets/images/images/examples/fit/pete-squeeze.jpg";
+
+### `fit`
+
+Specifies how the image is fit to the target area.
+
+Fit is performed after setting the [`width`](/images/optimization/features/#width) and [`height`](/images/optimization/features/#height) dimensions of the image.
+
+| Option | Result | Match original aspect ratio | Upscales |
+| --- | --- | --- | --- |
+| `contain` (default) | Show entire image without cropping | Yes | Yes |
+| `cover` | Fill the entire requested area, cropping if needed | No | Yes |
+| `crop` | Same as `cover`, but never upscales | No | No |
+| `pad` | Fit within the target area, adding space for remaining area | Yes | Yes |
+| `scale-down` | Same as `contain`, but never upscales | Yes | No |
+| `squeeze` | Scale to exact dimensions, distorting if needed | No | Yes |
+
```txt
@@ -30,3 +39,199 @@ Affects interpretation of `width` and `height`. All resizing modes preserve aspe
```
+
+#### `contain`
+Resizes the image to be as large as possible within the target `width` and `height` dimensions while preserving its original aspect ratio. This is the default `fit` behavior.
+
+In the example below, the 1080x720 image is resized to fit within the target 500x500 area. Since `contain` preserves original aspect ratio (3:2), the final dimensions of the output image are 500x333.
+
+
+
+
+ 
+ |
+
+ 
+ |
+
+ 
+ |
+
+
+
+ Original
+ 1080 x 720 (3:2)
+ |
+
+ Requested
+ 500 x 500 (1:1)
+ |
+
+ Output
+ 500 x 333 (3:2)
+ |
+
+
+
+When the original image is smaller than the target area, it upscales instead, which may reduce image quality. To avoid upscaling, use `scale-down`.
+
+#### `cover`
+Fills the entire target area, shrinking or enlarging the image if needed. The output area always matches the requested `width` and `height` dimensions exactly.
+
+When the original and target aspect ratios differ, the image is resized to cover the full target area and any overflow is cropped. Use the [`gravity`](/images/optimization/features/#gravity) parameter to control which part of the image is preserved during cropping.
+
+In the example below, the 1080×720 image is first resized to 750×500 (matching the requested height) to fit the target area, then cropped from the left and right edges to its final 500x500 dimensions.
+
+
+
+ |
+
+ |
+
+
+ |
+
+ 
+ |
+
+
+
+ Original
+ 1080 x 720 (3:2)
+ |
+
+ Requested
+ 500 x 500 (1:1)
+ |
+
+ Output
+ 500 x 500 (1:1)
+ |
+
+
+
+When the original image is smaller than the target area, it upscales instead. To avoid upscaling, use `crop`.
+
+#### `crop`
+Resizes the image to fill the target area without upscaling.
+
+When the original image is smaller than the target area, it is returned at its original dimensions and does not upscale.
+
+In the example below, the original image (1080x720) is smaller than the target area (1296x1296), so it preserves its original size and aspect ratio.
+
+
+
+ |
+
+ |
+
+
+ |
+
+
+ |
+
+
+
+ Original
+ 1080 x 720 (3:2)
+ |
+
+ Requested
+ 1296 x 1296 (1:1)
+ |
+
+ Output
+ 1080 x 720 (3:2)
+ |
+
+
+
+When the original image is larger than the target area, it behaves like `cover` (fills the target area and crops the rest) instead.
+
+#### `pad`
+Resizes the image to be as large as possible within the dimensions. If applicable, the output area will be expanded to match the `width` and `height` dimensions exactly.
+
+Works with the `background` parameter to fill any blank or transparent pixels. However, for web apps, you can often achieve the same visual result using the `contain` option with the CSS `object-fit: contain` property, which avoids encoding padding pixels into the image itself.
+
+In the example below, the original image (1080x720) is smaller than the target area (1080x1080), so it creates space for the remaining pixels.
+
+
+
+ |
+
+ |
+
+
+ |
+
+ 
+ |
+
+
+
+ Original
+ 1080 x 720 (3:2)
+ |
+
+ Requested
+ 1080 x 1080 (1:1)
+ |
+
+ Output
+ 1080 x 1080 (1:1)
+ |
+
+
+
+#### `scale-down`
+Resizes the image to fit within the specified dimensions while preserving its original aspect ratio, but never upscales the image.
+
+When the original image is smaller than the target area, it behaves like `crop` (keeps original size and aspect ratio). When larger, it behaves like `contain` (downscaled to fill the target area).
+
+#### `squeeze`
+Resizes the image to exactly match the requested width and height, without cropping the edges or constraining the portions.
+
+When the original and target aspect ratios differ, the image will be distorted to fit the target area.
+
+
+
+ |
+
+ |
+
+ 
+ |
+
+
+
+ Original
+ 1080 x 720
+ |
+
+ Output
+ 1080 x 540
+ |
+
+
+
+
+
+
+ 
+ |
+
+ 
+ |
+
+
+
+ Original
+ 1080 x 1080
+ |
+
+ Output
+ 1080 x 540
+ |
+
+
\ No newline at end of file
diff --git a/src/content/partials/images/flip.mdx b/src/content/partials/images/flip.mdx
index b12aa0ed0d4..bd1f6b121be 100644
--- a/src/content/partials/images/flip.mdx
+++ b/src/content/partials/images/flip.mdx
@@ -1,17 +1,49 @@
---
{}
---
-import { Tabs, TabItem } from "~/components"
+import { Tabs, TabItem} from "~/components"
+import originalImg from "~/assets/images/images/examples/original.jpg";
+import flipHImg from "~/assets/images/images/examples/flip-h.jpg";
+import flipVImg from "~/assets/images/images/examples/flip-v.jpg";
-Flips the image horizontally, vertically, or both. Can be used with the `rotate` parameter to set the orientation of an image.
+### `flip`
-Flipping is performed before rotation. For example, if you apply `flip=h,rotate=90,` then the image will be flipped horizontally, then rotated by 90 degrees.
+Flips the image horizontally, vertically, or both.
-Available options are:
+Accepts the following values:
-- `h`: Flips the image horizontally.
-- `v`: Flips the image vertically.
-- `hv`: Flips the image vertically and horizontally.
+- `h` — Flips the image horizontally.
+- `v` — Flips the image vertically.
+- `hv` — Flips the image both horizontally and vertically.
+
+Flip can be used with the `rotate` parameter to set the orientation of the image. Flip is performed before rotation. For example, if you apply `flip=h,rotate=90`, then the image will be flipped horizontally, then rotated by 90 degrees.
+
+
+
+ |
+
+ |
+
+ 
+ |
+
+ 
+ |
+
+
+ |
+ Original
+ |
+
+
+ flip=h
+ |
+
+
+ flip=v
+ |
+
+
diff --git a/src/content/partials/images/format.mdx b/src/content/partials/images/format.mdx
index b485fdf2605..9735d739f07 100644
--- a/src/content/partials/images/format.mdx
+++ b/src/content/partials/images/format.mdx
@@ -2,39 +2,38 @@
{}
---
-import { Tabs, TabItem } from "~/components";
+import { Tabs, TabItem} from "~/components";
-The `auto` option will serve the WebP or AVIF format to browsers that support it. If this option is not specified, a standard format like JPEG or PNG will be used. Cloudflare will default to JPEG when possible due to the large size of PNG files.
+
-Other supported options:
+### `format` | `f`
-- `avif`: Generate images in AVIF format if possible (with WebP as a fallback).
-- `webp`: Generate images in Google WebP format. Set the quality to `100` to get the WebP lossless format.
-- `jpeg`: Generate images in interlaced progressive JPEG format, in which data is compressed in multiple passes of progressively higher detail.
-- `baseline-jpeg`: Generate images in baseline sequential JPEG format. It should be used in cases when target devices don't support progressive JPEG or other modern file formats.
-- `json`: Instead of generating an image, outputs information about the image in JSON format. The JSON object will contain data such as image size (before and after resizing), source image's MIME type, and file size.
+Specifies the output format for the image.
-**Alias:** `f`
+Accepts the following values:
+
+- `auto` — Automatically serves the most efficient format that the requesting browser supports. When you serve a [hosted image](/images/optimization/hosted-images/create-variants/), this is the default `format` option.
+- `avif` — Transcodes the image to AVIF, if possible. AVIF encoding can be an order of magnitude slower than encoding to other formats. If the image is too large to be quickly encoded to AVIF, then Cloudflare will fall back to WebP or JPEG.
+- `webp` — Transcodes the image to Google WebP format. Use `quality=100` to return the WebP lossless format.
+- `jpeg` — Transcodes the image in interlaced progressive JPEG format, in which data is compressed in multiple passes of progressively higher detail.
+- `baseline-jpeg` — Transcode the image in baseline sequential JPEG format. It should be used in cases when target devices do not support progressive JPEG or other modern file formats.
+- `json` — Outputs information about the image as a JSON object. This contains data such as image size (before and after resizing), the source image's MIME type, and file size.
```txt
format=auto
+ f=auto
```
-
- ```txt
- f=auto
- ```
-
-
+
```js
cf: {image: {format: "avif"}}
```
-For the `format:auto` option to work with a custom Worker, you need to parse the `Accept` header. Refer to [this example Worker](/images/transform-images/transform-via-workers/#an-example-worker) for a complete overview of how to set up an image transformation Worker.
+To use `format=auto` with a custom Worker, you need to parse the `Accept` header. Refer to [this example Worker](/images/optimization/transformations/transform-via-workers/#an-example-worker) for a complete overview of how to set up an image transformation Worker.
```js title="Custom Worker for Image Resizing with format:auto"
const accept = request.headers.get("accept");
diff --git a/src/content/partials/images/gamma.mdx b/src/content/partials/images/gamma.mdx
index da09730e805..3ea11b2bc81 100644
--- a/src/content/partials/images/gamma.mdx
+++ b/src/content/partials/images/gamma.mdx
@@ -1,9 +1,45 @@
---
{}
---
-import { Tabs, TabItem } from "~/components"
+import { Tabs, TabItem} from "~/components"
+import originalImg from "~/assets/images/images/examples/original.jpg";
+import gammaLowImg from "~/assets/images/images/examples/gamma-0.5.jpg";
+import gammaHighImg from "~/assets/images/images/examples/gamma-2.jpg";
-Increase exposure by a factor. A value of `1.0` equals no change, a value of `0.5` darkens the image, and a value of `2.0` lightens the image. `0` is ignored.
+### `gamma`
+
+Adjusts the exposure of an image using a multiplier. Gamma controls the midtone brightness without affecting the darkest or lightest parts of the image.
+
+- `0` and `1` (default) — No change to the original gamma.
+- `< 1.0` — Increases midtone brightness, making the image appear lighter overall.
+- `> 1.0` — Decreases midtone brightness, making the image appear darker overall.
+
+
+
+ |
+
+ |
+
+ 
+ |
+
+ 
+ |
+
+
+ |
+ Original
+ |
+
+
+ gamma=0.5
+ |
+
+
+ gamma=2
+ |
+
+
@@ -16,4 +52,4 @@ Increase exposure by a factor. A value of `1.0` equals no change, a value of `0.
cf: {image: {gamma: 0.5}}
```
-
\ No newline at end of file
+
diff --git a/src/content/partials/images/gravity.mdx b/src/content/partials/images/gravity.mdx
index ebe213e36c5..4c47bbca7ac 100644
--- a/src/content/partials/images/gravity.mdx
+++ b/src/content/partials/images/gravity.mdx
@@ -2,84 +2,187 @@
{}
---
-import { Tabs, TabItem } from "~/components";
+import { Tabs, TabItem} from "~/components";
+import xxy from "~/assets/images/images/examples/gravity/xxy.png";
+import coffeeBase from "~/assets/images/images/examples/gravity/coffee-base.jpg";
+import coffeeCrop from "~/assets/images/images/examples/gravity/coffee-crop.jpg";
+import coffeeAuto from "~/assets/images/images/examples/gravity/coffee-auto.jpg";
+import faceBase from "~/assets/images/images/examples/gravity/suad-kamardeen.jpeg";
+import faceCrop from "~/assets/images/images/examples/gravity/suad-kamardeen-crop.jpeg";
+import faceOutput from "~/assets/images/images/examples/gravity/suad-kamardeen-face.jpeg";
+import pete from "~/assets/images/images/examples/fit/pete-landscape.jpg";
+import sideOutput from "~/assets/images/images/examples/gravity/pete-bottom.jpg";
+import base from "~/assets/images/images/examples/gravity/base.png";
+import relPoints from "~/assets/images/images/examples/gravity/rel-points.png";
+import relAlignment from "~/assets/images/images/examples/gravity/rel-alignment.png";
+import relOutput from "~/assets/images/images/examples/gravity/rel-output.png";
-Specifies how an image should be cropped when used with `fit=cover` and `fit=crop`.
-Available options are `auto`, `face`, a side (`left`, `right`, `top`, `bottom`), and relative coordinates (`XxY` with a valid range of `0.0` to `1.0`):
+
-- `auto`\
- Selects focal point based on saliency detection (using maximum symmetric surround algorithm).
-- `side`\
- A side (`"left"`, `"right"`, `"top"`, `"bottom"`) or coordinates specified on a scale from `0.0` (top or left) to `1.0` (bottom or right), `0.5` being the center. The X and Y coordinates are separated by lowercase `x` in the URL format. For example, `0x1` means left and bottom, `0.5x0.5` is the center, `0.5x0.33` is a point in the top third of the image.
+### `gravity` | `g`
- For the Workers integration, use an object `{x, y}` to specify coordinates. It contains focal point coordinates in the original image expressed as fractions ranging from `0.0` (top or left) to `1.0` (bottom or right), with `0.5` being the center. `{fit: "cover", gravity: {x:0.5, y:0.2}}` will crop each side to preserve as much as possible around a point at 20% of the height of the source image.
+Specifies how the image should be cropped when used with `fit=cover` and `fit=crop`. By default, Cloudflare will crop toward the center point of the original image.
-:::note
-You must subtract the height of the image before you calculate the focal point.
-:::
-
-- `face`\
- Automatically sets the focal point based on detected faces in an image. This can be combined with the `zoom` parameter to specify how closely the image should be cropped towards the faces.
-
- The new focal point is determined by a minimum bounding box that surrounds all detected faces. If no faces are found, then the focal point will fall back to the center of the image.
-
- This feature uses an open-source model called RetinaFace through WorkersAI. Our model pipeline is limited only to facial detection, or identifying the pixels that represent a human face. We do not support facial identification or recognition. Read more about Cloudflare's [approach to responsible AI](https://www.cloudflare.com/trust-hub/responsible-ai/).
-
-**Alias:** `g`
+Accepts `auto`, `face`, a side (`left`, `right`, `top`, `bottom`), and relative coordinates (`XxY`).
```txt
gravity=auto
-
- OR
-
- gravity=left
-
- OR
-
- gravity=0x1
-
- OR
-
- gravity=face
- ```
-
-
-
- ```txt
g=auto
-
- OR
-
- g=left
-
- OR
-
- g=0x1
-
- OR
-
- g=face
+ gravity=face
+ gravity=left
+ gravity=0.5x1
```
-
```js
cf: {image: {gravity: "auto"}}
-
-OR
-
-cf: {image: {gravity: "right"}}
-
-OR
-
-cf: {image: {gravity: {x:0.5, y:0.2}}}
-
-OR
-
-cf: {image: {gravity: "face"}}
+ cf: {image: {gravity: "face"}}
+ cf: {image: {gravity: "left"}}
+ cf: {image: {gravity: {x:0.5, y:0.2}}}
```
-```
\ No newline at end of file
+
+#### `auto`
+Automatically sets the focal point by using a saliency algorithm to detect the most visually interesting pixels.
+
+This is useful when you don't know the contents of the image ahead of time, such as with user-generated content. For large image libraries such as e-commerce product galleries, this feature eliminates the need to manually set a focal point for each image.
+
+
+
+
+ 
+ |
+
+ 
+ |
+
+ 
+ |
+
+
+ |
+ Original
+ |
+
+ Default crop
+ |
+
+ `gravity=auto`
+ |
+
+
+
+#### `face`
+Automatically sets the focal point based on faces in the image.
+
+This can be combined with the [`zoom`](/images/optimization/features#zoom) parameter to specify how closely the image should be cropped toward the face.
+
+
+
+
+ 
+ |
+
+ 
+ |
+
+ 
+ |
+
+
+ |
+ Original
+ |
+
+ Default crop
+ |
+
+ `gravity=face`
+ |
+
+
+
+*Photograph by [Suad Kamardeen (@suadkamardeen) on Unsplash](https://unsplash.com/photos/woman-in-black-cardigan-standing-beside-pink-flowers-UO-82DJ3rcc)*
+
+
+
+#### `left`, `right`, `top`, `bottom`
+Sets the side of the image that should not be cropped.
+
+In the example below, the 1080x720 image is cropped to a 1080x400 area, starting from its bottom edge:
+
+
+
+
+ 
+ |
+
+ 
+ |
+
+
+ |
+ Original
+ |
+
+ `gravity=bottom`
+ |
+
+
+
+#### `XxY`
+Sets the focal point (X,Y) so that the relative coordinates of the output image are positioned at the relative coordinates of the original image. Accepts a coordinate pair formatted as `XxY`, where X and Y are decimal values between `0.0` and `1.0`.
+
+
+
+- Horizontal value (X) — `0.0` is the left edge and `1.0` is the right edge of the image.
+- Vertical value (Y) — `0.0` is the top edge and `1.0` is the bottom edge of the image.
+
+The example below crops a 900x900 image to 300x900 using a 0.33x0.5 gravity point:
+- Both the original image and target area will have gravity points set at 1/3 of the width from the left edge and 1/2 of the height from the top edge.
+- The relative coordinates of the output gravity point are positioned at the relative coordinates of the original image. That is, the target area is positioned so that its gravity point sits at the same relative position in the original image (0.33, 0.5).
+- The darkened parts of the image show the area outside of the requested output, which will be cropped.
+- The final cropped result captures the 300x900 content that is around the gravity point (0.33, 0.5).
+
+
+
+
+ 
+ |
+
+ 
+ |
+
+ 
+ |
+
+ 
+ |
+
+
+
+ Original
+ |
+
+ Align
+ |
+
+ Crop
+ |
+
+ Output
+ |
+
+
+
+When optimizing through Workers, use an object `{x, y}` to specify coordinates. For example, `{fit: "cover", gravity: {x:0.5, y:0.2}}` will crop each side to preserve as much as possible around a point at 20% of the height of the original image.
diff --git a/src/content/partials/images/height.mdx b/src/content/partials/images/height.mdx
index 51d68c69458..bc8a14e11fc 100644
--- a/src/content/partials/images/height.mdx
+++ b/src/content/partials/images/height.mdx
@@ -1,26 +1,26 @@
---
{}
---
-import { Tabs, TabItem } from "~/components"
+import { Tabs, TabItem} from "~/components"
-Specifies maximum height of the image in pixels. Exact behavior depends on the `fit` mode (described below).
+
-**Alias:** `h`
+### `height` | `h`
+
+Sets the height of the output image in pixels using a positive integer value. By default, Cloudflare uses the original height of the input image.
+
+When `height` is set, the exact behavior depends on the `fit` parameter.
```txt
height=250
+ h=250
```
-
- ```txt
- h=250
- ```
-
```js
cf: {image: {height: 250}}
```
-
\ No newline at end of file
+
diff --git a/src/content/partials/images/ir-svg-aside.mdx b/src/content/partials/images/ir-svg-aside.mdx
index 28ab8c7ad8f..142fb225119 100644
--- a/src/content/partials/images/ir-svg-aside.mdx
+++ b/src/content/partials/images/ir-svg-aside.mdx
@@ -4,5 +4,5 @@
---
:::note
-You can use image transformations to sanitize SVGs, but not to resize them. Refer to [Resize with Workers](/images/transform-images/transform-via-workers/) for more information.
+You can use image transformations to sanitize SVGs, but not to resize them. Refer to [Resize with Workers](/images/optimization/transformations/transform-via-workers/) for more information.
:::
diff --git a/src/content/partials/images/metadata.mdx b/src/content/partials/images/metadata.mdx
index f9307bf54ae..73d7f90a654 100644
--- a/src/content/partials/images/metadata.mdx
+++ b/src/content/partials/images/metadata.mdx
@@ -2,28 +2,23 @@
{}
---
-import { Tabs, TabItem } from "~/components";
+import { Tabs, TabItem} from "~/components";
-Controls amount of invisible metadata (EXIF data) that should be preserved. Color profiles and EXIF rotation are applied to the image even if the metadata is discarded. Content Credentials (C2PA metadata) may be preserved if the [setting is enabled](/images/transform-images/preserve-content-credentials).
+### `metadata`
+Controls the amount of invisible metadata (EXIF) that should be preserved for a JPEG image. For all other output formats (e.g. WebP or PNG), all metadata will always be discarded.
-Available options are `copyright`, `keep`, and `none`. The default for all JPEG images is `copyright`. WebP and PNG output formats will always discard EXIF metadata.
+Color profiles and EXIF rotation are applied to the image even if the metadata is discarded.
:::note
-- If [Polish](/images/polish/) is enabled, then all metadata may already be removed and this option will have no effect.
-- Even when choosing to keep EXIF metadata, Cloudflare will modify JFIF data (potentially invalidating it) to avoid the known incompatibility between the two standards. For more details, refer to [JFIF Compatibility](https://en.wikipedia.org/wiki/JPEG_File_Interchange_Format#Compatibility).
- :::
-
-Options include:
-
-- `copyright`\
- Discards all EXIF metadata except copyright tag.
- If C2PA metadata preservation is enabled, then this option will preserve all Content Credentials.
-- `keep`\
- Preserves most of EXIF metadata, including GPS location if present.
- If C2PA metadata preservation is enabled, then this option will preserve all Content Credentials.
-- `none`\
- Discards all invisible EXIF and C2PA metadata. If the output format is WebP or PNG, then all metadata will be discarded.
+If [Polish](/images/polish/) is enabled, then all metadata may already be removed and this option will have no effect.
+:::
+
+Accepts the following values:
+
+- `copyright` (default) — Discards all metadata except EXIF copyright tag.
+- `keep` — Preserves most of EXIF metadata, including GPS location, if present.
+- `none` — Discards all invisible EXIF metadata.
diff --git a/src/content/partials/images/onerror.mdx b/src/content/partials/images/onerror.mdx
index 809d52fc245..1700e080718 100644
--- a/src/content/partials/images/onerror.mdx
+++ b/src/content/partials/images/onerror.mdx
@@ -2,13 +2,19 @@
{}
---
-import { Tabs, TabItem } from "~/components";
+import { Tabs, TabItem} from "~/components";
-:::note[Note]
-This setting only works directly with [image transformations](/images/transform-images/) and does not support resizing with Cloudflare Workers.
+### `onerror`
+
+Redirects the end-user to the URL of the original source image when a fatal error prevents the image from being transformed. Accepts `redirect`. The default is none.
+
+:::note
+This feature is available only when optimizing remote images through the URL interface. This is not supported for hosted images.
:::
-In case of a [fatal error](/images/reference/troubleshooting/#error-responses-from-resizing) that prevents the image from being resized, redirects to the unresized source image URL. This may be useful in case some images require user authentication and cannot be fetched anonymously via Worker. This option should not be used if there is a chance the source image is very large. This option is ignored if the image is from another domain, but you can use it with subdomains.
+This option works only if the image is in the same zone (subdomains are accepted). If the original image is from a different zone, then the option does not have any effect.
+
+This may be useful in cases where an image requires user authentication and the image cannot be fetched anonymously via Workers. However, this option is not recommended if the source image is very large.
diff --git a/src/content/partials/images/quality.mdx b/src/content/partials/images/quality.mdx
index 109de58d916..a4c2c8581fe 100644
--- a/src/content/partials/images/quality.mdx
+++ b/src/content/partials/images/quality.mdx
@@ -2,40 +2,30 @@
{}
---
-import { Tabs, TabItem } from "~/components";
+import { Tabs, TabItem} from "~/components";
-Specifies quality for images in JPEG, WebP, and AVIF formats. The quality is in a 1-100 scale, but useful values are between `50` (low quality, small file size) and `90` (high quality, large file size). `85` is the default. When using the PNG format, an explicit quality setting allows use of PNG8 (palette) variant of the format. Use the `format=auto` option to allow use of WebP and AVIF formats.
+
-We also allow setting one of the perceptual quality levels `high|medium-high|medium-low|low`
+### `quality` | `q`
-**Alias:** `q`
+Specifies the output quality of an image for JPEG, WebP, and AVIF formats, expressed as a fixed value or perceptual quality level. The default is `85`.
+
+- **Fixed quality** — Accepts a positive integer from `1` (low quality, small file size) to `100` (high quality, large file size).
+- **Perceptual quality** — Accepts `high`, `medium-high`, `medium-low`, and `low`.
+
+When the output format is PNG, an explicit `quality` setting allows the use of PNG8 (palette) variant of the format.
```txt
quality=50
-
- OR
-
quality=low
+ q=50
```
-
- ```txt
- q=50
-
-OR
-
-q=medium-high
-
-```
-
```js
cf: {image: {quality: 50}}
-
-OR
-
cf: {image: {quality: "high"}}
```
diff --git a/src/content/partials/images/rotate.mdx b/src/content/partials/images/rotate.mdx
index bf01d63804b..0601d8dace1 100644
--- a/src/content/partials/images/rotate.mdx
+++ b/src/content/partials/images/rotate.mdx
@@ -1,9 +1,35 @@
---
{}
---
-import { Tabs, TabItem } from "~/components"
+import { Tabs, TabItem} from "~/components"
+import originalImg from "~/assets/images/images/examples/original.jpg";
+import rotateImg from "~/assets/images/images/examples/rotate-180.jpg";
-Number of degrees (`90`, `180`, or `270`) to rotate the image by. `width` and `height` options refer to axes after rotation.
+### `rotate`
+
+Rotates an image by a number of degrees. Accepts `90`, `180`, or `270`. The default is `0` (no rotation).
+
+Rotation is performed before resizing; `width` and `height` options will refer to the axes after the image is rotated.
+
+
+
+ |
+
+ |
+
+ 
+ |
+
+
+ |
+ Original
+ |
+
+
+ rotate=180
+ |
+
+
@@ -16,4 +42,4 @@ Number of degrees (`90`, `180`, or `270`) to rotate the image by. `width` and `h
cf: {image: {rotate: 90}}
```
-
\ No newline at end of file
+
diff --git a/src/content/partials/images/saturation.mdx b/src/content/partials/images/saturation.mdx
index e77799eed15..1b2566f41d3 100644
--- a/src/content/partials/images/saturation.mdx
+++ b/src/content/partials/images/saturation.mdx
@@ -1,9 +1,46 @@
---
{}
---
-import { Tabs, TabItem } from "~/components"
+import { Tabs, TabItem} from "~/components"
+import originalImg from "~/assets/images/images/examples/original.jpg";
+import saturationLowImg from "~/assets/images/images/examples/saturation-0.jpg";
+import saturationHighImg from "~/assets/images/images/examples/saturation-2.jpg";
-Increases saturation by a factor. A value of `1.0` equals no change, a value of `0.5` equals half saturation, and a value of `2.0` equals twice as saturated. A value of `0` will convert the image to grayscale.
+### `saturation`
+
+Adjusts the color saturation of an image using a multiplier.
+
+- `0` — Completely desaturates the image (grayscale).
+- `< 1.0` — Reduces color intensity. For example, `0.5` is half as saturated.
+- `1` (default) — No change to the original saturation.
+- `> 1.0` — Increases color intensity. For example, `2` is twice as saturated.
+
+
+
+ |
+
+ |
+
+ 
+ |
+
+ 
+ |
+
+
+ |
+ Original
+ |
+
+
+ saturation=0
+ |
+
+
+ saturation=2
+ |
+
+
diff --git a/src/content/partials/images/segment.mdx b/src/content/partials/images/segment.mdx
index e40abf1e40d..7fd367b67d4 100644
--- a/src/content/partials/images/segment.mdx
+++ b/src/content/partials/images/segment.mdx
@@ -1,11 +1,35 @@
---
{}
---
-import { Tabs, TabItem } from "~/components"
+import { Tabs, TabItem} from "~/components"
+import originalImg from "~/assets/images/images/examples/original.jpg";
+import segmentImg from "~/assets/images/images/examples/segment-foreground.png";
-Automatically isolates the subject of an image by replacing the background with transparent pixels.
+### `segment`
- This feature uses an open-source model called BiRefNet through Workers AI. Read more about Cloudflare's [approach to responsible AI](https://www.cloudflare.com/trust-hub/responsible-ai/).
+Automatically isolates the subject of an image by replacing the background with transparent pixels. Accepts `foreground`. The default is none.
+
+This feature uses an open-source model called BiRefNet through [Workers AI](/workers-ai/). Read more about Cloudflare's [approach to responsible AI](https://www.cloudflare.com/trust-hub/responsible-ai/).
+
+
+
+ |
+
+ |
+
+ 
+ |
+
+
+ |
+ Original
+ |
+
+
+ segment=foreground
+ |
+
+
@@ -15,7 +39,7 @@ Automatically isolates the subject of an image by replacing the background with
```js
- cf: {segment: "foreground"}
+ cf: {image: {segment: "foreground"}}
```
-
\ No newline at end of file
+
diff --git a/src/content/partials/images/sharpen.mdx b/src/content/partials/images/sharpen.mdx
index 4293217c83b..d0b57cbe99c 100644
--- a/src/content/partials/images/sharpen.mdx
+++ b/src/content/partials/images/sharpen.mdx
@@ -1,9 +1,33 @@
---
{}
---
-import { Tabs, TabItem } from "~/components"
+import { Tabs, TabItem} from "~/components"
+import originalImg from "~/assets/images/images/examples/original.jpg";
+import sharpenImg from "~/assets/images/images/examples/sharpen-5.jpg";
-Specifies strength of sharpening filter to apply to the image. The value is a floating-point number between `0` (no sharpening, default) and `10` (maximum). `1` is a recommended value for downscaled images.
+### `sharpen`
+
+Applies a sharpening filter to enhance edge definition in an image. Accepts a decimal value from `0` (no sharpening) to `10` (maximum sharpening). The default is `0`. The recommended value for downscaled images is `1`.
+
+
+
+ |
+
+ |
+
+ 
+ |
+
+
+ |
+ Original
+ |
+
+
+ sharpen=5
+ |
+
+
@@ -16,4 +40,4 @@ Specifies strength of sharpening filter to apply to the image. The value is a fl
cf: {image: {sharpen: 2}}
```
-
\ No newline at end of file
+
diff --git a/src/content/partials/images/slow-connection-quality.mdx b/src/content/partials/images/slow-connection-quality.mdx
index 747cb02098e..2039720617c 100644
--- a/src/content/partials/images/slow-connection-quality.mdx
+++ b/src/content/partials/images/slow-connection-quality.mdx
@@ -2,41 +2,36 @@
{}
---
-import { Tabs, TabItem } from "~/components";
+import { Tabs, TabItem} from "~/components";
-Allows overriding `quality` value whenever a slow connection is detected.
+
-Available options are same as [quality](/images/transform-images/transform-via-url/#quality).
+### `slow-connection-quality` | `scq`
-**Alias:** `scq`
+Overrides the `quality` value whenever a slow connection is detected. Accepts the same fixed or perceptual settings as [quality](/images/optimization/features/#quality). The default is none.
-
-
- ```txt
- slow-connection-quality=50
- ```
-
-
- ```txt
- scq=50
- ```
-
-
-
-Detecting slow connections is currently only supported on Chromium-based browsers such as Chrome, Edge, and Opera.
+:::note
+This feature is available only when optimizing through the URL interface on Chromium-based browsers such as Chrome, Edge, and Opera.
+:::
-You can enable any of the following client hints via HTTP in a header
+To detect slow connections, enable any of the following client hints via HTTP in a header:
```txt
accept-ch: rtt, save-data, ect, downlink
```
-slow-connection-quality applies whenever any of the following is true and the client hint is present:
+`slow-connection-quality` applies when the client hint is present and any of the following conditions are met:
- [rtt](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/RTT): Greater than 150ms.
-
- [save-data](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Save-Data): Value is "on".
-
- [ect](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/ECT): Value is one of `slow-2g|2g|3g`.
-
- [downlink](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Downlink): Less than 5Mbps.
+
+
+
+ ```txt
+ slow-connection-quality=50
+ scq=50
+ ```
+
+
diff --git a/src/content/partials/images/transformation-url-breakdown.mdx b/src/content/partials/images/transformation-url-breakdown.mdx
new file mode 100644
index 00000000000..5a1a9d52781
--- /dev/null
+++ b/src/content/partials/images/transformation-url-breakdown.mdx
@@ -0,0 +1,10 @@
+---
+{}
+---
+
+| Part | Description |
+| --- | --- |
+| `` | Your domain name at Cloudflare. Transformations can be requested on every Cloudflare zone that has transformations enabled. |
+| `/cdn-cgi/image/` | A fixed prefix that identifies that this path is a request to optimize an image. To hide this part, you can set up [Transform Rules](/images/optimization/transformations/rewrite-rules/) to serve images from a custom path. |
+| `` | A list of optimization parameters, separated by a comma. A valid URL must specify at least one parameter. |
+| `` | The original image that you want to transform. You can use an absolute path on the origin server or an absolute URL (that starts with `https://` or `http://`). |
diff --git a/src/content/partials/images/trim.mdx b/src/content/partials/images/trim.mdx
index ad23c6d57e3..ca8d95307d8 100644
--- a/src/content/partials/images/trim.mdx
+++ b/src/content/partials/images/trim.mdx
@@ -1,57 +1,52 @@
---
{}
---
-import { Tabs, TabItem } from "~/components"
+import { Tabs, TabItem} from "~/components"
-Specifies a number of pixels to cut off on each side. Allows removal of borders or cutting out a specific fragment of an image. Trimming is performed before resizing or rotation. Takes `dpr` into account. For image transformations and Cloudflare Images, use as four numbers in pixels separated by a semicolon, in the form of `top;right;bottom;left` or via separate values `trim.width`,`trim.height`, `trim.left`,`trim.top`. For the Workers integration, specify an object with properties: `{top, right, bottom, left, width, height}`.
+### `trim`
-
-
- ```txt
- trim=20;30;20;0
- trim.width=678
- trim.height=678
- trim.left=30
- trim.top=40
- ```
-
-
- ```js
- cf: {image: {trim: {top: 12, right: 78, bottom: 34, left: 56, width:678, height:678}}}
- ```
-
-
+Removes pixels around the sides of an image.
+
+This feature can be used to trim an image by its border colors or by a specified number of pixels from its side(s).
-The API also supports automatic border removal based on color. This can be enabled by setting `trim=border` for automatic color detection, or customized with the parameters below.
+Trim takes into account the [`dpr`](/images/optimization/features/#dpr) parameter and is performed before resizing and rotation.
-`trim.border.color`
-The border color to trim. Accepts any CSS color using CSS4 modern syntax, such as `rgb(255 255 0)`. If omitted, the color is detected automatically.
+#### `border`
-`trim.border.tolerance`
-The matching tolerance for the color, on a scale of 0 to 255.
+Automatically trims the sides of the image based on its border color.
-`trim.border.keep`
-The number of pixels of the original border to leave untrimmed.
+The `trim=border` option can be further adjusted using the following parameters:
+
+- `trim.border.color` — Selects the border color to trim. Accepts any CSS color using CSS4 modern syntax. If omitted, the color is detected automatically.
+- `trim.border.tolerance` — Sets how closely the detected pixels must match in color. Accepts an integer between `0` (doesn't need to match) and 255 (must match exactly).
+- `trim.border.keep` — Specifies the number of pixels of the original border to leave untrimmed.
+
+#### `top;right;bottom;left`
+
+Specifies the number of pixels to remove from the sides of an image. Accepts four integers, separated by a semicolon, to set the trim on all four sides of an image at once.
+
+Trim can also be applied to a specific side using the following parameters:
+
+- `trim.top` — Specifies the number of pixels to remove from the top side of the image.
+- `trim.left` — Specifies the number of pixels to remove from the left side of the image
+- `trim.height` — Sets the height, in pixels, of the image from the top edge, then trims everything below the specified value.
+- `trim.width` — Sets the width of the image from the left edge, then trims everything to the right of the specified value.
```txt
trim=border
+ trim.height=800
+ // This sets the height of the image to 800 pixels from the top of the image, then trims everything below that point
- OR
+ trim.left=800
+ // This removes 800 pixels from the left of the image
- trim.border.color=%23000000
- trim.border.tolerance=5
- trim.border.keep=10
```
- ```js
- cf: {image: {trim: "border"}}
-
- OR
-
- cf: {image: {trim: {border: {color: "#000000", tolerance: 5, keep: 10}}}}
- ```
+ ```js
+ cf: {image: {trim: {top: 12, right: 78, bottom: 34, left: 56, width:678, height:678}}}
+ ```
\ No newline at end of file
diff --git a/src/content/partials/images/width.mdx b/src/content/partials/images/width.mdx
index b416e027be8..100ebd36981 100644
--- a/src/content/partials/images/width.mdx
+++ b/src/content/partials/images/width.mdx
@@ -1,22 +1,25 @@
---
{}
---
-import { Tabs, TabItem } from "~/components"
+import { Tabs, TabItem} from "~/components"
-Specifies maximum width of the image. Exact behavior depends on the `fit` mode; use the `fit=scale-down` option to ensure that the image will not be enlarged unnecessarily.
+
-Available options are a specified width in pixels or `auto`.
+### `width` | `w`
-**Alias:** `w`
+Sets the width of the output image in pixels using a positive integer value. By default, Cloudflare uses the original width of the input image.
+
+When `width` is set, the exact behavior depends on the `fit` parameter.
+
+Accepts the following values:
+
+- A number in pixels (for example, `250`).
+- `auto` — Automatically serves the image in the most optimal width based on available information about the browser and device. This method is supported only by Chromium browsers. For more information, refer to [Transform width parameter](/images/optimization/make-responsive-images/#transform-with-width-parameter).
```txt
width=250
- ```
-
-
- ```txt
w=250
```
@@ -29,6 +32,4 @@ Available options are a specified width in pixels or `auto`.
Ideally, image sizes should match the exact dimensions at which they are displayed on the page. If the page contains thumbnails with markup such as `![]()
`, then you can resize the image by applying `width=200`.
-[To serve responsive images](/images/transform-images/make-responsive-images/#transform-with-html-srcset), you can use the HTML `srcset` element and apply width parameters.
-
-`auto` - Automatically serves the image in the most optimal width based on available information about the browser and device. This method is supported only by Chromium browsers. For more information about this works, refer to [Transform width parameter](/images/transform-images/make-responsive-images/#transform-with-width-parameter).
+[To serve responsive images](/images/optimization/make-responsive-images/#transform-with-html-srcset), you can use the HTML `srcset` element and apply width parameters.
diff --git a/src/content/partials/images/zoom.mdx b/src/content/partials/images/zoom.mdx
index f6753898560..34131df8ba0 100644
--- a/src/content/partials/images/zoom.mdx
+++ b/src/content/partials/images/zoom.mdx
@@ -1,12 +1,13 @@
---
{}
---
-import { Tabs, TabItem } from "~/components"
+import { Tabs, TabItem} from "~/components"
-Specifies how closely the image is cropped toward the face when combined with the `gravity=face` option.
-Valid range is from `0` (includes as much of the background as possible) to `1` (crops the image as closely to the face as possible), decimals allowed. The default is `0`.
+
-This controls the threshold for how much of the surrounding pixels around the face will be included in the image and takes effect only if face(s) are detected in the image.
+### `zoom` | `face-zoom`
+
+Specifies how closely the image is cropped toward detected faces when combined with the `gravity=face` option. Accepts a valid range between `0.0` (includes as much of the background as possible) and `1.0` (crops the image as closely to the face as possible). The default is `0`.
@@ -14,17 +15,9 @@ This controls the threshold for how much of the surrounding pixels around the fa
zoom=0.1
```
-
- ```txt
- zoom=0.2
- OR
-
- face-zoom=0.2
- ```
-
```js
cf: {image: {zoom: 0.5}}
```
-
\ No newline at end of file
+
diff --git a/src/content/partials/version-management/product-limitations.mdx b/src/content/partials/version-management/product-limitations.mdx
index be87a484fe9..02c5622e7fb 100644
--- a/src/content/partials/version-management/product-limitations.mdx
+++ b/src/content/partials/version-management/product-limitations.mdx
@@ -70,7 +70,7 @@ Version Management does not currently support or have limited support for the fo
-- Changes made to [Image Transformations](/images/transform-images/) are not cloned when a new zone version is created.
+- Changes made to [Image Transformations](/images/optimization/transformations/overview/) are not cloned when a new zone version is created.