Fitxers

Pugeu, llisteu i recupereu fitxers a IPFS.

Pujar Fitxer

POST /upload/new

Pugeu qualsevol fitxer a IPFS. El fitxer es fixa i es retorna un CID permanent.

Cos de la sol·licitud

Paràmetre	Tipus	Requerit	Descripció
content	string | object	Sí	Objecte/matriu JSON, o dades de fitxer codificades en base64 (imatges, PDF, HTML o qualsevol tipus de fitxer). Per a importacions CAR, fitxer CAR codificat en base64.
car	boolean	No	Establiu a true per importar un fitxer CAR (importació DAG). Preserva els CID exactes.
description	string	No	Descripció breu del contingut pujat.
metadata	object	No	Parells clau-valor personalitzats per adjuntar al fitxer. Màx 10 claus. Les claus han de ser alfanumèriques o guió baix, 1-64 caràcters. Els valors han de ser cadenes, màx 256 caràcters cadascun. La mida total de metadata no pot superar 4 KB.

Exemple de sol·licitud

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"
    }
  }'

Pujar una imatge (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"
  })
});

Resposta 200 OK

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

CIDv1 per defecte

Les pujades noves retornen CIDv1 modern (bafk… per a contingut petit d'un sol bloc, bafy… per a fitxers i directoris més grans) seguint el perfil IPIP-0499 unixfs-v1-2025 — blocs d'1 MiB amb fulles en cru (raw leaves). Els CID Qm… heretats de pujades anteriors continuen sent completament resolubles i segueixen funcionant amb tots els endpoints.

Alternativa al tauler de control

La pàgina /upload del tauler de control accepta arrossegar i deixar anar per a fitxers, carpetes (empaquetades en un directori UnixFS al navegador) i arxius .car — tot passa pel mateix endpoint. Consulteu Importació CAR per a més detalls sobre el camí CAR.

Canviar el nom d'un fitxer

PUT /files/:cid/name

Actualitza el nom que es mostra per a un fitxer. El CID no canvia — és un hash del contingut — només l'etiqueta que veieu a la vostra llista de fitxers.

Cos de la sol·licitud

Paràmetre	Tipus	Requerit	Descripció
name	string	Sí	Nou nom a mostrar. 1-200 caràcters. No ha de contenir separadors de ruta (/, \). Els noms que només contenen espais en blanc es rebutgen.

Exemple de sol·licitud

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" }'

Resposta 200 OK

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

Tauler de control

La pàgina de Fitxers té una opció Rename al menú d'accions de cada fila de fitxer (botó de tres punts). Mateix efecte, sense necessitat de codi.

Llistar Fitxers

GET /upload/list

Recupereu una llista dels vostres fitxers IPFS pujats dins d'un rang de temps.

Paràmetres de consulta

Paràmetre	Tipus	Requerit	Descripció
from	number	Sí	Inici del rang de temps, marca de temps Unix en mil·lisegons.
to	number	Sí	Final del rang de temps, marca de temps Unix en mil·lisegons.

Exemple de sol·licitud

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

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

GET /file/:cid

Recupereu metadata per a un fitxer pujat específic pel seu CID.

Paràmetres de ruta

Paràmetre	Tipus	Requerit	Descripció
cid	string	Sí	L'identificador de contingut IPFS del fitxer.

Exemple de sol·licitud

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

Resposta 200 OK

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