[Images] Images Bindings (#20141)

* Images updates for bindings

* Added Images Binding to Workers

* Fixed relative links

* Small edits and added content on caching

* Update code example

Author: dcpena

src/content/docs/images/transform-images/bindings.mdx

@@ -0,0 +1,96 @@
+---
+pcx_content_type: how-to
+title: Bind to Workers API
+sidebar:
+  order: 4
+---
+
+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 [`fetch()` options](/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 `fetch()` options, 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 })
+        .output({ format: "image/avif" })
+      ).response();
+ 
+return response;
+```
+
+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`.

src/content/docs/images/transform-images/draw-overlays.mdx

@@ -2,7 +2,7 @@
 pcx_content_type: reference
 title: Draw overlays and watermarks
 sidebar:
-  order: 3
+  order: 5
 
 ---
 
@@ -68,6 +68,39 @@ The `draw` property is an array. Overlays are drawn in the order they appear in
 * `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 [other `fetch()` options](/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
 

src/content/docs/workers/local-development.mdx

@@ -41,6 +41,7 @@ npx wrangler dev
 | Durable Objects                     | ✅                  | ✅                   |
 | Email Bindings                      | ❌                  | ✅                   |
 | Hyperdrive                          | ✅                  | ✅                   |
+| Images                              | ✅                  | ✅                   |
 | KV                                  | ✅                  | ✅                   |
 | mTLS                                | ❌                  | ✅                   |
 | Queues                              | ✅                  | ❌                   |

src/content/docs/workers/runtime-apis/bindings/images.mdx

@@ -0,0 +1,8 @@
+---
+pcx_content_type: navigation
+title: Images
+external_link: /images
+head: []
+description: Store, transform, optimize, and deliver images at scale.
+
+---

src/content/docs/workers/wrangler/configuration.mdx

@@ -658,6 +658,23 @@ id = "<ID>"
 
 </WranglerConfig>
 
+### Images 
+
+[Cloudflare Images](/images/transform-images/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.
+
+`binding` (required). The name of the binding used to refer to the Images API.
+
+<WranglerConfig>
+
+```toml title="wrangler.toml"
+[[images]]
+binding = "IMAGES" # i.e. available in your Worker on env.IMAGES
+```
+
+</WranglerConfig>
+
 ### KV namespaces
 
 [Workers KV](/kv/api/) is a global, low-latency, key-value data store. It stores data in a small number of centralized data centers, then caches that data in Cloudflare’s data centers after access.