Βελτιστοποίηση Εικόνας

Μετασχηματίστε και βελτιστοποιήστε εικόνες που εξυπηρετούνται από το IPFS on-the-fly χρησιμοποιώντας παραμέτρους ερωτήματος. Αυτό είναι δημόσιο endpoint που δεν απαιτεί πιστοποίηση.

Βελτιστοποίηση Εικόνας

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

Επιστρέφει την εικόνα στο δοθέν CID, μετασχηματισμένη σύμφωνα με τις παρεχόμενες παραμέτρους ερωτήματος. Εάν δεν παρέχονται παράμετροι μετασχηματισμού, το αίτημα κάνει 302-ανακατεύθυνση στην αρχική εικόνα στην πύλη IPFS.

Παράμετροι διαδρομής

Παράμετρος	Τύπος	Απαιτείται	Περιγραφή
`cid`	string	Ναι	Το αναγνωριστικό περιεχομένου IPFS της εικόνας.

Παράμετροι ερωτήματος

Παράμετρος	Τύπος	Προεπιλογή	Περιγραφή
`w`	integer	—	Πλάτος εξόδου σε pixels. Εύρος: 1–4096. Τιμές ≤ 0 ή μη αριθμητικές αγνοούνται.
`h`	integer	—	Ύψος εξόδου σε pixels. Εύρος: 1–4096. Τιμές ≤ 0 ή μη αριθμητικές αγνοούνται.
`format`	string	—	Μορφή εξόδου: `webp`, `jpeg`, `png` ή `avif`. Διάκριση πεζών-κεφαλαίων (lowercase). Άγνωστες τιμές αγνοούνται.
`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 θεωρείται no-op και κάνει 302-ανακατεύθυνση στην αρχική εικόνα. Τα quality και fit από μόνα τους δεν προκαλούν μετασχηματισμό.

Λειτουργίες προσαρμογής

Mode	Behavior
`cover`	Περικοπή ώστε να καλυφθούν και οι δύο διαστάσεις (προεπιλογή).
`contain`	Προσαρμογή εντός και των δύο διαστάσεων, διατηρώντας την αναλογία. Μπορεί να αφήσει κενό χώρο (διαφανή ή μαύρο ανάλογα με τη μορφή).
`fill`	Επέκταση ώστε να γεμίσουν και οι δύο διαστάσεις ακριβώς. Μπορεί να παραμορφώσει την εικόνα.
`inside`	Όπως το `contain`, αλλά μόνο σμικρύνει, ποτέ δεν μεγεθύνει.
`outside`	Όπως το `cover`, αλλά μόνο σμικρύνει, ποτέ δεν μεγεθύνει.

Μεγέθυνση

Ο μετασχηματιστής ποτέ δεν μεγεθύνει μια εικόνα πέρα από τις διαστάσεις της πηγής. Εάν ζητήσετε w=2000 για πηγή πλάτους 1200px, η έξοδος θα είναι πλάτους 1200px. Αυτό ισχύει για όλες τις λειτουργίες fit.

Απάντηση

Status	When	Body
`200`	Παράχθηκε μετασχηματισμός σε αυτό το αίτημα.	Δυαδικά bytes εικόνας. Το `Content-Type` ταιριάζει με τη ζητούμενη μορφή.
`302`	Δεν παρασχέθηκαν παράμετροι μετασχηματισμού, ή ένα προηγουμένως μετασχηματισμένο αποτέλεσμα είναι ήδη αποθηκευμένο στην cache.	Η κεφαλίδα `Location` δείχνει στην αρχική εικόνα ή στο αποθηκευμένο αποτέλεσμα στο `https://ipfs.ninja/image-cache/...`.
`400`	Λείπει η παράμετρος διαδρομής `cid`.	`{ "error": "cid required" }`
`404`	Το CID δεν βρέθηκε στην πύλη.	`{ "error": "CID not found" }`
`500`	Απρόσμενο σφάλμα (αλλοιωμένη εικόνα, αποτυχία μετασχηματισμού κ.λπ.).	`{ "error": "<message>" }`

Όλες οι απαντήσεις 200 και 302-cache εξυπηρετούνται με Cache-Control: public, max-age=31536000, immutable. Δείτε Caching παρακάτω.

Παραδείγματα αιτημάτων

Αλλαγή μεγέθους σε 400px πλάτος, μετατροπή σε WebP:

bash

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

Αλλαγή μεγέθους και περικοπή σε μικρογραφία 200×200 ως JPEG στο 60% ποιότητα:

bash

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

Τετράγωνη μικρογραφία με letterboxing αντί περικοπής:

bash

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

Μόνο μετατροπή μορφής, χωρίς αλλαγή μεγέθους (χρήσιμο για παροχή εκδόσεων AVIF/WebP από παλαιά JPEG):

bash

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

Όριο μέγιστου πλάτους χωρίς επιβολή ύψους (διατηρεί την αναλογία):

bash

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

Χρήση σε HTML

Αναφορά βελτιστοποιημένων εικόνων απευθείας σε ετικέτες img:

html

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

Παροχή διαφορετικών μεγεθών με srcset:

html

<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):

html

<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:

css

.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}`;
}

jsx

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

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

Caching

Οι απαντήσεις εξυπηρετούνται με Cache-Control: public, max-age=31536000, immutable. Δεδομένου ότι το περιεχόμενο IPFS είναι content-addressed, το ίδιο CID με τις ίδιες παραμέτρους παράγει πάντα την ίδια έξοδο, ώστε οι περιηγητές και τα CDN μπορούν να αποθηκεύουν τις απαντήσεις επ' αόριστον.

Οι αποθηκευμένοι μετασχηματισμοί αποθηκεύονται στο S3 με κλειδί το πλήρες σύνολο παραμέτρων (cid, w, h, format, quality, fit). Επόμενα αιτήματα με τις ίδιες παραμέτρους επιστρέφουν 302 ανακατεύθυνση στην cache πίσω από CloudFront (https://ipfs.ninja/image-cache/...) αντί να εκτελούν ξανά τον μετασχηματισμό. Διαφορετικοί συνδυασμοί παραμέτρων παράγουν διαφορετικές καταχωρήσεις cache.

Διαθεσιμότητα

Η βελτιστοποίηση εικόνας είναι διαθέσιμη σε όλα τα πλάνα, συμπεριλαμβανομένου του δωρεάν πλάνου Dharma.

Βελτιστοποίηση Εικόνας ​