导航|地址|刷新
Manage hosted images with Workers

Skip to contentDocumentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/images/llms.txt
Use this file to discover all available pages before exploring further.

Docs Directory API SDKs Changelog

Search

Log in

Cloudflare Images

/

Overview

Get started

Introduction

Key concepts

Limits and formats

Optimization

Features

Remote images (transformations)

Overview

Define source origins

Create transformation flows

Transform via fetch

Control origin access

Draw overlays and watermarks

Integrate with frameworks

Set up rewrite rules

Preserve Content Credentials

Hosted images

Serve uploaded images

Create predefined variants

Enable flexible variants

Apply blur

Delete variants

Preserve Content Credentials

Browser TTL

Serve images from custom domains

Serve private images

Optimize with Workers

Draw overlays and watermarks

Make responsive images

Storage

Upload images

Methods

Upload via URL

Upload via custom path

Accept user-uploaded images

Upload via batch API

Upload via a Worker

Upload via Sourcing Kit

Overview

Enable Sourcing Kit

Edit sources

Credentials

Configure webhooks

Manage hosted images

Edit images

Export images

Delete images

Manage with Workers

Demos and architectures

Pricing

Cloudflare Polish

Overview

Activate Polish

Polish compression

Cf-Polished statuses

WebP may be skipped

Images API Reference ↗API

Reference

Troubleshooting

Security

Tutorials

Optimize mobile viewing

Transform user-uploaded images before uploading to R2

Examples

Platform

Changelog

Agent resources

Agent setup ↗

Cloudflare Skills ↗

Code Mode MCP Server ↗

Domain-specific MCP Servers ↗MCP

Cloudflare Images llms.txt ↗

Cloudflare Images llms-full.txt ↗

Cloudflare Docs llms.txt ↗

Cloudflare Docs llms-full.txt ↗

Home

/Cloudflare Images

/Storage

/Manage with Workers

Manage hosted images with Workers

Last updated Jun 10, 2026|Copy as Markdown|View as Markdown|Agent setup

OverviewSetupMethods .upload(image, options) .list(options) .image(imageId) .image(imageId).details() .image(imageId).bytes() .image(imageId).update(options) .image(imageId).delete()Examples Upload an image from a request body Upload a base64-encoded image List images with pagination Get the details for a single image Stream the original bytes for an image Update image metadata Delete an image Ingest a remote image into Images storageType definitions ImageMetadata ImageListError handlingLocal developmentRelated resources

A binding connects your Worker to external resources on the Developer Platform, like Images, R2 buckets, or KV namespaces.

When managing hosted images, the Images binding lets your Worker upload, list, retrieve, update, and delete hosted images without calling the REST API directly. The hosted namespace exposes storage and management operations. This binding can also be used to optimize hosted images.

Bindings can be configured in the Cloudflare dashboard for your Worker or in the Wrangler configuration file in your project's directory.

Billing

Hosted image operations require a paid Images plan with storage. Calls count against your storage allowances in the same way as if you had used the REST API or the dashboard.

Setup

To bind Images to your Worker, add the following to your Wrangler configuration file:

{ "images": { "binding": "IMAGES", // available in your Worker on env.IMAGES },}

[images]binding = "IMAGES"

Within your Worker code, you can manage hosted images using the env.IMAGES.hosted namespace.

Methods

The env.IMAGES.hosted namespace lets you upload and list images across your account. To manage a specific image, call .image(imageId) to get a handle, then call a method on it.

.upload(image, options)

Uploads a new image to your account. You can pass image bytes as a stream or an ArrayBuffer. Returns ImageMetadata.

Accepts the following options as an ImageUploadOptions object:

idstring — A custom ID to assign to the image. If omitted, Cloudflare generates a UUID. Refer to Upload to a custom path.

filenamestring — The filename to associate with the image.

requireSignedURLsboolean — Sets whether the image should require a signed URL to view. Defaults to false.

metadataRecord<string, unknown> — Arbitrary metadata to store alongside the image.

creatorstring — A user-defined identifier for the image creator.

encoding'base64' — Set to base64 if the provided bytes are base64-encoded. The binding will decode them before upload.

.list(options)

Lists images in your account with pagination. Returns ImageList.

Accepts the following options as an ImageListOptions object:

limitnumber — The maximum number of images to return in a page.

cursorstring — The continuation token returned by the previous list() call. Omit on the first page.

sortOrder'asc' | 'desc' — The order to sort results in by uploaded timestamp. Defaults to asc.

creatorstring — Filter results to images uploaded with this creator identifier.

.image(imageId)

Returns a handle for a single hosted image. The imageId can be the Cloudflare-generated UUID or a custom ID.

The handle itself does not make a network request, so it is cheap to construct.

.image(imageId).details()

Gets the metadata for an image. Returns ImageMetadata or null if no image with the given ID exists.

.image(imageId).bytes()

Gets the raw bytes of an image. Returns ReadableStream<Uint8Array> or null if no image with the given ID exists. This streams the original uploaded file. Pass the image bytes to .input() to optimize before serving, or use the URLs returned in ImageMetadata.variants or the image delivery URL to serve a predefined variant.

.image(imageId).update(options)

Updates the metadata or access controls for an image. All fields are optional; only the specified fields will be changed. Returns ImageMetadata with the updated values.

Accepts the following options as an ImageUpdateOptions object:

requireSignedURLsboolean — Whether signed URLs should be required to view the image. Cannot be set to true on an image that was uploaded with a custom ID.

metadataRecord<string, unknown> — Replacement metadata for the image. This replaces the existing metadata rather than merging into it.

creatorstring — A user-defined identifier for the image creator.

.image(imageId).delete()

Deletes an image. Returns true if the image was deleted or false if no image with the given ID existed.

Examples

Upload an image from a request body

export default { async fetch(request, env) { if (!request.body) { return new Response("Missing body", { status: 400 }); } const image = await env.IMAGES.hosted.upload(request.body, { filename: "upload.jpg", metadata: { source: "worker" }, requireSignedURLs: false, }); return Response.json(image); },};

export default { async fetch(request, env) { if (!request.body) { return new Response("Missing body", { status: 400 }); } const image = await env.IMAGES.hosted.upload(request.body, { filename: "upload.jpg", metadata: { source: "worker" }, requireSignedURLs: false, }); return Response.json(image); },};

Upload a base64-encoded image

Set encoding: "base64" and the binding will decode the body for you before uploading.

export default { async fetch(request, env) { if (!request.body) { return new Response("Missing body", { status: 400 }); } const image = await env.IMAGES.hosted.upload(request.body, { encoding: "base64", filename: "upload.png", }); return Response.json(image); },};

export default { async fetch(request, env) { if (!request.body) { return new Response("Missing body", { status: 400 }); } const image = await env.IMAGES.hosted.upload(request.body, { encoding: "base64", filename: "upload.png", }); return Response.json(image); },};

List images with pagination

export default { async fetch(request, env) { let cursor; const ids = []; do { const page = await env.IMAGES.hosted.list({ limit: 100, cursor }); ids.push(...page.images.map((image) => image.id)); cursor = page.cursor; } while (cursor); return Response.json({ count: ids.length, ids }); },};

export default { async fetch(request, env) { let cursor: string | undefined; const ids: string[] = []; do { const page = await env.IMAGES.hosted.list({ limit: 100, cursor }); ids.push(...page.images.map((image) => image.id)); cursor = page.cursor; } while (cursor); return Response.json({ count: ids.length, ids }); },};

Get the details for a single image

export default { async fetch(request, env) { const details = await env.IMAGES.hosted.image("IMAGE_ID").details(); if (!details) { return new Response("Not found", { status: 404 }); } return Response.json(details); },};

export default { async fetch(request, env) { const details = await env.IMAGES.hosted.image("IMAGE_ID").details(); if (!details) { return new Response("Not found", { status: 404 }); } return Response.json(details); },};

Stream the original bytes for an image

export default { async fetch(request, env) { const bytes = await env.IMAGES.hosted.image("IMAGE_ID").bytes(); if (!bytes) { return new Response("Not found", { status: 404 }); } return new Response(bytes); },};

export default { async fetch(request, env) { const bytes = await env.IMAGES.hosted.image("IMAGE_ID").bytes(); if (!bytes) { return new Response("Not found", { status: 404 }); } return new Response(bytes); },};

Update image metadata

export default { async fetch(request, env) { const updated = await env.IMAGES.hosted.image("IMAGE_ID").update({ metadata: { reviewed: true }, }); return Response.json(updated); },};

export default { async fetch(request, env) { const updated = await env.IMAGES.hosted.image("IMAGE_ID").update({ metadata: { reviewed: true }, }); return Response.json(updated); },};

Delete an image

export default { async fetch(request, env) { const deleted = await env.IMAGES.hosted.image("IMAGE_ID").delete(); return new Response(deleted ? "Deleted" : "Not found", { status: deleted ? 200 : 404, }); },};

export default { async fetch(request, env) { const deleted = await env.IMAGES.hosted.image("IMAGE_ID").delete(); return new Response(deleted ? "Deleted" : "Not found", { status: deleted ? 200 : 404, }); },};

Ingest a remote image into Images storage

This example fetches an image from a remote URL, uploads it into your Images account, and returns the first variant URL.

export default { async fetch(request, env) { const upstream = await fetch("https://example.com/photo.jpg"); if (!upstream.ok || !upstream.body) { return new Response("Upstream fetch failed", { status: 502 }); } const image = await env.IMAGES.hosted.upload(upstream.body, { filename: "photo.jpg", metadata: { source: "example.com" }, }); return Response.json({ id: image.id, variant: image.variants[0], }); },};

export default { async fetch(request, env) { const upstream = await fetch("https://example.com/photo.jpg"); if (!upstream.ok || !upstream.body) { return new Response("Upstream fetch failed", { status: 502 }); } const image = await env.IMAGES.hosted.upload(upstream.body, { filename: "photo.jpg", metadata: { source: "example.com" }, }); return Response.json({ id: image.id, variant: image.variants[0], }); },};

Type definitions

ImageMetadata

Returned by operations that retrieve, create, or update an image.

idstring
The unique identifier for the image.

filenamestringoptional
The original filename supplied at upload time.

uploadedstringoptional
The date and time the image was uploaded, as an ISO 8601 string.

requireSignedURLsboolean
Whether signed URLs are required to access this image. Refer to Serve private images.

metaRecord<string, unknown>optional
User-supplied metadata associated with the image.

variantsArray<string>
Fully-formed URLs for each variant configured on your account. Refer to Create variants.

draftbooleanoptional
Whether the image is in a draft state (no bytes uploaded yet). Drafts are typically only seen on accounts using Direct Creator Uploads.

creatorstringoptional
A user-defined identifier for the image creator.

ImageList

Returned by list().

imagesArray<ImageMetadata>
The images in this page of results.

cursorstringoptional
A continuation token to pass to the next list() call. Only present when there are more results.

listCompleteboolean
true when there are no further pages, false otherwise.

Error handling

Methods that fail throw an ImagesError — .upload(), .list(), .update() — with the following properties:

codenumber
A numeric error code that identifies the failure mode.

messagestring
A human-readable description of the error.

Methods that fetch a single image — .details(), .bytes(), and .delete() — return null or false for "not found" rather than throwing.

You may want to wrap operations that can throw in a try...catch block.

Local development

When you run wrangler dev, operations for managing hosted images are served by a local mock that stores images in an embedded KV namespace. The mock supports every method documented on this page, so you can develop and test your Worker offline.

The mock is only suitable for local development. To exercise the real Images service from your local environment, run wrangler dev --remote.

Related resources

Optimize with Workers — Use the binding to optimize images from a Worker.

Upload via the REST API — The equivalent HTTP API.

Manage hosted images — Dashboard and API workflows for managing stored images.

PreviousDelete imagesNextDemos and architectures

Was this helpful?

YesNo

Edit pageReport issue

On this page

Overview

Setup

Methods

.upload(image, options)

.list(options)

.image(imageId)

.image(imageId).details()

.image(imageId).bytes()

.image(imageId).update(options)

.image(imageId).delete()

Examples

Upload an image from a request body

Upload a base64-encoded image

List images with pagination

Get the details for a single image

Stream the original bytes for an image

Update image metadata

Delete an image

Ingest a remote image into Images storage

Type definitions

ImageMetadata

ImageList

Error handling

Local development

Related resources

Edit pageReport issue

Getting started
PlansContact salesPartnersFind a partnerStartupsUnder attack?Domain name search

Company
AboutCareersInvestorsPressPress kitGlobal network

Public interest
Project GalileoAthenian ProjectCloudflare for CampaignsProject FairshotImpact/ESG

Compliance
Compliance resourcesTrust HubData ProtectionResponsible AITransparency reportReport abuse

Resources
App innovation reportCloudflare RadarCase studiesStatusSupportEventsBlog

Developers
DocumentationLearning centerCommunity
…(内容过长已截断)

------
导航页打开网址