dotfiles/.agents/skills/cloudflare-deploy/references/images/api.md

API Reference

Workers Binding API

# wrangler.toml
[images]
binding = "IMAGES"

Transform Images

const imageResponse = await env.IMAGES
  .input(fileBuffer)
  .transform({ width: 800, height: 600, fit: "cover", quality: 85, format: "avif" })
  .output();
return imageResponse.response();

Transform Options

interface TransformOptions {
  width?: number;        height?: number;
  fit?: "scale-down" | "contain" | "cover" | "crop" | "pad";
  quality?: number;      // 1-100
  format?: "avif" | "webp" | "jpeg" | "png";
  dpr?: number;          // 1-3
  gravity?: "auto" | "left" | "right" | "top" | "bottom" | "face" | string;
  sharpen?: number;      // 0-10
  blur?: number;         // 1-250
  rotate?: 90 | 180 | 270;
  background?: string;   // CSS color for pad
  metadata?: "none" | "copyright" | "keep";
  brightness?: number;   contrast?: number;   gamma?: number;  // 0-2
}

Draw/Watermark

await env.IMAGES.input(baseImage)
  .draw(env.IMAGES.input(watermark).transform({ width: 100 }), { top: 10, left: 10, opacity: 0.8 })
  .output();

REST API

Upload Image

curl -X POST https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1 \
  -H "Authorization: Bearer {token}" -F file=@image.jpg -F metadata='{"key":"value"}'

Other Operations

GET  /accounts/{account_id}/images/v1/{image_id}      # Get details
DELETE /accounts/{account_id}/images/v1/{image_id}   # Delete
GET  /accounts/{account_id}/images/v1?page=1         # List

URL Transform API

https://imagedelivery.net/{hash}/{id}/width=800,height=600,fit=cover,format=avif

Params: w=, h=, fit=, q=, f=, dpr=, gravity=, sharpen=, blur=, rotate=, background=, metadata=

Direct Creator Upload

// 1. Get upload URL (backend)
const { result } = await fetch(
  `https://api.cloudflare.com/client/v4/accounts/${accountId}/images/v2/direct_upload`,
  { method: 'POST', headers: { 'Authorization': `Bearer ${token}` },
    body: JSON.stringify({ requireSignedURLs: false }) }
).then(r => r.json());

// 2. Client uploads to result.uploadURL
const formData = new FormData();
formData.append('file', file);
await fetch(result.uploadURL, { method: 'POST', body: formData });

Error Codes

Code	Message	Solution
5400	Invalid format	Use JPEG, PNG, GIF, WebP
5401	Too large	Max 100MB
5403	Invalid transform	Check params
9413	Rate limit	Implement backoff