스킬 파일

Cloudflare Images

Name: Cloudflare Images
Author: Juamnoz

Store and transform images with Cloudflare Images API and transformations. Use when: uploading images, implementing direct creator uploads, creating variants, generating signed URLs, optimizing formats (WebP/AVIF), transforming via Workers, or debugging CORS, multipart, AVIF limits, metadata stripping, cache issues, or error codes 9401-9413.

Juamnoz0 스타2026. 2. 16.

직업
카테고리: 미디어

스킬 내용

Status: Production Ready ✅ Last Updated: 2026-01-21 Dependencies: Cloudflare account with Images enabled Latest Versions: Cloudflare Images API v2, @cloudflare/[email protected]

Recent Updates (2025):

February 2025: Content Credentials support (C2PA standard) - preserve image provenance chains, automatic cryptographic signing of transformations
August 2025: AI Face Cropping GA (gravity=face with zoom control, GPU-based RetinaFace, 99.4% precision)
May 2025: Media Transformations origin restrictions (default: same-domain only, configurable via dashboard)
Upcoming: Background removal, generative upscale (planned features)

Deprecation Notice: Mirage deprecated September 15, 2025. Migrate to Cloudflare Images for storage/transformations or use native <img loading="lazy"> for lazy loading.

Overview

Two features: Images API (upload/store with variants) and (resize any image via URL or Workers).

관련 스킬

Cloudflare Images | Skills Pool

curl -X POST https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/images/v1 \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@./image.jpg'

<img src="/cdn-cgi/image/width=800,quality=85/uploads/photo.jpg" />

fetch(imageURL, {
  cf: {
    image: { width: 800, quality: 85, format: 'auto', gravity: 'face', zoom: 0.8 }
  }
});

// ✅ CORRECT
const formData = new FormData();
formData.append('file', fileInput.files[0]);
await fetch(uploadURL, {
  method: 'POST',
  body: formData // Browser sets multipart/form-data automatically
});

// ❌ WRONG
await fetch(uploadURL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' }, // CORS error
  body: JSON.stringify({ file: base64Image })
});

const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB

if (file.size > MAX_FILE_SIZE) {
  alert('File too large. Please select an image under 10MB.');
  return;
}

// ✅ CORRECT
formData.append('file', imageFile);

// ❌ WRONG
formData.append('image', imageFile); // 400 error
formData.append('photo', imageFile); // 400 error

ARCHITECTURE:
Browser → Backend API → POST /direct_upload → Returns uploadURL → Browser uploads to uploadURL

// ✅ CORRECT
fetch(imageURL, {
  cf: {
    image: {
      width: 800,
      quality: 85,
      format: 'auto'
    }
  }
});

// ❌ WRONG
fetch(imageURL, {
  cf: {
    image: {
      width: 'large', // Must be number
      quality: 150 // Max 100
    }
  }
});

// ✅ CORRECT
if (url.pathname.startsWith('/images/')) {
  const originalPath = url.pathname.replace('/images/', '');
  const originURL = `https://storage.example.com/${originalPath}`;
  return fetch(originURL, { cf: { image: { width: 800 } } });
}

// ❌ WRONG
if (url.pathname.startsWith('/images/')) {
  // Fetches worker's own URL, causes loop
  return fetch(request, { cf: { image: { width: 800 } } });
}

// ✅ CORRECT
const imageURL = "https://example.com/images/photo%20name.jpg";

// ❌ WRONG
const imageURL = "http://example.com/images/photo.jpg"; // HTTP not allowed
const imageURL = "https://example.com/images/photo name.jpg"; // Space not encoded

const filename = "photo name.jpg";
const imageURL = `https://example.com/images/${encodeURIComponent(filename)}`;

// Verify URL before transforming
const originResponse = await fetch(imageURL, { method: 'HEAD' });
const contentType = originResponse.headers.get('content-type');

if (!contentType?.startsWith('image/')) {
  return new Response('Not an image', { status: 400 });
}

return fetch(imageURL, { cf: { image: { width: 800 } } });

const MAX_MEGAPIXELS = 100;

if (width * height > MAX_MEGAPIXELS * 1_000_000) {
  return new Response('Image too large', { status: 413 });
}

// ✅ CORRECT - Use named variants for private images
await uploadImage({
  file: imageFile,
  requireSignedURLs: true // Use named variants: /public, /avatar, etc.
});

// ❌ WRONG - Flexible variants don't support signed URLs
// Cannot use: /w=400,sharpen=3 with requireSignedURLs=true

// SVGs can be served but not resized
// Use any variant name as placeholder
// https://imagedelivery.net/<HASH>/<SVG_ID>/public

// SVG will be served at original size regardless of variant settings

// ✅ CORRECT - JPEG preserves metadata
fetch(imageURL, {
  cf: {
    image: {
      width: 800,
      format: 'jpeg', // or 'auto' (may become jpeg)
      metadata: 'keep' // Preserves most EXIF including GPS
    }
  }
});

// ❌ WRONG - WebP/PNG ignore metadata setting
fetch(imageURL, {
  cf: {
    image: {
      format: 'webp',
      metadata: 'keep' // NO EFFECT - always stripped for WebP/PNG
    }
  }
});

// ✅ RECOMMENDED - Use format=auto instead of explicit avif
fetch(imageURL, {
  cf: {
    image: {
      width: 2000,
      format: 'auto' // Cloudflare chooses best format
    }
  }
});

// ⚠️ MAY FAIL - Explicit AVIF with large dimensions
fetch(imageURL, {
  cf: {
    image: {
      width: 2000,
      format: 'avif' // May fail if >1200px
    }
  }
});

// ✅ WORKAROUND - Use WebP for larger images
if (width > 1200) {
  format = 'webp'; // WebP supports larger dimensions
} else {
  format = 'avif'; // AVIF for smaller images
}

cp templates/upload-api-basic.ts src/upload.ts
# Edit with your account ID and API token

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    const imageKey = url.pathname.replace('/images/', '');
    const originURL = `https://r2-bucket.example.com/${imageKey}`;

    return fetch(originURL, {
      cf: {
        image: {
          width: 800,
          quality: 85,
          format: 'auto'
        }
      }
    });
  }
};

Cloudflare Images

Overview

Cloudflare Images

Overview

Quick Start

Upload Methods

Image Transformations

Variants

Signed URLs

Critical Rules

Always Do

Never Do

Known Issues Prevention

Issue #1: Direct Creator Upload CORS Error

Issue #2: Error 5408 - Upload Timeout

Issue #3: Error 400 - Invalid File Parameter

Issue #4: CORS Preflight Failures

Issue #5: Error 9401 - Invalid Arguments

Issue #6: Error 9402 - Image Too Large

Issue #7: Error 9403 - Request Loop

Issue #8: Error 9406/9419 - Invalid URL Format

Issue #9: Error 9412 - Non-Image Response

Issue #10: Error 9413 - Max Image Area Exceeded

Issue #11: Flexible Variants + Signed URLs Incompatibility

Issue #12: SVG Resizing Limitation

Issue #13: EXIF Metadata Stripped by Format

Issue #14: AVIF Resolution Limit Ambiguity

Issue #15: Image Cache by Device Type (Community-reported)

Issue #16: PNG Not Cached by Default

Using Bundled Resources

Templates (templates/)

References (references/)

Scripts (scripts/)

Advanced Topics

Troubleshooting

Problem: Images not transforming

Problem: Direct upload returns CORS error

Problem: Worker transformations return 9403 loop error

Problem: Signed URLs not working

Problem: Images uploaded but not appearing

Problem: Re-uploaded image still shows old version

Problem: PNG images not caching

Official Documentation

Package Versions

Songsee

Video Frames

Gifgrep

Qqbot Media

Camsnap

Openai Whisper Api