Optimisation d'Images

Transformez et optimisez les images servies depuis IPFS à la volée en utilisant des paramètres de requête. C'est un endpoint public qui ne nécessite aucune authentification.

Optimiser une Image

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

Retourne l'image au CID donné, transformée selon les paramètres de requête fournis. Si aucun paramètre de transformation n'est fourni, la requête renvoie une redirection 302 vers l'image originale sur la passerelle IPFS.

Paramètres de chemin

Paramètre	Type	Requis	Description
cid	string	Oui	L'identifiant de contenu IPFS de l'image.

Paramètres de requête

Paramètre	Type	Par défaut	Description
w	integer	—	Largeur de sortie en pixels. Plage : 1–4096. Les valeurs ≤ 0 ou non numériques sont ignorées.
h	integer	—	Hauteur de sortie en pixels. Plage : 1–4096. Les valeurs ≤ 0 ou non numériques sont ignorées.
format	string	—	Format de sortie : webp, jpeg, png ou avif. Sensible à la casse (en minuscules). Les valeurs inconnues sont ignorées.
quality	integer	80	Qualité de compression, 1–100. S'applique uniquement à webp, jpeg et avif. png est sans perte et l'ignore.
fit	string	cover	Comment l'image doit s'adapter aux dimensions : cover, contain, fill, inside ou outside.

Note : le paramètre est quality, pas q. Les alias raccourcis courants (q, width, height, fmt) ne sont pas reconnus.

Une requête qui ne fournit aucun de w, h ou format est traitée comme une opération neutre et renvoie une redirection 302 vers l'image originale. quality et fit seuls ne déclenchent pas de transformation.

Modes d'ajustement

Mode	Comportement
cover	Recadrer pour couvrir les deux dimensions (par défaut).
contain	S'adapter dans les deux dimensions, en préservant le ratio d'aspect. Peut laisser de l'espace vide (transparent ou noir selon le format).
fill	Étirer pour remplir les deux dimensions exactement. Peut déformer l'image.
inside	Comme contain, mais ne réduit que, n'agrandit jamais.
outside	Comme cover, mais ne réduit que, n'agrandit jamais.

Agrandissement

Le transformateur n'agrandit jamais une image au-delà des dimensions de sa source. Si vous demandez w=2000 pour une source de 1200px de large, la sortie fera 1200px de large. Cela s'applique à tous les modes fit.

Réponse

Statut	Quand	Corps
200	Une transformation a été produite sur cette requête.	Octets binaires de l'image. Content-Type correspond au format demandé.
302	Aucun paramètre de transformation fourni, ou un résultat précédemment transformé est déjà en cache.	L'en-tête Location pointe vers l'image originale ou le résultat mis en cache sur https://ipfs.ninja/image-cache/....
400	Paramètre de chemin cid manquant.	{ "error": "cid required" }
404	CID introuvable sur la passerelle.	{ "error": "CID not found" }
500	Erreur inattendue (image corrompue, échec de transformation, etc.).	{ "error": "<message>" }

Toutes les réponses 200 et les réponses 302 issues du cache sont servies avec Cache-Control: public, max-age=31536000, immutable. Voir Cache ci-dessous.

Exemples de requêtes

Redimensionner à 400px de large, convertir en WebP :

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

Redimensionner et recadrer en miniature 200×200 en JPEG à 60% de qualité :

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

Miniature carrée avec bandes plutôt que recadrage :

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

Conversion de format uniquement, sans redimensionnement (utile pour servir des versions AVIF/WebP de JPEGs hérités) :

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

Plafonner la largeur maximale sans forcer la hauteur (préserve le ratio d'aspect) :

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

Utilisation en HTML

Référencez les images optimisées directement dans les balises img :

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

Servez différentes tailles avec 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"
/>

Négociation de formats modernes avec <picture> (AVIF → WebP → repli JPEG) :

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

Image de fond en CSS :

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

Utilisation avec Next.js

En tant que loader personnalisé pour 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

Les réponses sont servies avec Cache-Control: public, max-age=31536000, immutable. Puisque le contenu IPFS est adressé par contenu, le même CID avec les mêmes paramètres produit toujours la même sortie, donc les navigateurs et CDN peuvent mettre les réponses en cache indéfiniment.

Les transformations mises en cache sont stockées dans S3, indexées par l'ensemble complet des paramètres (cid, w, h, format, quality, fit). Les requêtes ultérieures avec les mêmes paramètres renvoient une redirection 302 vers le cache servi par CloudFront (https://ipfs.ninja/image-cache/...) plutôt que de réexécuter la transformation. Des combinaisons de paramètres différentes produisent des entrées de cache différentes.

Disponibilité

L'optimisation d'images est disponible sur tous les plans, y compris le plan gratuit Dharma.