IPFS Upload API — Täielik arendaja õpetus

Failide üleslaadimine IPFS-i peaks olema sama lihtne kui POST päringu tegemine. Selles õpetuses teete just seda — laadite üles JSON dokumendid, pildid ja PDF-id IPFS-i kasutades vaid fetch() ja API võtit. Lõpus on teil täielik Node.js skript, mis laadib üles sisu, loetleb faile, hangib metaandmeid ja genereerib allkirjastatud tokeneid turvaliseks kliendipoolseks üleslaadimiseks. Uus IPFS-i juures? Alustage Mis on IPFS Pinning?, et mõista aluseid enne koodi sukeldumist.

Mida te ehitate

• Laadite JSON objekti IPFS-i ja saate tagasi sisu identifikaatori (CID).
• Laadite üles binaarpildi kettalt.
• Lisate kirjeldused ja kohandatud metaandmed üleslaadimistele.
• Päringule oma üleslaadimiste ajalugu kuupäevavahemiku järgi.
• Toote detailid konkreetse faili kohta.
• Loote ajaliselt piiratud allkirjastatud tokeneid, et brauser saaks otse üles laadida ilma teie API võtit paljastamata.
• Käsitsete vigu ja rakendate korduskatse loogikat.

Kõik töötab ühe baas-URL-i vastu: https://api.ipfs.ninja

1. Seadistamine — Registreerige ja hankige API võti

1. Registreeruge tasuta kontole (krediitkaarti pole vaja).
2. Minge API Keys juurde töölaua külgribal.
3. Klõpsake Create key, andke sellele nimi ja kopeerige võti kohe — seda enam ei näidata.

Teie võti näeb välja selline: bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6. Iga allolev näide saadab selle X-Api-Key päises.

2. JSON-i üleslaadimine IPFS-i

Lihtsaim üleslaadimine: edastage tavaline JavaScripti objekt kui content ja API serialiseerib selle, kinnitab IPFS-i ja tagastab CID.

// upload-json.mjs
const API = "https://api.ipfs.ninja";
const API_KEY = "bws_your_key_here";

const payload = {
  content: {
    name: "Galactic Badge #42",
    description: "Proof of attendance — Galactic Meetup 2026",
    attributes: [
      { trait_type: "Event", value: "Galactic Meetup" },
      { trait_type: "Year", value: 2026 }
    ]
  }
};

const res = await fetch(`${API}/upload/new`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": API_KEY
  },
  body: JSON.stringify(payload)
});

const data = await res.json();
console.log("CID :", data.cid);
console.log("Size:", data.sizeMB, "MB");
console.log("IPFS:", data.uris.ipfs);
console.log("URL :", data.uris.url);

Käivitage node upload-json.mjs. Edukas vastus näeb välja selline:

{
  "cid": "bafkreigx7gq...",
  "sizeMB": 0.0004,
  "uris": {
    "ipfs": "ipfs://bafkreigx7gq...",
    "url": "https://ipfs.ninja/ipfs/bafkreigx7gq..."
  }
}

Väli url osutab avalikule HTTP lüüsile, nii et sisu on kohe ligipääsetav igas brauseris.

3. Pildi üleslaadimine

Binaarfailid (pildid, PDF-id, heli) saadetakse base64-kodeeritud stringidena väljal content.

// upload-image.mjs
import { readFileSync } from "node:fs";

const API = "https://api.ipfs.ninja";
const API_KEY = "bws_your_key_here";

const imageBuffer = readFileSync("./photo.png");
const base64 = imageBuffer.toString("base64");

const res = await fetch(`${API}/upload/new`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": API_KEY
  },
  body: JSON.stringify({ content: base64 })
});

const data = await res.json();
console.log("Image CID:", data.cid);
console.log("Gateway  :", data.uris.url);

API tuvastab MIME tüübi automaatselt — PNG, JPEG, WebP, GIF ja PDF on kõik toetatud. Lisapäiseid ega content-type ümberkirjutamist pole vaja.

Curl-iga näeb sama operatsioon välja selline:

BASE64=$(base64 -w 0 photo.png)

curl -X POST https://api.ipfs.ninja/upload/new \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: bws_your_key_here" \
  -d "{\"content\": \"$BASE64\"}"

4. Üleslaadimine metaandmetega

Iga üleslaadimine aktsepteerib kahte valikulist välja: description (vaba teksti silt) ja metadata (suvalised võtme-väärtuse paarid). Mõlemad salvestatakse koos CID-iga ja tagastatakse, kui hiljem faili loetletate või hangite.

// upload-with-metadata.mjs
const API = "https://api.ipfs.ninja";
const API_KEY = "bws_your_key_here";

const res = await fetch(`${API}/upload/new`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": API_KEY
  },
  body: JSON.stringify({
    content: { title: "Meeting Notes", body: "Q1 roadmap recap..." },
    description: "Q1 2026 planning meeting notes",
    metadata: {
      project: "acme-app",
      author: "dana",
      version: "1"
    }
  })
});

const data = await res.json();
console.log("CID:", data.cid);

Metaandmed lihtsustavad failide filtreerimist ja korraldamist teie poolel ilma IPFS-i sisu ennast parsimata.

5. Olemasoleva CID kinnitamine

Kui teil on juba sisu IPFS-is ja soovite tagada, et see jääb saadavaks, kinnitage see CID järgi:

// pin-cid.mjs
const API = "https://api.ipfs.ninja";
const API_KEY = "bws_your_key_here";

const res = await fetch(`${API}/pin`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": API_KEY
  },
  body: JSON.stringify({
    cid: "bafkreigx7gq...",
    description: "Pinned from external source"
  })
});

const data = await res.json();
console.log("Pinned:", data.cid);

6. Teie failide loetlemine

Hankige iga fail, mille olete üles laadinud kindla ajaakna jooksul. Päringuparameetrid from ja to on Unixi ajatemplid millisekundites.

// list-files.mjs
const API = "https://api.ipfs.ninja";
const API_KEY = "bws_your_key_here";

const now = Date.now();
const oneWeekAgo = now - 7 * 24 * 60 * 60 * 1000;

const url = `${API}/upload/list?from=${oneWeekAgo}&to=${now}`;

const res = await fetch(url, {
  headers: { "X-Api-Key": API_KEY }
});

const files = await res.json();

for (const file of files) {
  console.log(`${file.cid}  ${file.description ?? "(no description)"}`);
}

Curl-iga:

FROM=$(($(date +%s) * 1000 - 604800000))
TO=$(($(date +%s) * 1000))

curl -s "https://api.ipfs.ninja/upload/list?from=$FROM&to=$TO" \
  -H "X-Api-Key: bws_your_key_here" | jq .

7. Faili detailid

Hankige ühe CID täielik kirje, sealhulgas metaandmed, suurus ja ajatemplid:

// get-file.mjs
const API = "https://api.ipfs.ninja";
const API_KEY = "bws_your_key_here";
const CID = "bafkreigx7gq...";

const res = await fetch(`${API}/file/${CID}`, {
  headers: { "X-Api-Key": API_KEY }
});

const details = await res.json();
console.log(JSON.stringify(details, null, 2));

8. Kliendipoolne üleslaadimine allkirjastatud tokenitega

API võtme manustamine brauseri komplekti on turvarisk. Selle asemel genereerige oma serveris lühiajaline allkirjastatud token ja edastage see kliendile.

Server (Express)

// server.mjs
import express from "express";

const app = express();
const API = "https://api.ipfs.ninja";
const API_KEY = process.env.IPFS_API_KEY;

app.post("/api/upload-token", async (req, res) => {
  const response = await fetch(`${API}/upload/signed-url`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": API_KEY
    },
    body: JSON.stringify({
      name: "browser-upload",
      expiresIn: 600          // token valid for 10 minutes
    })
  });

  const { token, tokenId, expiresAt } = await response.json();
  res.json({ token, tokenId, expiresAt });
});

app.listen(3000, () => console.log("Server running on :3000"));

Brauseri klient

<!-- upload.html -->
<input type="file" id="filePicker" />
<button id="uploadBtn">Upload to IPFS</button>
<pre id="result"></pre>

<script>
  const API = "https://api.ipfs.ninja";

  document.getElementById("uploadBtn").addEventListener("click", async () => {
    // 1. Get a signed token from your own backend
    const tokenRes = await fetch("/api/upload-token", { method: "POST" });
    const { token } = await tokenRes.json();

    // 2. Read the selected file as base64
    const file = document.getElementById("filePicker").files[0];
    if (!file) return alert("Pick a file first");

    const base64 = await new Promise((resolve) => {
      const reader = new FileReader();
      reader.onload = () => resolve(reader.result.split(",")[1]);
      reader.readAsDataURL(file);
    });

    // 3. Upload directly to IPFS using the signed token
    const uploadRes = await fetch(`${API}/upload/new`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Signed ${token}`
      },
      body: JSON.stringify({
        content: base64,
        description: file.name
      })
    });

    const data = await uploadRes.json();
    document.getElementById("result").textContent = JSON.stringify(data, null, 2);
  });
</script>

Brauser ei näe kunagi teie API võtit. Allkirjastatud token aegub automaatselt. Tokenid on mitmekordseks kasutamiseks — neid saab kasutada mitu korda, kuni need aeguvad või tühistatakse. useCount jälgitakse, kuid seda ei jõustata piiranguna.

9. Vigade käsitsemine

API kasutab tavapäraseid HTTP olekukoode. Siin on need, mida peaksite selgelt käsitlema:

Vastupidav üleslaadimise funktsioon eksponentsiaalse backoff-iga:

// resilient-upload.mjs
const API = "https://api.ipfs.ninja";
const API_KEY = "bws_your_key_here";

async function uploadWithRetry(content, retries = 3) {
  for (let attempt = 1; attempt <= retries; attempt++) {
    const res = await fetch(`${API}/upload/new`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Api-Key": API_KEY
      },
      body: JSON.stringify({ content })
    });

    if (res.ok) return await res.json();

    const body = await res.text();

    if (res.status === 401) {
      throw new Error(`Authentication failed: ${body}`);
    }

    if (res.status === 413) {
      throw new Error(`Payload too large — reduce file size. ${body}`);
    }

    if (res.status === 429 || res.status >= 500) {
      const delay = Math.pow(2, attempt) * 1000;    // 2s, 4s, 8s
      console.warn(`Attempt ${attempt} failed (${res.status}). Retrying in ${delay}ms...`);
      await new Promise((r) => setTimeout(r, delay));
      continue;
    }

    throw new Error(`Upload failed (${res.status}): ${body}`);
  }

  throw new Error("Upload failed after all retries");
}

// Usage
const data = await uploadWithRetry({ hello: "world" });
console.log("CID:", data.cid);

10. Täielik töötav näide

Üks skript, mis kasutab kõiki selles õpetuses käsitletud lõpp-punkte. Salvestage see nimega ipfs-demo.mjs ja käivitage node ipfs-demo.mjs.

// ipfs-demo.mjs
import { readFileSync } from "node:fs";

const API = "https://api.ipfs.ninja";
const API_KEY = "bws_your_key_here";

const headers = {
  "Content-Type": "application/json",
  "X-Api-Key": API_KEY
};

async function request(method, path, body) {
  const opts = { method, headers };
  if (body) opts.body = JSON.stringify(body);
  const res = await fetch(`${API}${path}`, opts);
  if (!res.ok) throw new Error(`${method} ${path} → ${res.status}: ${await res.text()}`);
  return res.json();
}

// --- 1. Upload JSON ---
console.log("--- Upload JSON ---");
const jsonResult = await request("POST", "/upload/new", {
  content: { name: "Demo Token", edition: 1 },
  description: "Tutorial demo — JSON upload",
  metadata: { tutorial: "true" }
});
console.log("CID:", jsonResult.cid);
console.log("URL:", jsonResult.uris.url);

// --- 2. Upload an image (if photo.png exists) ---
try {
  const img = readFileSync("./photo.png");
  console.log("\n--- Upload Image ---");
  const imgResult = await request("POST", "/upload/new", {
    content: img.toString("base64"),
    description: "Tutorial demo — image upload"
  });
  console.log("CID:", imgResult.cid);
  console.log("URL:", imgResult.uris.url);
} catch {
  console.log("\n--- Skipping image upload (no photo.png found) ---");
}

// --- 3. Pin the JSON CID ---
console.log("\n--- Pin CID ---");
const pinResult = await request("POST", "/pin", {
  cid: jsonResult.cid,
  description: "Pinned from tutorial"
});
console.log("Pinned:", pinResult.cid);

// --- 4. Get file details ---
console.log("\n--- File Details ---");
const details = await request("GET", `/file/${jsonResult.cid}`);
console.log(JSON.stringify(details, null, 2));

// --- 5. List recent files ---
console.log("\n--- Recent Files ---");
const now = Date.now();
const oneHourAgo = now - 60 * 60 * 1000;
const files = await request("GET", `/upload/list?from=${oneHourAgo}&to=${now}`);
console.log(`Found ${files.length} file(s) in the last hour`);
for (const f of files) {
  console.log(` - ${f.cid}  ${f.description ?? ""}`);
}

// --- 6. Create a signed upload token ---
console.log("\n--- Signed Token ---");
const tokenResult = await request("POST", "/upload/signed-url", {
  name: "demo-token",
  expiresIn: 300
});
console.log("Token ID :", tokenResult.tokenId);
console.log("Expires  :", new Date(tokenResult.expiresAt).toISOString());

// --- 7. Upload using the signed token ---
console.log("\n--- Upload with Signed Token ---");
const signedRes = await fetch(`${API}/upload/new`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Signed ${tokenResult.token}`
  },
  body: JSON.stringify({
    content: { note: "Uploaded with a signed token" }
  })
});
const signedData = await signedRes.json();
console.log("CID:", signedData.cid);

console.log("\nDone.");

Asendage bws_your_key_here päris võtmega ja käivitage skript. Iga samm prindib oma tulemuse, nii et saate jälgida.

11. Järgmised sammud

Nüüd teate, kuidas faile üles laadida, kinnitada, loetleda ja hankida IPFS Upload API kaudu ning kuidas hoida brauseri üleslaadimisi turvaliselt allkirjastatud tokenitega. Laiema ülevaate, sealhulgas töölaua UI ja Pythoni näidete jaoks, vaadake Kuidas faile IPFS-i üles laadida. Siin on, kuhu siit edasi minna:

• API Reference — Täielik lõpp-punktide dokumentatsioon aadressil ipfs.ninja/docs.
• Kohandatud lüüsid — Pakkuge IPFS sisu oma domeenist. Vaadake lüüsi seadistamise juhendit.
• Analüütika — Jälgige üleslaadimismahtu, ribalaiust ja kinnituste arvu töölaual.
• HTTP klient — SDK pole vajalik. API-ga suhtlemiseks võite kasutada standardset fetch() või mis tahes HTTP klienti.

Kui kohtate probleeme, avage pilet aadressil support.ipfs.ninja või liituge kogukonnaga Discordis.