IPFS Upload API — সম্পূর্ণ ডেভেলপার টিউটোরিয়াল

IPFS-এ ফাইল আপলোড করা একটি POST অনুরোধ পাঠানোর মতই সহজ হওয়া উচিত। এই টিউটোরিয়ালে আপনি ঠিক সেটাই করবেন — শুধুমাত্র fetch() এবং একটি API কী দিয়ে IPFS-এ JSON ডকুমেন্ট, ছবি এবং PDF আপলোড করবেন। শেষে আপনার কাছে একটি সম্পূর্ণ Node.js স্ক্রিপ্ট থাকবে যা কন্টেন্ট আপলোড করে, ফাইল তালিকা করে, মেটাডেটা পুনরুদ্ধার করে এবং নিরাপদ ক্লায়েন্ট-সাইড আপলোডের জন্য সাইন করা টোকেন তৈরি করে। IPFS-এ নতুন? কোডে ঝাঁপ দেওয়ার আগে মৌলিক বিষয়গুলি বোঝার জন্য IPFS Pinning কী? দিয়ে শুরু করুন।

আপনি যা তৈরি করবেন

• IPFS-এ একটি JSON অবজেক্ট আপলোড করুন এবং একটি কন্টেন্ট আইডেন্টিফায়ার (CID) ফেরত পান।
• ডিস্ক থেকে একটি বাইনারি ছবি আপলোড করুন।
• আপলোডগুলিতে বর্ণনা এবং কাস্টম মেটাডেটা সংযুক্ত করুন।
• তারিখের পরিসর অনুযায়ী আপনার আপলোড ইতিহাস কোয়েরি করুন।
• একটি নির্দিষ্ট ফাইলের জন্য বিশদ পুনরুদ্ধার করুন।
• সময়-সীমিত সাইন করা টোকেন তৈরি করুন যাতে একটি ব্রাউজার আপনার API কী এক্সপোজ না করেই সরাসরি আপলোড করতে পারে।
• ত্রুটিগুলি পরিচালনা করুন এবং পুনরায় চেষ্টার লজিক প্রয়োগ করুন।

সবকিছু একটি একক বেস URL এর বিরুদ্ধে চলে: https://api.ipfs.ninja

১. সেটআপ — সাইন আপ করুন এবং API কী পান

1. একটি বিনামূল্যের অ্যাকাউন্টের জন্য সাইন আপ করুন (কোনো ক্রেডিট কার্ড প্রয়োজন নেই)।
2. ড্যাশবোর্ড সাইডবারে API Keys এ যান।
3. Create key ক্লিক করুন, এটিকে একটি নাম দিন এবং কীটি অবিলম্বে কপি করুন — এটি আর দেখানো হবে না।

আপনার কী এরকম দেখায়: bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6। নিচের প্রতিটি উদাহরণ এটিকে X-Api-Key হেডারে পাঠায়।

২. IPFS-এ JSON আপলোড

সবচেয়ে সহজ আপলোড: content হিসাবে একটি প্লেইন JavaScript অবজেক্ট পাস করুন এবং API এটিকে সিরিয়ালাইজ করে, IPFS-এ পিন করে এবং 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);

node upload-json.mjs দিয়ে চালান। একটি সফল প্রতিক্রিয়া এইরকম দেখায়:

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

url ফিল্ড একটি পাবলিক HTTP গেটওয়ের দিকে নির্দেশ করে, তাই কন্টেন্ট যেকোনো ব্রাউজারে অবিলম্বে অ্যাক্সেসযোগ্য।

৩. একটি ছবি আপলোড

বাইনারি ফাইল (ছবি, PDF, অডিও) content ফিল্ডে base64-এনকোডেড স্ট্রিং হিসাবে পাঠানো হয়।

// 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 স্বয়ংক্রিয়ভাবে MIME টাইপ সনাক্ত করে — PNG, JPEG, WebP, GIF এবং PDF সব সমর্থিত। কোনো অতিরিক্ত হেডার বা content-type ওভাররাইড প্রয়োজন নেই।

curl দিয়ে একই অপারেশন এইরকম দেখায়:

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

৪. মেটাডেটা সহ আপলোড

প্রতিটি আপলোড দুটি ঐচ্ছিক ফিল্ড গ্রহণ করে: description (মুক্ত-টেক্সট লেবেল) এবং metadata (যেকোনো কী-মান জোড়া)। উভয়ই CID-এর পাশাপাশি সংরক্ষিত হয় এবং পরে যখন আপনি ফাইলটি তালিকাভুক্ত বা ফেচ করেন তখন ফেরত দেওয়া হয়।

// 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);

মেটাডেটা IPFS কন্টেন্ট নিজেই পার্স না করে আপনার পক্ষে ফাইল ফিল্টার এবং সংগঠিত করা সহজ করে।

৫. একটি বিদ্যমান CID পিন করুন

আপনার যদি ইতিমধ্যে IPFS-এ কন্টেন্ট থাকে এবং এটি উপলব্ধ থাকা নিশ্চিত করতে চান, তাহলে CID দ্বারা পিন করুন:

// 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);

৬. আপনার ফাইল তালিকাভুক্ত করুন

একটি সময়ের উইন্ডোর মধ্যে আপনি যে প্রতিটি ফাইল আপলোড করেছেন তা পুনরুদ্ধার করুন। from এবং to কোয়েরি প্যারামিটার হল মিলিসেকেন্ডে Unix টাইমস্ট্যাম্প।

// 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 দিয়ে:

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 .

৭. ফাইলের বিশদ পান

মেটাডেটা, আকার এবং টাইমস্ট্যাম্প সহ একটি একক CID-এর সম্পূর্ণ রেকর্ড ফেচ করুন:

// 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));

৮. সাইন করা টোকেন সহ ক্লায়েন্ট-সাইড আপলোড

একটি ব্রাউজার বান্ডেলে একটি API কী এম্বেড করা একটি নিরাপত্তা ঝুঁকি। পরিবর্তে, আপনার সার্ভারে একটি স্বল্প-মেয়াদী সাইন করা টোকেন তৈরি করুন এবং এটি ক্লায়েন্টের কাছে পাঠান।

সার্ভার (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"));

ব্রাউজার ক্লায়েন্ট

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

ব্রাউজার কখনই আপনার API কী দেখে না। সাইন করা টোকেন স্বয়ংক্রিয়ভাবে মেয়াদ শেষ হয়। টোকেনগুলি বহু-ব্যবহার্য — সেগুলির মেয়াদ শেষ না হওয়া পর্যন্ত বা প্রত্যাহার না হওয়া পর্যন্ত একাধিকবার ব্যবহার করা যেতে পারে। useCount ট্র্যাক করা হয় কিন্তু একটি সীমা হিসাবে প্রয়োগ করা হয় না।

৯. ত্রুটি হ্যান্ডলিং

API প্রচলিত HTTP স্ট্যাটাস কোড ব্যবহার করে। এখানে যেগুলি আপনার স্পষ্টভাবে পরিচালনা করা উচিত:

সূচক ব্যাকঅফ সহ একটি স্থিতিস্থাপক আপলোড ফাংশন:

// 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);

১০. সম্পূর্ণ কার্যকরী উদাহরণ

একটি একক স্ক্রিপ্ট যা এই টিউটোরিয়ালে কভার করা প্রতিটি এন্ডপয়েন্ট অনুশীলন করে। এটিকে ipfs-demo.mjs হিসাবে সংরক্ষণ করুন এবং 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.");

bws_your_key_here কে একটি বাস্তব কী দিয়ে প্রতিস্থাপন করুন এবং স্ক্রিপ্ট চালান। প্রতিটি ধাপ এর ফলাফল প্রিন্ট করে যাতে আপনি অনুসরণ করতে পারেন।

১১. পরবর্তী পদক্ষেপ

আপনি এখন জানেন কীভাবে IPFS Upload API এর মাধ্যমে ফাইল আপলোড, পিন, তালিকাভুক্ত এবং পুনরুদ্ধার করতে হয় এবং সাইন করা টোকেন দিয়ে ব্রাউজার আপলোডগুলি নিরাপদ রাখতে হয়। ড্যাশবোর্ড UI এবং Python উদাহরণ সহ একটি বিস্তৃত ওভারভিউয়ের জন্য, IPFS-এ ফাইল কীভাবে আপলোড করবেন দেখুন। এখান থেকে যেখানে যাবেন:

• API Reference — ipfs.ninja/docs এ সম্পূর্ণ এন্ডপয়েন্ট ডকুমেন্টেশন।
• কাস্টম গেটওয়ে — আপনার নিজস্ব ডোমেন থেকে IPFS কন্টেন্ট পরিবেশন করুন। গেটওয়ে সেটআপ গাইড দেখুন।
• অ্যানালিটিক্স — ড্যাশবোর্ডে আপলোডের পরিমাণ, ব্যান্ডউইথ এবং পিন সংখ্যা ট্র্যাক করুন।
• HTTP ক্লায়েন্ট — কোনো SDK প্রয়োজন নেই। API-এর সাথে ইন্টারঅ্যাক্ট করতে আপনি স্ট্যান্ডার্ড fetch() বা যেকোনো HTTP ক্লায়েন্ট ব্যবহার করতে পারেন।

যদি আপনি সমস্যার সম্মুখীন হন, support.ipfs.ninja এ একটি টিকিট খুলুন বা Discord-এ কমিউনিটিতে যোগ দিন।