Cloudflare Images -- Storage and Global Delivery

In this tutorial, you'll learn about Cloudflare Images. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

This tutorial explains how Cloudflare Images provides a complete image pipeline -- upload, store, transform, and deliver images at the edge -- replacing multiple services with a single integrated platform.

Why Cloudflare Images Matters

Managing images at scale requires storage buckets, transformation pipelines, CDN delivery, and optimization services. Each component has its own API, pricing, and maintenance overhead. Cloudflare Images combines all of these into one service. You upload an image once, and it is stored securely, transformed on demand via URL parameters, and delivered from over 330 edge locations. This eliminates the complexity of stitching together S3, ImageMagick, and CDN configurations. For product catalogs, social platforms, or media sites, this unified approach reduces infrastructure costs and development time.

Real-world use: Doda Browser's screenshot sharing feature uploads user screenshots to Cloudflare Images. Each screenshot is automatically transformed into three variants (thumbnail, preview, full) and served from edge locations with sub-100ms load times. The team manages this with a single API integration instead of three separate services.

Cloudflare Images Architecture

flowchart LR
  A[Upload image] --> B[Cloudflare Images API]
  B --> C[Store at edge]
  C --> D[Generate variants]
  D --> E[Deliver via CDN]
  E --> F[thumbnail variant]
  E --> G[preview variant]
  E --> H[full variant]
  C --> I[Transform on demand]
  I --> E
  style B fill:#f90,color:#fff
  style C fill:#f90,color:#fff
  style E fill:#f90,color:#fff

Uploading Images

You can upload images directly to Cloudflare Images via the API or by providing a URL for the service to fetch. Each upload returns a unique image ID that you use for delivery and transformations.

# Upload an image by providing a URL
curl -X POST "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/images/v1" \
  -H "Authorization: Bearer API_TOKEN" \
  -F "url=https://example.com/photo.jpg" \
  -F "metadata={\"key\":\"product_photo\"}"
# Expected output:
# {"success":true,"result":{"id":"img_abc123","filename":"photo.jpg","uploaded":"2026-06-23T12:00:00Z","variants":["https://imagedelivery.net/ACCOUNT_HASH/img_abc123/public","https://imagedelivery.net/ACCOUNT_HASH/img_abc123/thumbnail"]}}

The API returns a delivery URL prefix. Append the variant name (public, thumbnail) to get the transformed version. Variants are defined in the dashboard and control output dimensions, format, and quality.

# Upload a direct file upload
curl -X POST "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/images/v1" \
  -H "Authorization: Bearer API_TOKEN" \
  -F "file=@/path/to/photo.jpg" \
  -F "metadata={\"alt\":\"Product photo\"}"
# Expected output:
# {"success":true,"result":{"id":"img_def456","filename":"photo.jpg"}}

Delivering Images with Variants

Variants are predefined transformation profiles. You create them in the Cloudflare dashboard or via API. Each variant specifies width, height, fit mode, quality, and format.

<!-- Image delivery with variants -->
<img
  src="https://imagedelivery.net/ACCOUNT_HASH/img_abc123/thumbnail"
  srcset="
    https://imagedelivery.net/ACCOUNT_HASH/img_abc123/thumbnail 150w,
    https://imagedelivery.net/ACCOUNT_HASH/img_abc123/public 800w,
    https://imagedelivery.net/ACCOUNT_HASH/img_abc123/full 1920w"
  sizes="(max-width: 600px) 150px, (max-width: 1200px) 800px, 1920px"
  alt="Product photo"
  loading="lazy"
/>

The browser automatically selects the appropriate variant based on viewport width. Thumbnails for small screens, full resolution for large screens. All variations are delivered from the edge cache.

Managing Images

The API supports listing, deleting, and updating image metadata. This is essential for keeping your image library organized at scale.

# List all images with pagination
curl -s "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/images/v1?page=1&per_page=10" \
  -H "Authorization: Bearer API_TOKEN" | jq '.result.images[] | {id, filename, uploaded}'
# Expected output:
# {"id":"img_abc123","filename":"photo.jpg","uploaded":"2026-06-23T12:00:00Z"}
# {"id":"img_def456","filename":"banner.png","uploaded":"2026-06-23T11:30:00Z"}

# Delete an image by ID
curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/images/v1/img_abc123" \
  -H "Authorization: Bearer API_TOKEN"
# Expected output:
# {"success":true,"result":{}}

Deleting an image removes all variants and cached copies from every edge location. There is no additional purge step required.

FAQ

Practice Questions

1. What is the difference between URL-based uploads and direct file uploads in Cloudflare Images?
2. How do variants help optimize image delivery for different screen sizes?
3. What happens when you delete an image from Cloudflare Images?

Summary

Cloudflare Images provides an end-to-end image pipeline with unified storage, transformation, and delivery at the edge. Images are uploaded once, transformed into predefined variants, and served from over 330 locations worldwide. The single API replaces the need for separate storage, processing, and CDN services, reducing infrastructure complexity and operational costs.

Built by the developers of Doda Browser, DodaZIP, and Durga Antivirus Pro -- security-first tools for the modern web.