Görüntü Optimizasyonu

IPFS'ten sunulan görüntüleri sorgu parametreleri kullanarak anında dönüştürün ve optimize edin. Bu, kimlik doğrulama gerektirmeyen genel bir uç noktadır.

Görüntüyü Optimize Et

GET https://api.ipfs.ninja/image/:cid

Verilen CID'deki görüntüyü, sağlanan sorgu parametrelerine göre dönüştürülmüş olarak döndürür. Hiçbir dönüşüm parametresi sağlanmazsa, istek IPFS ağ geçidindeki orijinal görüntüye 302-yönlendirmesi yapar.

Yol parametreleri

Parametre	Tür	Zorunlu	Açıklama
cid	string	Evet	Görüntünün IPFS içerik tanımlayıcısı.

Sorgu parametreleri

Parametre	Tür	Varsayılan	Açıklama
w	integer	—	Çıkış genişliği piksel cinsinden. Aralık: 1–4096. ≤ 0 veya sayısal olmayan değerler yok sayılır.
h	integer	—	Çıkış yüksekliği piksel cinsinden. Aralık: 1–4096. ≤ 0 veya sayısal olmayan değerler yok sayılır.
format	string	—	Çıkış formatı: webp, jpeg, png veya avif. Büyük/küçük harf duyarlı (lowercase). Bilinmeyen değerler yok sayılır.
quality	integer	80	Sıkıştırma kalitesi, 1–100. Yalnızca webp, jpeg ve avif için geçerlidir. png kayıpsızdır ve bunu yok sayar.
fit	string	cover	Görüntünün boyutlara nasıl sığdırılacağı: cover, contain, fill, inside veya outside.

Not: parametre quality, q değil. Yaygın kısaltma takma adları (q, width, height, fmt) tanınmaz.

w, h veya format'tan hiçbirini sağlamayan bir istek no-op olarak ele alınır ve orijinal görüntüye 302-yönlendirmesi yapar. Yalnızca quality ve fit bir dönüşümü tetiklemez.

Sığdırma modları

Mod	Davranış
cover	Her iki boyutu da kaplayacak şekilde kırp (varsayılan).
contain	En boy oranını koruyarak her iki boyuta sığdır. Boş alan bırakabilir (formata bağlı olarak şeffaf veya siyah).
fill	Her iki boyutu tam olarak dolduracak şekilde gerdirin. Görüntüyü bozabilir.
inside	contain gibi, ancak yalnızca küçültür, asla büyütmez.
outside	cover gibi, ancak yalnızca küçültür, asla büyütmez.

Büyütme

Dönüştürücü hiçbir zaman görüntüyü kaynak boyutlarının ötesinde büyütmez. 1200px genişliğindeki bir kaynak için w=2000 talep ederseniz, çıktı 1200px genişliğinde olacaktır. Bu tüm fit modları için geçerlidir.

Yanıt

Status	When	Body
200	Bu istekte dönüşüm üretildi.	İkili görüntü baytları. Content-Type istenen formata uygun.
302	Dönüşüm parametresi sağlanmadı veya daha önce dönüştürülmüş bir sonuç zaten önbelleğe alındı.	Location başlığı orijinal görüntüye veya https://ipfs.ninja/image-cache/... üzerindeki önbelleğe alınmış sonuca işaret eder.
400	cid yol parametresi eksik.	{ "error": "cid required" }
404	CID ağ geçidinde bulunamadı.	{ "error": "CID not found" }
500	Beklenmedik hata (bozuk görüntü, dönüşüm hatası vb.).	{ "error": "<message>" }

Tüm 200 ve 302-önbellek yanıtları Cache-Control: public, max-age=31536000, immutable ile sunulur. Aşağıdaki Önbellekleme bölümüne bakın.

Örnek istekler

400 piksel genişliğe yeniden boyutlandır, WebP'ye dönüştür:

curl "https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=400&format=webp"

%60 kalitede JPEG olarak 200×200 küçük resme yeniden boyutlandır ve kırp:

curl "https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=200&h=200&format=jpeg&quality=60&fit=cover"

Kırpma yerine letterbox ile kare küçük resim:

curl "https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=200&h=200&format=png&fit=contain"

Yalnızca format dönüştürme, yeniden boyutlandırma yok (eski JPEG'lerin AVIF/WebP sürümlerini sunmak için kullanışlı):

curl "https://api.ipfs.ninja/image/QmXmCX9S6ANV...?format=avif&quality=70"

Yüksekliği zorlamadan maksimum genişliği sınırla (en boy oranını korur):

curl "https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=1200&format=webp"

HTML'de kullanım

Optimize edilmiş görüntüleri doğrudan img etiketlerinde referans alın:

<img
  src="https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=800&format=webp&quality=75"
  alt="Optimized IPFS image"
/>

srcset ile farklı boyutlar sunun:

<img
  srcset="
    https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=400&format=webp 400w,
    https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=800&format=webp 800w,
    https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=1200&format=webp 1200w
  "
  sizes="(max-width: 600px) 400px, (max-width: 1000px) 800px, 1200px"
  src="https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=800&format=webp"
  alt="Responsive IPFS image"
/>

<picture> ile modern format müzakeresi (AVIF → WebP → JPEG yedeği):

<picture>
  <source
    type="image/avif"
    srcset="https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=800&format=avif&quality=60"
  />
  <source
    type="image/webp"
    srcset="https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=800&format=webp&quality=75"
  />
  <img
    src="https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=800&format=jpeg&quality=80"
    alt="IPFS image with format fallback"
  />
</picture>

CSS background-image:

.hero {
  background-image: url("https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=1600&format=webp&quality=70");
}

Next.js ile kullanım

next/image için özel yükleyici olarak:

// loaders/ipfs.js
export default function ipfsLoader({ src, width, quality }) {
  return `https://api.ipfs.ninja/image/${src}?w=${width}&format=webp&quality=${quality || 75}`;
}

import Image from "next/image";
import ipfsLoader from "@/loaders/ipfs";

<Image
  loader={ipfsLoader}
  src="QmXmCX9S6ANV..."
  alt="IPFS image"
  width={800}
  height={600}
/>;

Önbellekleme

Yanıtlar Cache-Control: public, max-age=31536000, immutable ile sunulur. IPFS içeriği içerik adreslemeli olduğundan, aynı CID aynı parametrelerle her zaman aynı çıktıyı üretir, bu nedenle tarayıcılar ve CDN'ler yanıtları süresiz olarak önbelleğe alabilir.

Önbelleğe alınmış dönüşümler, tam parametre kümesi (cid, w, h, format, quality, fit) ile anahtarlanarak S3'te saklanır. Aynı parametrelerle yapılan sonraki istekler, dönüşümü yeniden çalıştırmak yerine CloudFront önyüzlü önbelleğe (https://ipfs.ninja/image-cache/...) bir 302 yönlendirmesi döndürür. Farklı parametre kombinasyonları farklı önbellek girişleri üretir.

Erişilebilirlik

Görüntü optimizasyonu, ücretsiz Dharma planı dahil tüm planlarda mevcuttur.