การปรับแต่งรูปภาพ

แปลงและปรับแต่งรูปภาพที่ให้บริการจาก IPFS แบบ on-the-fly โดยใช้พารามิเตอร์คิวรี นี่คือ endpoint สาธารณะที่ไม่ต้องยืนยันตัวตน

ปรับแต่งรูปภาพ

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

ส่งคืนรูปภาพที่ CID ที่กำหนด แปลงตามพารามิเตอร์คิวรีที่ให้มา หากไม่มีพารามิเตอร์การแปลงใด ๆ ถูกส่งมา คำขอจะถูกเปลี่ยนเส้นทางแบบ 302 ไปยังรูปภาพต้นฉบับบน IPFS gateway

พารามิเตอร์ path

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
cid	string	ใช่	ตัวระบุเนื้อหา IPFS ของรูปภาพ

พารามิเตอร์คิวรี

พารามิเตอร์	ประเภท	ค่าเริ่มต้น	คำอธิบาย
w	integer	—	ความกว้างเอาต์พุตเป็นพิกเซล ช่วง: 1–4096 ค่าที่ ≤ 0 หรือไม่ใช่ตัวเลขจะถูกเพิกเฉย
h	integer	—	ความสูงเอาต์พุตเป็นพิกเซล ช่วง: 1–4096 ค่าที่ ≤ 0 หรือไม่ใช่ตัวเลขจะถูกเพิกเฉย
format	string	—	รูปแบบเอาต์พุต: webp, jpeg, png หรือ avif คำนึงถึงตัวพิมพ์ใหญ่-เล็ก (ตัวพิมพ์เล็ก) ค่าที่ไม่รู้จักจะถูกเพิกเฉย
quality	integer	80	คุณภาพการบีบอัด 1–100 ใช้ได้กับ webp, jpeg และ avif เท่านั้น png เป็นแบบไม่สูญเสียข้อมูลและจะเพิกเฉยพารามิเตอร์นี้
fit	string	cover	วิธีปรับรูปภาพให้พอดีกับขนาด: cover, contain, fill, inside หรือ outside

หมายเหตุ: พารามิเตอร์คือ quality ไม่ใช่ q ชื่อย่อทั่วไป (q, width, height, fmt) จะไม่ถูกรู้จัก

คำขอที่ไม่ได้ระบุ w, h หรือ format จะถือเป็นการไม่ทำอะไรและเปลี่ยนเส้นทางแบบ 302 ไปยังรูปภาพต้นฉบับ การมีเพียง quality และ fit จะไม่กระตุ้นการแปลง

โหมด fit

โหมด	พฤติกรรม
cover	ครอปเพื่อให้ครอบคลุมทั้งสองมิติ (ค่าเริ่มต้น)
contain	พอดีภายในทั้งสองมิติ รักษาอัตราส่วน อาจมีพื้นที่ว่าง (โปร่งใสหรือดำขึ้นอยู่กับรูปแบบ)
fill	ยืดให้เต็มทั้งสองมิติ อาจบิดเบือนรูปภาพ
inside	เหมือน contain แต่ลดขนาดเท่านั้น ไม่ขยาย
outside	เหมือน cover แต่ลดขนาดเท่านั้น ไม่ขยาย

การขยายขนาด

ตัวแปลงจะไม่ขยายรูปภาพเกินขนาดต้นฉบับ ถ้าคุณขอ w=2000 สำหรับต้นฉบับที่มีความกว้าง 1200px เอาต์พุตจะมีความกว้าง 1200px เรื่องนี้ใช้กับโหมด fit ทุกโหมด

การตอบกลับ

Status	When	Body
200	มีการสร้างการแปลงในคำขอนี้	ไบต์รูปภาพไบนารี Content-Type ตรงกับรูปแบบที่ขอ
302	ไม่มีพารามิเตอร์การแปลงใด ๆ หรือผลการแปลงก่อนหน้านี้ถูกแคชไว้แล้ว	เฮดเดอร์ Location ชี้ไปยังรูปภาพต้นฉบับหรือผลที่แคชไว้บน https://ipfs.ninja/image-cache/...
400	ขาดพารามิเตอร์ path cid	{ "error": "cid required" }
404	ไม่พบ CID บน gateway	{ "error": "CID not found" }
500	ข้อผิดพลาดที่ไม่คาดคิด (รูปภาพเสียหาย การแปลงล้มเหลว ฯลฯ)	{ "error": "<message>" }

การตอบกลับ 200 และ 302 แบบแคชทั้งหมดให้บริการด้วย Cache-Control: public, max-age=31536000, immutable ดู การแคช ด้านล่าง

ตัวอย่างคำขอ

ปรับขนาดเป็นความกว้าง 400px แปลงเป็น WebP:

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

ปรับขนาดและครอปเป็น 200×200 thumbnail เป็น JPEG คุณภาพ 60%:

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

thumbnail สี่เหลี่ยมจัตุรัสด้วย letterboxing แทนการครอป:

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

แปลงรูปแบบเท่านั้น ไม่ปรับขนาด (มีประโยชน์สำหรับการให้บริการ AVIF/WebP เวอร์ชันของ JPEG เก่า):

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

จำกัดความกว้างสูงสุดโดยไม่บังคับความสูง (รักษาอัตราส่วน):

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

ใช้ใน HTML

อ้างอิงรูปภาพที่ปรับแต่งแล้วโดยตรงในแท็ก img:

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

ให้บริการขนาดต่าง ๆ ด้วย srcset:

<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> (AVIF → WebP → JPEG fallback):

<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

ในรูปแบบ loader ที่กำหนดเองสำหรับ next/image:

// 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}
/>;

การแคช

การตอบกลับให้บริการด้วย Cache-Control: public, max-age=31536000, immutable เนื่องจากเนื้อหา IPFS มีการระบุที่อยู่ตามเนื้อหา CID เดียวกันกับพารามิเตอร์เดียวกันจะสร้างเอาต์พุตเดียวกันเสมอ ดังนั้นเบราว์เซอร์และ CDN จึงสามารถแคชการตอบกลับได้อย่างไม่มีกำหนด

การแปลงที่แคชไว้ถูกเก็บใน S3 โดยใช้คีย์เป็นชุดพารามิเตอร์ทั้งหมด (cid, w, h, format, quality, fit) คำขอที่ตามมาด้วยพารามิเตอร์เดียวกันจะส่งคืนการเปลี่ยนเส้นทาง 302 ไปยังแคชที่อยู่หลัง CloudFront (https://ipfs.ninja/image-cache/...) แทนที่จะเรียกใช้การแปลงซ้ำ ชุดพารามิเตอร์ที่ต่างกันจะสร้างรายการแคชที่ต่างกัน

ความพร้อมใช้งาน

การปรับแต่งรูปภาพมีให้ในทุกแผน รวมถึงแผน Dharma ฟรี