# Demos and architectures URL: https://developers.cloudflare.com/images/demos/ import { ExternalResources, GlossaryTooltip, ResourcesBySelector } from "~/components" Learn how you can use Images within your existing architecture. ## Demos Explore the following demo applications for Images. ## Reference architectures Explore the following reference architectures that use Images: --- # Get started URL: https://developers.cloudflare.com/images/get-started/ In this guide, you will get started with Cloudflare Images and make your first API request. ## Prerequisites Before you make your first API request, ensure that you have a Cloudflare Account ID and an API token. Refer to [Find zone and account IDs](/fundamentals/setup/find-account-and-zone-ids/) for help locating your Account ID and [Create an API token](/fundamentals/api/get-started/create-token/) to learn how to create an access your API token. ## Make your first API request ```bash curl --request POST \ --url https://api.cloudflare.com/client/v4/accounts//images/v1 \ --header 'Authorization: Bearer ' \ --header 'Content-Type: multipart/form-data' \ --form file=@./ ``` ## 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. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account. 2. Go to **Images** > **Transformations**. 3. Go to the specific zone where you want to enable transformations. 4. 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. ::: --- # Overview URL: https://developers.cloudflare.com/images/ import { CardGrid, Description, Feature, LinkTitleCard, Plan } from "~/components" Store, transform, optimize, and deliver images at scale 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/). There are two different ways to use Images: - **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. :::note[Image Resizing is now available as transformations] All Image Resizing features are available as transformations with Images. Each unique transformation is billed only once per 30 days. If you are using a legacy plan with Image Resizing, visit the [dashboard](https://dash.cloudflare.com/) to switch to an Imagesplan. ::: *** ## Features Use Cloudflare’s edge network to store your images. Accept uploads directly and securely from your users by generating a one-time token. Add up to 100 variants to specify how images should be resized for various use cases. Control access to your images by using signed URL tokens. *** ## More resources Engage with other users and the Images team on Cloudflare support forum. --- # Pricing URL: https://developers.cloudflare.com/images/pricing/ 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. 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 | ## Images Free On the Free plan, you can request up to 5,000 unique transformations each month for free. 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. - 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. ## Images Paid When you purchase an Images Paid plan, you can choose your own storage or add storage in Images. | 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 | If you optimize an image stored outside of Images, then you will be billed only for Images Transformed. Alternatively, Images Stored and Images Delivered apply only to images that are stored in your Images bucket. When you optimize an image that is stored in Images, then this counts toward Images Delivered — not Images Transformed. ## Metrics ### 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. For example, if you transform `thumbnail.jpg` as 100x100, then this counts as 1 unique transformation. If you transform the same `thumbnail.jpg` as 200x200, then this counts as a separate unique transformation. You are billed for the number of unique transformations that are counted during each billing period. Unique transformations are counted over a 30-day sliding window. For example, if you request `width=100/thumbnail.jpg` on June 30, then this counts once for that billing period. If you request the same transformation on July 1, then this will not count as a billable request, since the same transformation was already requested within the last 30 days. The `format` parameter counts as only 1 billable transformation, even if multiple copies of an image are served. In other words, if `width=100,format=auto/thumbnail.jpg` is served to some users as AVIF and to others as WebP, then this counts as 1 unique transformation instead of 2. #### Example A retail website has 1,000 original product images that get served in 5 different sizes each month. This results in 5,000 unique transformations — or a cost of $2.50 per month. ### Images Stored Storage in Images is available only with an Images Paid plan. You can purchase storage in increments of $5 for every 100,000 images stored per month. You can create predefined variants to specify how an image should be resized, such as `thumbnail` as 100x100 and `hero` as 1600x500. Only uploaded images count toward Images Stored; defining variants will not impact your storage limit. ### Images Delivered For images that are stored in Images, you will incur $1 for every 100,000 images delivered per month. This metric does not include transformed images that are stored in remote sources. Every image requested by the browser counts as 1 billable request. #### Example 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. --- # Apply blur URL: https://developers.cloudflare.com/images/manage-images/blur-variants/ 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. To blur an image: 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account. 2. Select **Images** > **Variants**. 3. Find the variant you want to blur and select **Edit** > **Customization Options**. 4. Use the slider to adjust the blurring effect. You can use the preview image to see how strong the blurring effect will be. 5. Select **Save**. The image should now display the blurred effect. --- # Browser TTL URL: https://developers.cloudflare.com/images/manage-images/browser-ttl/ 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/). ## Custom setting You can use two custom settings to control the Browser TTL, an account or a named variant. To adjust how long a browser should keep an image in the cache, set the TTL in seconds, similar to how the `max-age` header is set. The value should be an interval between one hour to one year. ### Browser TTL for an account Setting the Browser TTL per account overrides the default TTL. ```bash title="Example" curl --request PATCH 'https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/config' \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '{ "browser_ttl": 31536000 }' ``` When the Browser TTL is set to one year for all images, the response for the `cache-control` header is essentially `public`, `max-age=31536000`, `stale-while-revalidate=7200`. ### Browser TTL for a named variant Setting the Browser TTL for a named variant is a more granular option that overrides all of the above when creating or updating an image variant, specifically the `browser_ttl` option in seconds. ```bash title="Example" curl 'https://api.cloudflare.com/client/v4/accounts//images/v1/variants' \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '{ "id":"avatar", "options": { "width":100, "browser_ttl": 86400 } }' ``` When the Browser TTL is set to one day for images requested with this variant, the response for the `cache-control` header is essentially `public`, `max-age=86400`, `stale-while-revalidate=7200`. :::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. ::: --- # Configure webhooks URL: https://developers.cloudflare.com/images/manage-images/configure-webhooks/ 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/). To receive notifications for direct creator uploads: 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account. 2. Go to **Notifications** > **Destinations**. 3. From the Webhooks card, select **Create**. 4. Enter information for your webhook and select **Save and Test**. The new webhook will appear in the **Webhooks** card and can be attached to notifications. 5. Next, go to **Notifications** > **All Notifications** and select **Add**. 6. Under the list of products, locate **Images** and select **Select**. 7. Give your notification a name and optional description. 8. Under the **Webhooks** field, select the webhook that you recently created. 9. Select **Save**. --- # Delete images URL: https://developers.cloudflare.com/images/manage-images/delete-images/ You can delete an image from the Cloudflare Images storage using the dashboard or the API. ## Delete images via the Cloudflare dashboard 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account. 2. Select **Images**. 3. Find the image you want to remove and select **Delete**. 4. (Optional) To delete more than one image, select the checkbox next to the images you want to delete and then **Delete selected**. Your image will be deleted from your account. ## Delete images via the API Make a `DELETE` request to the [delete image endpoint](/api/resources/images/subresources/v1/methods/delete/). `{image_id}` must be fully URL encoded in the API call URL. ```bash curl --request DELETE https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/{image_id} \ --header "Authorization: Bearer " ``` After the image has been deleted, the response returns `"success": true`. --- # Create variants URL: https://developers.cloudflare.com/images/manage-images/create-variants/ Variants let you specify how images should be resized for different use cases. By default, images are served with a `public` variant, but you can create up to 100 variants to fit your needs. Follow these steps to create a variant. :::note Cloudflare Images can deliver SVG files but will not resize them because it is an inherently scalable format. Resize via the Cloudflare dashboard. ::: 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account. 2. Select **Images** > **Variants**. 3. Name your variant and select **Add New Variant**. 4. Define variables for your new variant, such as resizing options, type of fit, and specific metadata options. ## Resize via the API Make a `POST` request to [create a variant](/api/resources/images/subresources/v1/subresources/variants/methods/create/). ```bash curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/variants" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '{"id":"","options":{"fit":"scale-down","metadata":"none","width":1366,"height":768},"neverRequireSignedURLs":true} ``` ## Fit options The `Fit` property describes how the width and height dimensions should be interpreted. The chart below describes each of the options. | Fit Options | Behavior | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Scale down | The image is shrunk in size to fully fit within the given width or height, but will not be enlarged. | | Contain | The image is resized (shrunk or enlarged) to be as large as possible within the given width or height while preserving the aspect ratio. | | Cover | The image is resized to exactly fill the entire area specified by width and height and will be cropped if necessary. | | Crop | The image is shrunk and cropped to fit within the area specified by the 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`. | | Pad | The image is resized (shrunk or enlarged) to be as large as possible within the given width or height while preserving the aspect ratio. The extra area is filled with a background color (white by default). | ## Metadata options Variants allow you to choose what to do with your image’s metadata information. From the **Metadata** dropdown, choose: * Strip all metadata * Strip all metadata except copyright * Keep all metadata ## 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). --- # Delete variants URL: https://developers.cloudflare.com/images/manage-images/delete-variants/ You can delete variants via the Images dashboard or API. The only variant you cannot delete is public. :::caution Deleting a variant is a global action that will affect other images that contain that variant. ::: ## Delete variants via the Cloudflare dashboard 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account. 2. Select **Images** > **Variants**. 3. Find the variant you want to remove and select **Delete**. ## Delete variants via the API 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} \ --header "Authorization: Bearer " ``` After the variant has been deleted, the response returns `"success": true.` --- # Edit images URL: https://developers.cloudflare.com/images/manage-images/edit-images/ The Edit option provides you available options to modify a specific image. After choosing to edit an image, you can: * Require signed URLs to use with that particular image. * Use a cURL command you can use as an example to access the image. * Use fully-formed URLs for all the variants configured in your account. To edit an image: 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account. 2. In **Account Home**, select **Images**. 3. Locate the image you want to modify and select **Edit**. --- # Enable flexible variants URL: https://developers.cloudflare.com/images/manage-images/enable-flexible-variants/ Flexible variants allow you to create variants with dynamic resizing which can provide more options than regular variants allow. This option is not enabled by default. ## Enable flexible variants via the Cloudflare dashboard 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account. 2. Select **Images** > **Variants**. 3. Enable **Flexible variants**. ## Enable flexible variants via the API Make a `PATCH` request to the [Update a variant endpoint](/api/resources/images/subresources/v1/subresources/variants/methods/edit/). ```bash curl --request PATCH https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/config \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '{"flexible_variants": true}' ``` After activation, you can use [transformation parameters](/images/transform-images/transform-via-url/#options) on any Cloudflare image. For example, `https://imagedelivery.net/{account_hash}/{image_id}/w=400,sharpen=3` Note that flexible variants cannot be used for images that require a [signed delivery URL](/images/manage-images/serve-images/serve-private-images). --- # Export images URL: https://developers.cloudflare.com/images/manage-images/export-images/ Cloudflare Images supports image exports via the Cloudflare dashboard and API which allows you to get the original version of your image. ## Export images via the Cloudflare dashboard 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account. 2. Select **Images**. 3. Find the image or images you want to export. 4. 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**. Your images are downloaded to your machine. ## Export images via the API Make a `GET` request as shown in the example below. `` must be fully URL encoded in the API call URL. `GET accounts//images/v1//blob` --- # Manage uploaded images URL: https://developers.cloudflare.com/images/manage-images/ import { DirectoryListing } from "~/components" --- # Changelog URL: https://developers.cloudflare.com/images/platform/changelog/ import { ProductReleaseNotes } from "~/components"; {/* */} --- # Platform URL: https://developers.cloudflare.com/images/platform/ import { DirectoryListing } from "~/components" --- # Activate Polish URL: https://developers.cloudflare.com/images/polish/activate-polish/ import { Render } 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. ::: 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select the account and domain where you want to activate Polish. 2. Go to **Speed** > **Optimization** > **Image Optimization**. 3. Under **Polish**, select *Lossy* or *Lossless* from the drop-down menu. [*Lossy*](/images/polish/compression/#lossy) gives greater file size savings. 4. (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. --- # Cf-Polished statuses URL: https://developers.cloudflare.com/images/polish/cf-polished-statuses/ 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/). --- # Cloudflare Polish URL: https://developers.cloudflare.com/images/polish/ 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. When an image is fetched from your origin, our systems automatically optimize it in Cloudflare's cache. Subsequent requests for the same image will get the smaller, faster, optimized version of the image, improving the speed of your website. ![Example of Polish compression's quality.](~/assets/images/images/polish.png) ## 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. ## Availability --- # Polish compression URL: https://developers.cloudflare.com/images/polish/compression/ 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. :::caution[Warning] Polish may not be applied to origin responses that contain a `Vary` header. The only accepted `Vary` header is `Vary: Accept-Encoding`. ::: ## Compression options ### Off Polish is disabled and no compression is applied. Disabling Polish does not revert previously polished images to original, until they expire or are purged from the cache. ### Lossless The Lossless option attempts to reduce file sizes without changing any of the image pixels, keeping images identical to the original. It removes most metadata, like EXIF data, and losslessly recompresses image data. JPEG images may be converted to progressive format. On average, lossless compression reduces file sizes by 21 percent compared to unoptimized image files. The Lossless option prevents conversion of JPEG to WebP, because this is always a lossy operation. ### Lossy The Lossy option applies significantly better compression to images than the Lossless option, at a cost of small quality loss. When uncompressed, some of the redundant information from the original image is lost. On average, using Lossy mode reduces file sizes by 48 percent. This option also removes metadata from images. The Lossy option mainly affects JPEG images, but PNG images may also be compressed in a lossy way, or converted to JPEG when this improves compression. ### WebP When enabled, in addition to other optimizations, Polish creates versions of images converted to the WebP format. WebP compression is quite effective on PNG images, reducing file sizes by approximately 26 percent. It may reduce file sizes of JPEG images by around 17 percent, but this [depends on several factors](/images/polish/no-webp/). WebP is supported in all browsers except for Internet Explorer and KaiOS. You can learn more in our [blog post](https://blog.cloudflare.com/a-very-webp-new-year-from-cloudflare/). The WebP version is served only when the `Accept` header from the browser includes WebP, and the WebP image is significantly smaller than the lossy or lossless recompression of the original format: ```txt Accept: image/avif,image/webp,image/*,*/*;q=0.8 ``` Polish only converts standard image formats to the WebP format. If the origin server serves WebP images, Polish will not convert them, and will not optimize them. #### File size, image quality, and WebP Lossy formats like JPEG and WebP are able to generate files of any size, and every image could theoretically be made smaller. However, reduction in file size comes at a cost of reduction in image quality. Reduction of file sizes below each format's optimal size limit causes disproportionally large losses in quality. Re-encoding of files that are already optimized reduces their quality more than it reduces their file size. Cloudflare will not convert from JPEG to WebP when the conversion would make the file bigger, or would reduce image quality by more than it would save in file size. If you choose the Lossless Polish setting, then WebP will be used very rarely. This is due to the fact that, in this mode, WebP is only adequate for PNG images, and cannot improve compression for JPEG images. Although WebP compresses better than JPEG on average, there are exceptions, and in some occasions JPEG compresses better than WebP. Cloudflare tries to detect these cases and keep the JPEG format. If you serve low-quality JPEG images at the origin (quality setting 60 or lower), it may not be beneficial to convert them to WebP. This is because low-quality JPEG images have blocky edges and noise caused by compression, and these distortions increase file size of WebP images. We recommend serving high-quality JPEG images (quality setting between 80 and 90) at your origin server to avoid this issue. If your server or Content Management System (CMS) has a built-in image converter or optimizer, it may interfere with Polish. It does not make sense to apply lossy optimizations twice to images, because quality degradation will be larger than the savings in file size. ## Polish interaction with Image optimization Polish will not be applied to URLs using image transformations. Resized images already have lossy compression applied where possible, so they do not need the optimizations provided by Polish. Use the `format=auto` option to allow use of WebP and AVIF formats. --- # WebP may be skipped URL: https://developers.cloudflare.com/images/polish/no-webp/ Polish avoids converting images to the WebP format when such conversion would increase the file size, or significantly degrade image quality. Polish also optimizes JPEG images, and the WebP format is not always better than a well-optimized JPEG. To enhance the use of WebP in Polish, enable the [Lossy option](/images/polish/compression/#lossy). When you create new JPEG images, save them with a slightly higher quality than usually necessary. We recommend JPEG quality settings between 85 and 95, but not higher. This gives Polish enough headroom for lossy conversion to WebP and optimized JPEG. ## In the **lossless** mode, it is not feasible to convert JPEG to WebP WebP is actually a name for two quite different image formats: WebP-lossless (similar to PNG) and WebP-VP8 (similar to JPEG). When the [Lossless option](/images/polish/compression/#lossless) is enabled, Polish will not perform any optimizations that change image pixels. This allows Polish to convert only between lossless image formats, such as PNG, GIF, and WebP-lossless. JPEG images will not be converted though, because the WebP-VP8 format does not support the conversion from JPEG without quality loss, and the WebP-lossless format does not compress images as heavily as JPEG. In the lossless mode, Polish can still apply lossless optimizations to JPEG images. This is a unique feature of the JPEG format that does not have an equivalent in WebP. ## Low-quality JPEG images do not convert well to WebP When JPEG files are already heavily compressed (for example, saved with a low quality setting like `q=50`, or re-saved many times), the conversion to WebP may not be beneficial, and may actually increase the file size. This is because lossy formats add distortions to images (for example, JPEG makes images blocky and adds noise around sharp edges), and the WebP format can not tell the difference between details of the image it needs to preserve and unwanted distortions caused by a previous compression. This forces WebP to wastefully use bytes on keeping the added noise and blockyness, which increases the file size, and makes compression less beneficial overall. Polish never makes files larger. When we see that the conversion to WebP increases the file size, we skip it, and keep the smaller original file format. ## For some images conversion to WebP can degrade quality too much The WebP format, in its more efficient VP8 mode, always loses some quality when compressing images. This means that the conversion from JPEG always makes WebP images look slightly worse. Polish ensures that file size savings from the conversion outweigh the quality loss. Lossy WebP has a significant limitation: it can only keep one shade of color per 4 pixels. The color information is always stored at half of the image resolution. In high-resolution photos this degradation is rarely noticeable. However, in images with highly saturated colors and sharp edges, this limitation can result in the WebP format having noticeably pixelated or smudged edges. Additionally, the WebP format applies smoothing to images. This feature hides blocky distortions that are a characteristic of low-quality JPEG images, but on the other hand it can cause loss of fine textures and details in high-quality images, making them look airbrushed. Polish tries to avoid degrading images for too little gain. Polish keeps the JPEG format when it has about the same size as WebP, but better quality. ## Sometimes older formats are better than WebP The WebP format has an advantage over JPEG when saving images with soft or blurry content, and when using low quality settings. WebP has fewer advantages when storing high-quality images with fine textures or noise. Polish applies optimizations to JPEG images too, and sometimes well-optimized JPEG is simply better than WebP, and gives a better quality and smaller file size at the same time. We try to detect these cases, and keep the JPEG format when it works better. Sometimes animations with little motion are more efficient as GIF than animated WebP. The WebP format does not support progressive rendering. With [HTTP/2 prioritization](/speed/optimization/protocol/enhanced-http2-prioritization/) enabled, progressive JPEG images may appear to load quicker, even if their file sizes are larger. ## 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. 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. For this reason Polish will not create the smallest possible file sizes. Instead, Polish aims to maximize the quality to file size ratio, to create the smallest possible files while preserving good quality. The quality level we stop at is carefully chosen to minimize visual distortion, while still having a high compression ratio. --- # Reference URL: https://developers.cloudflare.com/images/reference/ import { DirectoryListing } from "~/components"; --- # Security URL: https://developers.cloudflare.com/images/reference/security/ To further ensure the security and efficiency of image optimization services, you can adopt Cloudflare products that safeguard against malicious activities. Cloudflare security products like [Cloudflare WAF](/waf/), [Cloudflare Bot Management](/bots/get-started/bm-subscription/) and [Cloudflare Rate Limiting](/waf/rate-limiting-rules/) can enhance the protection of your image optimization requests against abuse. This proactive approach ensures a reliable and efficient experience for all legitimate users. --- # Troubleshooting URL: https://developers.cloudflare.com/images/reference/troubleshooting/ ## 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. *** ## 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. * 9422, 9424, 9516, 9517, 9518, 9522 & 9523 — Internal errors. Please contact support if you encounter these errors. *** ## Limits * Maximum image size is 100 megapixels (meaning 10.000×10.000 pixels large). Maximum file size is 100 MB. GIF/WebP animations are limited to 50 megapixels total (sum of sizes of all frames). * Image Resizing is not compatible with [Bringing Your Own IPs (BYOIP)](/byoip/). *** ## 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/). *** ## Caching and purging Changes to image dimensions or other resizing options always take effect immediately — no purging necessary. 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. 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. --- # Bind to Workers API URL: https://developers.cloudflare.com/images/transform-images/bindings/ 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/). You can bind the Images API to your Worker to transform, resize, and encode images without requiring them to be accessible through a URL. For example, when you allow Workers to interact with Images, you can: - Transform an image, then upload the output image directly into R2 without serving to the browser. - Optimize an image stored in R2 by passing the blob of bytes representing the image, instead of fetching the public URL for the image. - Resize an image, overlay the output over a second image as a watermark, then resize this output into a final result. Bindings can be configured in the Cloudflare dashboard for your Worker or in the `wrangler.toml` file in your project's directory. ## Setup The Images binding is enabled on a per-Worker basis. You can define variables in the `wrangler.toml` file of your Worker project's directory. These variables are bound to external resources at runtime, and you can then interact with them through this variable. To bind Images to your Worker, add the following to the end of your `wrangler.toml` file: ```txt [images] binding = "IMAGES" # i.e. available in your Worker on env.IMAGES ``` Within your Worker code, you can interact with this binding by using `env.IMAGES`. ## Methods ### `.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`. ### `.draw()` - Allows [drawing an image](/images/transform-images/draw-overlays/) over another image. - 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. ### `.output()` * Defines the [output format](/images/transform-images/) for the transformed image such as AVIF, WebP, and JPEG. For example, to rotate, resize, and blur an image, then output the image as AVIF: ```js const info = await env.IMAGES.info(stream); // stream contains a valid image, and width/height is available on the info object const response = ( await env.IMAGES.input(stream) .transform({ rotate: 90 }) .transform({ width: 128 }) .transform({ blur: 20 }) .output({ format: "image/avif" }) ).response(); return response; ``` ### `.info()` - Outputs information about the image, such as `format`, `fileSize`, `width`, and `height`. In this example, the transformed image is outputted as a WebP. Responses from the Images binding are not automatically cached. Workers lets you interact directly with the Cache API to customize cache behavior using Workers. You can implement logic in your script to store transformations in Cloudflare’s cache. ## Interact with your Images binding locally The Images API can be used in local development through [Wrangler](/workers/wrangler/install-and-update/), the command-line interface for Workers. Using the Images binding in local development will not incur usage charges. Wrangler supports two different versions of the Images API: - A high-fidelity version that supports all features that are available through the Images API. This is the same version that Cloudflare runs globally in production. - A low-fidelity version that supports only a subset of features, such as resizing and rotation. To test the high-fidelity version of Images, you can run `wrangler dev`: ```txt npx wrangler dev ``` This creates a local-only environment that mirrors the production environment where Cloudflare runs the Images API. You can test your Worker with all available transformation features before deploying to production. To test the low-fidelity version of Images, add the `--experimental-images-local-mode` flag: ```txt npm wrangler dev --experimental-images-local-mode ``` Currently, this version supports only `width`, `height`, `rotate`, and `format`. --- # Control origin access URL: https://developers.cloudflare.com/images/transform-images/control-origin-access/ 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/). ```js export default { async fetch(request, env, ctx) { // Here you can compute arbitrary imageURL and // resizingOptions from any request data ... return fetch(imageURL, { cf: { image: resizingOptions } }); }, }; ``` This code will be run for every request, but the source code will not be accessible to website visitors. This allows the code to perform security checks and contain secrets required to access the images in a controlled manner. The examples below are only suggestions, and do not have to be followed exactly. You can compute image URLs and resizing options in many other ways. :::caution[Warning] When testing image transformations, make sure you deploy the script and test it from a regular web browser window. The preview in the dashboard does not simulate transformations. ::: ## Hiding the image server ```js export default { async fetch(request, env, ctx) { const resizingOptions = { /* resizing options will be demonstrated in the next example */ }; const hiddenImageOrigin = "https://secret.example.com/hidden-directory"; const requestURL = new URL(request.url); // Append the request path such as "/assets/image1.jpg" to the hiddenImageOrigin. // You could also process the path to add or remove directories, modify filenames, etc. const imageURL = hiddenImageOrigin + requestURL.path; // This will fetch image from the given URL, but to the website's visitors this // will appear as a response to the original request. Visitor’s browser will // not see this URL. return fetch(imageURL, { cf: { image: resizingOptions } }); }, }; ``` ## Preventing access to full-size images On top of protecting the original image URL, you can also validate that only certain image sizes are allowed: ```js export default { async fetch(request, env, ctx) { const imageURL = … // detail omitted in this example, see the previous example const requestURL = new URL(request.url) const resizingOptions = { width: requestURL.searchParams.get("width"), } // If someone tries to manipulate your image URLs to reveal higher-resolution images, // you can catch that and refuse to serve the request (or enforce a smaller size, etc.) if (resizingOptions.width > 1000) { throw Error("We don’t allow viewing images larger than 1000 pixels wide") } return fetch(imageURL, {cf:{image:resizingOptions}}) },}; ``` ## Avoid image dimensions in URLs You do not have to include actual pixel dimensions in the URL. You can embed sizes in the Worker script, and select the size in some other way — for example, by naming a preset in the URL: ```js export default { async fetch(request, env, ctx) { const requestURL = new URL(request.url); const resizingOptions = {}; // The regex selects the first path component after the "images" // prefix, and the rest of the path (e.g. "/images/first/rest") const match = requestURL.path.match(/images\/([^/]+)\/(.+)/); // You can require the first path component to be one of the // predefined sizes only, and set actual dimensions accordingly. switch (match && match[1]) { case "small": resizingOptions.width = 300; break; case "medium": resizingOptions.width = 600; break; case "large": resizingOptions.width = 900; break; default: throw Error("invalid size"); } // The remainder of the path may be used to locate the original // image, e.g. here "/images/small/image1.jpg" would map to // "https://storage.example.com/bucket/image1.jpg" resized to 300px. const imageURL = "https://storage.example.com/bucket/" + match[2]; return fetch(imageURL, { cf: { image: resizingOptions } }); }, }; ``` ## Authenticated origin Cloudflare image transformations cache resized images to aid performance. Images stored with restricted access are generally not recommended for resizing because sharing images customized for individual visitors is unsafe. However, in cases where the customer agrees to store such images in public cache, Cloudflare supports resizing images through Workers. At the moment, this is supported on authenticated AWS, Azure, Google Cloud, SecureAuth origins and origins behind Cloudflare Access. ```js null {9} // generate signed headers (application specific) const signedHeaders = generatedSignedHeaders(); fetch(private_url, { headers: signedHeaders cf: { image: { format: "auto", "origin-auth": "share-publicly" } } }) ``` When using this code, the following headers are passed through to the origin, and allow your request to be successful: - `Authorization` - `Cookie` - `x-amz-content-sha256` - `x-amz-date` - `x-ms-date` - `x-ms-version` - `x-sa-date` - `cf-access-client-id` - `cf-access-client-secret` For more information, refer to: - [AWS docs](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html) - [Azure docs](https://docs.microsoft.com/en-us/rest/api/storageservices/List-Containers2#request-headers) - [Google Cloud docs](https://cloud.google.com/storage/docs/aws-simple-migration) - [Cloudflare Zero Trust docs](/cloudflare-one/identity/service-tokens/) - [SecureAuth docs](https://docs.secureauth.com/2104/en/authentication-api-guide.html) --- # Draw overlays and watermarks URL: https://developers.cloudflare.com/images/transform-images/draw-overlays/ 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: ```js fetch(imageURL, { cf: { image: { width: 800, height: 600, draw: [ { url: 'https://example.com/branding/logo.png', // draw this image bottom: 5, // 5 pixels from the bottom edge right: 5, // 5 pixels from the right edge fit: 'contain', // make it fit within 100x50 area width: 100, height: 50, opacity: 0.8, // 20% transparent }, ], }, }, }); ``` ## Draw options The `draw` property is an array. Overlays are drawn in the order they appear in the array (the last array entry is the topmost layer). Each item in the `draw` array is an object, which can have the following properties: * `url` * Absolute URL of the image file to use for the drawing. It can be any of the supported file formats. For drawing watermarks or non-rectangular overlays, Cloudflare recommends that you use PNG or WebP images. * `width` and `height` * 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). * `opacity` * Floating-point number between `0` (transparent) and `1` (opaque). For example, `opacity: 0.5` makes overlay semitransparent. * `repeat` * If set to `true`, the overlay image will be tiled to cover the entire area. This is useful for stock-photo-like watermarks. * If set to `"x"`, the overlay image will be tiled horizontally only (form a line). * If set to `"y"`, the overlay image will be tiled vertically only (form a line). * `top`, `left`, `bottom`, `right` * Position of the overlay image relative to a given edge. Each property is an offset in pixels. `0` aligns exactly to the edge. For example, `left: 10` positions left side of the overlay 10 pixels from the left edge of the image it is drawn over. `bottom: 0` aligns bottom of the overlay with bottom of the background image. Setting both `left` and `right`, or both `top` and `bottom` is an error. 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). * `rotate` * Number of degrees to rotate the overlay image by. Same as [for the main image](/images/transform-images/transform-via-workers/#fetch-options). ## Draw using the Images binding When [interacting with Images through a binding](/images/transform-images/bindings/), the Images API supports a `.draw()` method. The accepted options for the overlaid image are `opacity`, `repeat`, `top`, `left`, `bottom`, and `right`. ```js // Fetch image and watermark const img = await fetch('https://example.com/image.png'); const watermark = await fetch('https://example.com/watermark.png'); const response = await env.IMAGES.input(img.body) .transform({ width: 1024 }) .draw(watermark.body, { "opacity": 0.25, "repeat": true }) .output({ format: "image/avif" }) .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. 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. ```js // Fetch image and watermark const response = ( await env.IMAGES.input(img.body) .transform({ width: 1024 }) .draw(watermark.body, { "opacity": 0.25, "repeat": true }) .output({ format: "image/avif" }) ).response(); ``` ## Examples ### Stock Photo Watermark ```js image: { draw: [ { url: 'https://example.com/watermark.png', repeat: true, // Tiled over entire image opacity: 0.2, // and subtly blended }, ]; } ``` ### Signature ```js image: { draw: [ { url: 'https://example.com/by-me.png', // Predefined logo/signature bottom: 5, // Positioned near bottom right corner right: 5, }, ]; } ``` ### Centered icon ```js image: { draw: [ { url: 'https://example.com/play-button.png', // Center position is the default }, ]; } ``` ### Combined Multiple operations can be combined in one image: ```js image: { draw: [ { url: 'https://example.com/watermark.png', repeat: true, opacity: 0.2 }, { url: 'https://example.com/play-button.png' }, { url: 'https://example.com/by-me.png', bottom: 5, right: 5 }, ]; } ``` --- # Transform images URL: https://developers.cloudflare.com/images/transform-images/ 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/). ## Supported formats and limitations ### Supported input formats * JPEG * PNG * GIF (including animations) * WebP (including animations) * SVG ### 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 pixels¹ | 640 pixels | | Other | 12,000 pixels | N/A | | WebP | N/A | 2,560 pixels for lossy; 1920 pixels for lossless | ¹Hard 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. Cloudflare does not support the HEIC (HEIF) format and does not plan to support it. 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`). --- # Integrate with frameworks URL: https://developers.cloudflare.com/images/transform-images/integrate-with-frameworks/ ## Next.js Image transformations can be used automatically with the Next.js [`` component](https://nextjs.org/docs/api-reference/next/image). To use image transformations, define a global image loader or multiple custom loaders for each `` component. Next.js will request the image with the correct parameters for width and quality. Image transformations will be responsible for caching and serving an optimal format to the client. ### Global Loader 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. ```ts module.exports = { 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). ```ts const normalizeSrc = (src: string) => { return src.startsWith("/") ? src.slice(1) : src; }; export default function cloudflareLoader({ src, width, quality, }: { src: string; width: number; quality?: number }) { if (process.env.NODE_ENV === "development") { return src; } const params = [`width=${width}`]; if (quality) { params.push(`quality=${quality}`); } const paramsString = params.join(","); return `/cdn-cgi/image/${paramsString}/${normalizeSrc(src)}`; } ``` ### Custom Loaders Alternatively, define a loader for each `` component. ```js import Image from 'next/image'; const normalizeSrc = src => { return src.startsWith('/') ? src.slice(1) : src; }; const cloudflareLoader = ({ src, width, quality }) => { if (process.env.NODE_ENV === "development") { return src; } const params = [`width=${width}`]; if (quality) { params.push(`quality=${quality}`); } const paramsString = params.join(','); return `/cdn-cgi/image/${paramsString}/${normalizeSrc(src)}`; }; const MyImage = props => { return ( Picture of the author

); }; ``` :::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: `https:///cdn-cgi/image/${paramsString}/${normalizeSrc(src)}` ::: --- # Make responsive images URL: https://developers.cloudflare.com/images/transform-images/make-responsive-images/ 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. ## Transform with HTML `srcset` The `srcset` [feature of HTML](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images) allows browsers to automatically choose an image that is best suited for user’s screen resolution. `srcset` requires providing multiple resized versions of every image, and with Cloudflare’s image transformations this is an easy task to accomplish. 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. ### `srcset` for high-DPI displays For high-DPI display you need two versions of every image. One for `1x` density, suitable for typical desktop displays (such as HD/1080p monitors or low-end laptops), and one for `2x` high-density displays used by almost all mobile phones, high-end laptops, and 4K desktop displays. Some mobile phones have very high-DPI displays and could use even a `3x` resolution. However, while the jump from `1x` to `2x` is a clear improvement, there are diminishing returns from increasing the resolution further. The difference between `2x` and `3x` is visually insignificant, but `3x` files are two times larger than `2x` files. Assuming you have an image `product.jpg` in the `assets` folder and you want to display it at a size of `960px`, the code is as follows: ```html

``` In the URL path used in this example, the `src` attribute is for images with the usual "1x" density. `/cdn-cgi/image/` is a special path for resizing images. This is followed by `width=960` which resizes the image to have a width of 960 pixels. `/assets/product.jpg` is a URL to the source image on the server. The `srcset` attribute adds another, high-DPI image. The browser will automatically select between the images in the `src` and `srcset`. In this case, specifying `width=1920` (two times 960 pixels) and adding `2x` at the end, informs the browser that this is a double-density image. It will be displayed at the same size as a 960 pixel image, but with double the number of pixels which will make it look twice as sharp on high-DPI displays. Note that it does not make sense to scale images up for use in `srcset`. That would only increase file sizes without improving visual quality. The source images you should use with `srcset` must be high resolution, so that they are only scaled down for `1x` displays, and displayed as-is or also scaled down for `2x` displays. ### `srcset` for responsive images When you want to display an image that takes a certain percentage of the window or screen width, the image should have dimensions that are appropriate for a visitor’s screen size. Screen sizes vary a lot, typically from 320 pixels to 3840 pixels, so there is not a single image size that fits all cases. With `` you can offer the browser several possible sizes and let it choose the most appropriate size automatically. By default, the browser assumes the image will be stretched to the full width of the screen, and will pick a size that is closest to a visitor’s screen size. In the `src` attribute the browser will pick any size that is a good fallback for older browsers that do not understand `srcset`. ```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. 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. #### The `sizes` attribute If the image takes 50% of the screen (or window) width: ```html

``` The `vw` unit is a percentage of the viewport (screen or window) width. If the image can have a different size depending on media queries or other CSS properties, such as `max-width`, then specify all the conditions in the `sizes` attribute: ```html

``` In this example, `sizes` says that for screens smaller than 640 pixels the image is displayed at full viewport width; on all larger screens the image stays at 640px. Note that one of the options in `srcset` is 1280 pixels, because an image displayed at 640 CSS pixels may need twice as many image pixels on a high-dpi (`2x`) display. ## WebP images `srcset` is useful for pixel-based formats such as PNG, JPEG, and WebP. It is unnecessary for vector-based SVG images. HTML also [supports the `