Images

Images nedir?

Cloudflare Images bugün tek bir ürün ama iki kullanım modu var, ve fatura bu ikisi arasında bölünüyor:

“Optimize remote images — Keep your images on your own origin, in R2, or with any storage provider. Cloudflare pulls the original image, applies optimizations at the edge, and caches the optimized image.” “Upload and deliver with Images — Store, optimize, and deliver images globally with zero infrastructure management.”

Nasıl çalışır?

URL biçimleri

Kendi origin’inden veya R2’den:

https://<ZONE>/cdn-cgi/image/<SECENEKLER>/<KAYNAK-GORSEL>

Images deposundan:

https://imagedelivery.net/<HESAP_HASH>/<GORSEL_ID>/<VARIANT>

Kendi alan adından (alan adının proxied, yani turuncu bulut olması şart):

https://ornek.com/cdn-cgi/imagedelivery/<HESAP_HASH>/<GORSEL_ID>/<VARIANT>

Workers’da iki ayrı yol var: fetch alt isteğinde cf.image nesnesi (“available on any zone that hosts a Worker, including *.workers.dev subdomains”), ve ham baytlarla çalışan Images binding’i (“Unlike the URL interface, which requires images to be accessible through a URL, the binding works with raw image bytes”).

Cache ve fatura ilişkisi

“On a cache hit — Cloudflare serves the optimized image directly from the edge without contacting the origin or re-applying the optimization parameters.” “On a cache miss — Cloudflare fetches the original image from the source origin, applies the requested parameters… caches the transformed result…” “Each unique combination of source image and parameters is cached and billed separately. The first request for each unique version within a calendar month is billed as one unique transformation, regardless of cache status.”

Fit seçenekleri

Format seçimi

• auto — tarayıcının desteklediği en verimli formatı sunuyor. Hosted görsellerde varsayılan.
• avif — “AVIF encoding can be an order of magnitude slower… If the image is too large to be quickly encoded to AVIF, then Cloudflare will fall back to WebP or JPEG.”
• webp — quality=100 ile kayıpsız WebP.
• jpeg — progressive; baseline-jpeg eski cihazlar için.
• json — görsel hakkında bilgi döner, görselin kendisini değil.

İki otomatik geri düşüş kuralı: çıktı 50×50’den küçük veya 3000×3000’den büyük ise progressive JPEG istenmiş olsa bile baseline JPEG dönüyor.

Dikkat çeken parametreler

• dpr — üst sınır 2. Daha yükseği yok.
• quality — varsayılan 85. Sayısal (1–100) veya algısal (high, medium-high, medium-low, low).
• sharpen — 0–10, “The recommended value for downscaled images is 1.”
• gravity=auto — “saliency algorithm to detect the most visually interesting pixels”. face ile yüz odaklı kırpma, zoom yalnızca gravity=face ile çalışıyor.
• segment=foreground — arka planı şeffaflaştırıyor; “uses an open-source model called BiRefNet through Workers AI.”
• upscale=generate — ESRGAN ile AI büyütme. “the AI model runs a single pass at the nearest supported scale (2x or 4x)” ve “has higher latency than upscale=interpolate due to GPU inference.”
• border — yalnızca Workers’da.
• blur — güvenlik için kullanma: “This parameter should not be used to reliably obscure image content when optimizing via URL, as the URL can be modified to remove the blur parameter.”
• metadata — varsayılan copyright. keep seçersen GPS konumu dahil EXIF korunuyor. WebP ve PNG çıktılarında metadata her hâlükârda siliniyor.

Ne zaman kullanılır, ne zaman kullanılmaz

Uygun olduğu işler

• Kullanıcı yüklemeli ürün ve profil görsellerini tek bir hattan geçirmek
• Responsive görsel üretmek — ama breakpoint sayısını bilinçli seçerek
• Origin’i görsel işleme yükünden tamamen kurtarmak
• İstemciye API token’ı vermeden yükleme yaptırmak (Direct Creator Upload)
• R2’de saklayıp yalnızca dönüşüm için Images kullanmak — Cloudflare’in “typically the most cost-effective” dediği desen

Uygun olmadığı işler

• SVG boyutlandırma. Yapılmıyor, parametreler yok sayılıyor.
• Kimlik doğrulamalı origin’den çekmek. İstek anonimleştiriliyor: çerez yok, auth yok, özel başlık yok.
• Tek bir dönüştürülmüş görseli purge etmek. Yalnızca orijinali purge edebiliyorsun, o da hepsini siliyor.
• Görselin fiziksel olarak nerede saklandığını bölgeye sabitlemek. “Jurisdictional Restrictions (storage) options are not supported today.”
• BYOIP ile birlikte. Uzak görsel dönüşümlerinde uyumsuz.
• Polish ile birlikte. İkisi aynı işi yapıyor; Cloudflare açıkça birlikte kullanmamayı söylüyor.
• Video. Animasyonlu GIF/WebP için Cloudflare’in kendi tavsiyesi: “we recommend using video formats like MP4 and WebM for best performance.”

Somut örnekler

1. Uzak görseli dönüştürmek

https://ornek.com/cdn-cgi/image/width=800,quality=80,format=auto/urunler/kirmizi-canta.jpg

Üç parametre = tek bir benzersiz dönüşüm. Aynı görseli 400 piksel isteyince ikinci bir dönüşüm oluyor.

2. Responsive — ama kaç dönüşüm ödediğini bilerek

https://ornek.com/cdn-cgi/image/width=auto,wbreakpoints=480;960,format=auto/kapak.jpg

Varsayılan breakpoint’ler 320;768;960;1200 — dört tane. Yukarıdaki gibi ikiye indirirsen görsel başına maliyet yarıya iniyor.

3. Workers’da binding ile

// wrangler.jsonc
{ "images": { "binding": "IMAGES" } }

export default {
  async fetch(request, env) {
    const kaynak = await fetch("https://ornek.com/ham/foto.jpg");
    const sonuc = await env.IMAGES
      .input(kaynak.body)
      .transform({ width: 1200, fit: "cover" })
      .draw((await fetch("https://ornek.com/logo.png")).body, {
        bottom: 20, right: 20, opacity: 0.7,
      })
      .output({ format: "image/avif", quality: 80 });

    return sonuc.response();
  },
};

4. Kaynak origin’i doğru tanımlamak

Varsayılan yalnızca kendi zone’un. Başka bir alan adı ekliyorsan alt alan adları otomatik gelmiyor:

b.com          →  media.b.com REDDEDILIR
*.b.com        →  media.b.com kabul edilir

5. Signed URL ile private görsel

Panel: Hosted Images → Keys. İmzalama HMAC-SHA-256 ile, exp parametresi ekleniyor ve imza sig olarak yazılıyor. Cloudflare’in kendi uyarısı:

“Never hardcode your signing key in source code. Store it as a secret using npx wrangler secret put.”

Demo 1: Format farkını gerçekten ölçmek ve AVIF limitini patlatmak

Bu demo iki şeyi kanıtlıyor: format seçiminin bayt cinsinden karşılığı, ve AVIF’in belgelenmiş 1.200 piksel kenar limitine çarpınca ne olduğu.

Ön koşullar: Ubuntu sunucu, Cloudflare’de aktif bir zone, panelde Images → Transformations açık.

Adım 1 — Test görselini hazırla

sudo apt update && sudo apt install -y imagemagick curl jq webp
mkdir -p ~/img-lab && cd ~/img-lab

# Genis bir test gorseli uret — AVIF limitini asacak kadar
magick -size 3000x2000 gradient:navy-orange -pointsize 200 \
  -fill white -gravity center -annotate 0 "TEST" ham.jpg
identify ham.jpg
ls -lh ham.jpg

Dosyayı zone’unda erişilebilir bir yere koy (/var/www/html/img-lab/ham.jpg).

Terminal — identify çıktısında 3000x2000 ve ls -lh çıktısında dosya boyutu; ikisi aynı karede

Adım 2 — Aynı görseli üç formatta iste ve baytları karşılaştır

ZONE=ornek.com
YOL=/img-lab/ham.jpg

for F in jpeg webp avif; do
  curl -s -o /dev/null -w "$F: %{size_download} bayt  %{time_total}s  tip=%{content_type}\n" \
    "https://$ZONE/cdn-cgi/image/width=1000,quality=80,format=$F$YOL"
done

# Tarayicinin gordugu hali: format=auto
curl -s -o /dev/null -w "auto (Accept: avif): %{size_download} bayt  tip=%{content_type}\n" \
  -H "Accept: image/avif,image/webp,*/*" \
  "https://$ZONE/cdn-cgi/image/width=1000,quality=80,format=auto$YOL"

Terminal — dört satır: her formatın bayt boyutu, süresi ve content-type değeri. AVIF'in belirgin şekilde küçük olması görünsün

Adım 3 — Dönüşümün gerçekten uygulandığını doğrula

curl -sI "https://$ZONE/cdn-cgi/image/width=1000,format=webp$YOL" \
  | grep -iE 'cf-resized|cf-cache-status|content-type|content-length'

cf-resized başlığı yoksa dönüşüm hiç denenmemiş demektir — bu, sorun gidermede ilk bakılacak yer.

Terminal — curl -I çıktısında cf-resized başlığı ve cf-cache-status değeri (ilk istekte MISS, ikincide HIT) okunacak şekilde

Adım 4 — AVIF’in 1.200 piksel limitini gerçekten aş

Belgelenen limit: uzak görsellerde kenar en fazla 12.000 piksel, ama AVIF için 1.200.

# 1200 piksel — sinirda, AVIF donmeli
curl -s -o /dev/null -w "1200px: tip=%{content_type} boyut=%{size_download}\n" \
  "https://$ZONE/cdn-cgi/image/width=1200,format=avif$YOL"

# 1600 piksel — limit asildi
curl -s -o /dev/null -w "1600px: tip=%{content_type} boyut=%{size_download}\n" \
  "https://$ZONE/cdn-cgi/image/width=1600,format=avif$YOL"

İkinci istekte content-type AVIF olmayan bir değere düşüyor. Cloudflare bunu belgeliyor: “If the image is too large to be quickly encoded to AVIF, then Cloudflare will fall back to WebP or JPEG.”

Terminal — iki satır yan yana; birinde content-type image/avif, diğerinde image/webp veya image/jpeg. Sessiz geri düşüşün kanıtı bu

Adım 5 — Fatura sayacını gör

Panel: Images → Overview. Bu demoda kaç benzersiz dönüşüm ürettiğini say: her farklı width + format + quality kombinasyonu bir tane.

Panel ekran görüntüsü — Images Overview sayfasında Unique Transformations sayacı ve aylık kotaya göre konumu

Demo 2: Proxy’lenmemiş hostname’de dönüşüm çalışmıyor

Bu, kurulum sırasında en sık takılınan yer ve hata mesajı yardımcı olmuyor. Demonun amacı önce arızayı üretmek, sonra düzeltmek.

Adım 1 — Gri bulutlu bir alt alan adı hazırla

Panelde img-test.ornek.com için bir A kaydı oluştur ve proxy durumunu DNS only (gri bulut) yap. Aynı görseli oradan da servis et.

dig +short A img-test.ornek.com
curl -sI https://img-test.ornek.com/img-lab/ham.jpg | grep -iE '^HTTP|server|cf-ray'

dig sunucunun gerçek IP’sini döndürüyor ve yanıtta cf-ray başlığı yok — istek Cloudflare’e hiç uğramıyor.

Terminal — dig çıktısında origin IP'si, altında curl -I çıktısında server: nginx ve cf-ray başlığının yokluğu

Adım 2 — Dönüşümü dene

curl -s -o /dev/null -w "gri bulut: %{http_code} tip=%{content_type}\n" \
  "https://img-test.ornek.com/cdn-cgi/image/width=400,format=webp/img-lab/ham.jpg"

curl -s "https://img-test.ornek.com/cdn-cgi/image/width=400,format=webp/img-lab/ham.jpg" | head -c 300

Dönüşüm çalışmıyor — çünkü /cdn-cgi/ yolunu işleyen Cloudflare kenarı devrede değil. Sunucu ya 404 veriyor ya da yolu bilmediği için hata döndürüyor.

Terminal — HTTP kodu ve gövdenin ilk satırları; nginx'in 404 sayfası ya da benzeri bir hata görünsün

Adım 3 — Turuncu buluta al ve tekrar dene

Panelden aynı kaydın proxy durumunu Proxied yap, sonra:

sleep 15
curl -sI "https://img-test.ornek.com/cdn-cgi/image/width=400,format=webp/img-lab/ham.jpg" \
  | grep -iE '^HTTP|cf-ray|cf-resized|content-type'

Artık cf-ray ve cf-resized başlıkları var, içerik tipi image/webp.

Terminal — cf-ray, cf-resized ve content-type: image/webp başlıkları bir arada; önceki adımın çıktısıyla yan yana olursa fark net görünür

Adım 4 — İkinci bir tuzağı da göster: kaynak origin kısıtı

# Baska bir alan adindaki gorseli kaynak olarak kullanmayi dene
curl -s -o /dev/null -w "dis kaynak: %{http_code}\n" \
  "https://ornek.com/cdn-cgi/image/width=400/https://baska-site.com/foto.jpg"

Varsayılan olarak reddediliyor: “By default, Cloudflare accepts only source images from the zone where your transformations are served.” Panelden Images → Transformations → Sources altına ekleyince çalışıyor.

İki bölmeli görüntü — solda reddedilen isteğin HTTP kodu, sağda panelde Sources ekranına eklenen alan adı ve ardından başarılı istek

Ölçüm tablosu

Fiyatlandırma

Rakamlar 1 Eylül 2026’da Images pricing sayfasından alındı ve workers.cloudflare.com/pricing ile ürün sayfasında birebir aynı çıktı — üç resmî kaynak birbirini doğruluyor.

Ücretsiz

“On the Free plan, you can request up to 5,000 unique transformations each month for free.”

Aşarsan: mevcut cache’tekiler sunulmaya devam ediyor, yenileri 9422 hatası dönüyor, ve fatura çıkmıyor. Aynı zone’daki bir kaynaksa onerror=redirect ile orijinale yönlendirebilirsin.

Ücretli

“Every image requested by the browser counts as one billable request.” Cloudflare’in kendi örneği: 10 görsellik bir ürün sayfası, ayda 10.000 ziyaret = 100.000 teslim = 1,00 USD.

Cloudflare’in yayımladığı örnek hesaplar

Uzak görseller: 2.000 görsel × 5 boyut = 10.000 benzersiz dönüşüm → 5.000 dahil, 5.000 faturalanır → 2,50 USD.

R2 + Images: 5.000 görsel × 5 MB = 25 GB depolama (10 GB dahil, 15 GB × 0,015 USD = 0,22 USD) + 10.000 dönüşüm (2,50 USD) = toplam 2,72 USD. Class A yazma ve Class B okuma ücretsiz kotanın içinde kalıyor.

Lisanslama ve hukuki çerçeve

Images tescilli bir hizmettir ve Cloudflare Hizmet Şartlarına tabidir.

Veri yerelleştirme — Türkiye. Cloudflare Türkiye’yi yönetilen bir Regional Services bölgesi olarak destekliyor:

“Turkey — Cloudflare will only use data centers that are physically located within Turkey to decrypt and service HTTPS traffic.”

Uyumluluk matrisinde Images için satır şöyle:

¹ “Only when using a Custom Domain set to a region.” ² “Logs / Analytics not supported for CMB = EU. Jurisdictional Restrictions (storage) options are not supported today. All other features are available to all CMB regions.”

Images dokümantasyonunda veri yerleşimi hiç geçmiyor. residency, localization, jurisdiction, Turkey ve GDPR kelimelerinin tamamı sıfır eşleşme veriyor (pozitif kontrollü doğrulandı). Bu bilgi yalnızca Data Localization dokümanlarında var — Images’ı kullanacak bir ekibin oraya bakması gerektiğini bilmesi gerekiyor.

Metadata ve kişisel veri. metadata=keep seçersen EXIF’in çoğu korunuyor — GPS konumu dahil. Kullanıcı yüklemeli görsellerde varsayılan copyright değerini değiştirmeden önce iki kez düşün. Not: WebP ve PNG çıktılarında metadata her hâlükârda siliniyor.

Sık yapılan hatalar

Polish ile birlikte açmak

“Do not activate Polish and image transformations simultaneously. Image transformations already apply lossy compression, which makes Polish redundant.”

Zaten çalışmıyor da: “Polish skips image URLs processed by Cloudflare Images.”

width=auto bırakıp faturaya şaşırmak

Dört breakpoint = dört dönüşüm. wbreakpoints ile daralt.

Gri bulutlu kayıtta dönüşüm beklemek

/cdn-cgi/image/ yolunu Cloudflare kenarı işliyor. Kayıt proxy’lenmemişse istek oraya hiç uğramıyor.

Alan adı ekleyip alt alan adlarını unutmak

b.com eklemek media.b.com’u kapsamıyor; *.b.com yazman gerekiyor.

Worker’ı /* kapsamında çalıştırmak

“Resizing is ‘forgotten’ as soon as one Worker calls another. Do not use Workers scoped to the entire domain /*.”

Dönüştürülmüş görseli purge etmeye çalışmak

/cdn-cgi/ ile başlayan URL’ler purge edilemiyor. Orijinali purge et — tüm varyantları birlikte gidiyor.

Kimlik doğrulamalı origin’den görsel çekmeyi denemek

İstek anonimleştiriliyor: çerez, auth başlığı ve özel başlıklar gönderilmiyor.

Signed URL ile flexible variants’ı birleştirmeye çalışmak

Çalışmıyor. Aynı şekilde özel ID’li görseller private yapılamıyor ve private görseller custom path desteklemiyor.

Binding’de cache’i açmamak

Her çağrı tam bir çöz–yeniden kodla döngüsü çalıştırıyor. {"cache": {"enabled": true}} ekle.

blur ile içerik gizlemeye çalışmak

“This parameter should not be used to reliably obscure image content when optimizing via URL, as the URL can be modified to remove the blur parameter.”