Fichiers

Téléversez, listez et récupérez des fichiers sur IPFS. Voir authentification pour la configuration de votre clé API, et erreurs pour les codes de statut HTTP.

Téléverser un Fichier sur IPFS : 3 Étapes

1. Encodez votre fichier en base64 (pour les images/PDF) ou transmettez directement un objet ou tableau JSON.
2. Envoyez une requête POST à /upload/new avec votre clé API dans l'en-tête X-Api-Key.
3. Conservez le cid renvoyé dans la réponse — il identifie de façon permanente votre fichier sur IPFS.

POST /upload/new

Téléversez n'importe quel fichier sur IPFS. Le fichier est épinglé et un CID permanent est renvoyé.

Corps de la requête

Paramètre	Type	Requis	Description
content	string | object	Oui	Objet/tableau JSON, ou données de fichier encodées en base64 (images, PDF, HTML, ou tout autre type de fichier). Pour les imports CAR, fichier CAR encodé en base64.
car	boolean	Non	Définir sur true pour importer un fichier CAR (import de DAG). Préserve les CID exacts.
description	string	Non	Courte description du contenu téléversé.
metadata	object	Non	Paires clé-valeur personnalisées à attacher au fichier. Maximum 10 clés. Les clés doivent être alphanumériques ou contenir des underscores, de 1 à 64 caractères. Les valeurs doivent être des chaînes, 256 caractères maximum chacune. La taille totale des métadonnées ne doit pas dépasser 4 Ko.

Exemple de requête

curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": { "name": "example", "value": 42 },
    "description": "Test upload",
    "metadata": {
      "project": "my-app",
      "environment": "production"
    }
  }'

Téléverser une image (base64)

const fs = require("fs");
const image = fs.readFileSync("photo.png").toString("base64");

const response = await fetch("https://api.ipfs.ninja/upload/new", {
  method: "POST",
  headers: {
    "X-Api-Key": "bws_your_api_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    content: image,
    description: "Profile photo"
  })
});

Réponse 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "sizeMB": 0.042,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

CIDv1 par défaut

Les nouveaux téléversements renvoient un CIDv1 moderne (bafk… pour le contenu à bloc unique de petite taille, bafy… pour les fichiers volumineux et les répertoires) selon le profil IPIP-0499 unixfs-v1-2025 — des chunks de 1 MiB avec des feuilles brutes (raw leaves). Les CID Qm… hérités des téléversements précédents restent entièrement résolubles et continuent de fonctionner avec tous les endpoints.

Alternative via le tableau de bord

La page /upload du tableau de bord accepte le glisser-déposer pour les fichiers, les dossiers (regroupés dans un répertoire UnixFS dans le navigateur) et les archives .car — tous passent par ce même endpoint. Voir Import CAR pour plus de détails sur le chemin CAR.

Types de fichiers pris en charge

L'API accepte directement des objets et tableaux JSON, ainsi que des fichiers binaires encodés en base64 : images (JPEG, PNG, GIF, WebP), PDF, HTML et tout autre type de fichier. Le serveur détecte automatiquement le type de contenu à partir du contenu envoyé.

Champs de la réponse

Le champ cid de la réponse est l'identifiant de contenu IPFS permanent. sizeMB correspond à la taille stockée en mégaoctets. L'objet uris contient à la fois l'URI native ipfs:// et une URL de gateway HTTPS pour l'accès depuis un navigateur.

Renommer un fichier

PUT /files/:cid/name

Met à jour le nom d'affichage d'un fichier. Le CID ne change pas — c'est un hash du contenu — seul le libellé visible dans votre liste de fichiers change.

Corps de la requête

Paramètre	Type	Requis	Description
name	string	Oui	Nouveau nom d'affichage. 1 à 200 caractères. Ne doit pas contenir de séparateurs de chemin (/, \). Les noms composés uniquement d'espaces sont rejetés.

Exemple de requête

curl -X PUT https://api.ipfs.ninja/files/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/name \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Season 1 promo art" }'

Réponse 200 OK

{
  "success": true,
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "name": "Season 1 promo art"
}

Tableau de bord

La page Fichiers propose une entrée Renommer dans le menu d'actions de chaque ligne de fichier (bouton à trois points). Même effet, sans écrire de code.

Lister les fichiers

GET /upload/list

Récupère la liste de vos fichiers IPFS téléversés dans une plage de temps donnée.

Paramètres de requête

Paramètre	Type	Requis	Description
from	number	Oui	Début de la plage de temps, horodatage Unix en millisecondes.
to	number	Oui	Fin de la plage de temps, horodatage Unix en millisecondes.

Exemple de requête

curl "https://api.ipfs.ninja/upload/list?from=1704067200000&to=1735689600000" \
  -H "X-Api-Key: bws_your_api_key_here"

Réponse 200 OK

[
  {
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "fileName": "Test upload",
    "fileType": "json",
    "sizeMB": 0.001,
    "createdAt": 1711036800000,
    "metadata": {
      "project": "my-app",
      "environment": "production"
    },
    "uris": {
      "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
      "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
    }
  }
]

Obtenir un fichier

GET /file/:cid

Récupère les métadonnées d'un fichier téléversé spécifique à partir de son CID.

Paramètres de chemin

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

Exemple de requête

curl https://api.ipfs.ninja/file/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi \
  -H "X-Api-Key: bws_your_api_key_here"

Réponse 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "fileName": "Test upload",
  "fileType": "json",
  "sizeMB": 0.001,
  "createdAt": 1711036800000,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}