IPFS Upload API — संपूर्ण डेवलपर ट्यूटोरियल

IPFS पर फ़ाइलें अपलोड करना उतना ही सरल होना चाहिए जितना POST अनुरोध करना। इस ट्यूटोरियल में आप ठीक यही करेंगे — केवल fetch() और एक API कुंजी के साथ IPFS पर JSON दस्तावेज़, छवियाँ, और PDF अपलोड करेंगे। अंत में, आपके पास एक पूर्ण Node.js स्क्रिप्ट होगी जो सामग्री अपलोड करती है, फ़ाइलों को सूचीबद्ध करती है, मेटाडेटा प्राप्त करती है, और सुरक्षित क्लाइंट-साइड अपलोड के लिए हस्ताक्षरित टोकन उत्पन्न करती है। IPFS में नए हैं? कोड में कूदने से पहले बुनियादी बातों को समझने के लिए IPFS Pinning क्या है? से शुरू करें।

आप क्या बनाएंगे

• IPFS पर एक JSON ऑब्जेक्ट अपलोड करें और एक सामग्री पहचानकर्ता (CID) वापस प्राप्त करें।
• डिस्क से एक बाइनरी छवि अपलोड करें।
• अपलोड के लिए विवरण और कस्टम मेटाडेटा संलग्न करें।
• तिथि सीमा के अनुसार अपने अपलोड इतिहास को क्वेरी करें।
• किसी विशिष्ट फ़ाइल के लिए विवरण प्राप्त करें।
• समय-सीमित हस्ताक्षरित टोकन बनाएँ ताकि एक ब्राउज़र आपकी API कुंजी का खुलासा किए बिना सीधे अपलोड कर सके।
• त्रुटियों को संभालें और पुनः प्रयास तर्क लागू करें।

सब कुछ एक एकल बेस URL के विरुद्ध चलता है: https://api.ipfs.ninja

1. सेटअप — साइन अप करें और API कुंजी प्राप्त करें

1. एक मुफ्त खाते के लिए साइन अप करें (क्रेडिट कार्ड की आवश्यकता नहीं)।
2. डैशबोर्ड साइडबार में API Keys पर जाएँ।
3. Create key पर क्लिक करें, इसे एक नाम दें, और कुंजी को तुरंत कॉपी करें — यह फिर से नहीं दिखाई जाएगी।

आपकी कुंजी bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 जैसी दिखती है। नीचे दिया गया प्रत्येक उदाहरण इसे X-Api-Key हेडर में भेजता है।

2. IPFS पर JSON अपलोड करें

सबसे सरल अपलोड: एक सादे JavaScript ऑब्जेक्ट को content के रूप में पास करें और 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 गेटवे की ओर इशारा करती है, इसलिए सामग्री तुरंत किसी भी ब्राउज़र में सुलभ है।

3. एक छवि अपलोड करें

बाइनरी फ़ाइलें (छवियाँ, 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\"}"

4. मेटाडेटा के साथ अपलोड

प्रत्येक अपलोड दो वैकल्पिक फ़ील्ड स्वीकार करता है: 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 सामग्री को स्वयं पार्स किए बिना आपकी ओर से फ़ाइलों को फ़िल्टर और व्यवस्थित करना आसान बनाता है।

5. एक मौजूदा 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);

6. अपनी फ़ाइलों को सूचीबद्ध करें

समय विंडो के भीतर आपके द्वारा अपलोड की गई प्रत्येक फ़ाइल को प्राप्त करें। 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 .

7. फ़ाइल विवरण प्राप्त करें

मेटाडेटा, आकार, और टाइमस्टैम्प सहित एक एकल 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));

8. हस्ताक्षरित टोकन के साथ क्लाइंट-साइड अपलोड

ब्राउज़र बंडल में 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 ट्रैक किया जाता है लेकिन एक सीमा के रूप में लागू नहीं किया जाता है।

9. त्रुटि हैंडलिंग

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

10. पूर्ण कार्यशील उदाहरण

एक एकल स्क्रिप्ट जो इस ट्यूटोरियल में शामिल प्रत्येक एंडपॉइंट का अभ्यास करती है। इसे 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 को एक वास्तविक कुंजी से बदलें और स्क्रिप्ट चलाएँ। प्रत्येक चरण अपना परिणाम प्रिंट करता है ताकि आप अनुसरण कर सकें।

11. अगले कदम

अब आप जानते हैं कि IPFS Upload API के माध्यम से फ़ाइलों को कैसे अपलोड, पिन, सूचीबद्ध, और पुनः प्राप्त करना है और हस्ताक्षरित टोकन के साथ ब्राउज़र अपलोड को सुरक्षित कैसे रखना है। डैशबोर्ड UI और Python उदाहरणों सहित एक व्यापक अवलोकन के लिए, IPFS पर फ़ाइलें कैसे अपलोड करें देखें। यहाँ से कहाँ जाएँ:

• API संदर्भ — ipfs.ninja/docs पर पूर्ण एंडपॉइंट दस्तावेज़ीकरण।
• कस्टम गेटवे — अपने स्वयं के डोमेन से IPFS सामग्री प्रदान करें। गेटवे सेटअप गाइड देखें।
• एनालिटिक्स — डैशबोर्ड में अपलोड वॉल्यूम, बैंडविड्थ, और पिन गणनाओं को ट्रैक करें।
• HTTP क्लाइंट — कोई SDK आवश्यक नहीं है। API के साथ इंटरैक्ट करने के लिए मानक fetch() या किसी भी HTTP क्लाइंट का उपयोग कर सकते हैं।

यदि आपको समस्याएँ आती हैं, तो support.ipfs.ninja पर एक टिकट खोलें या Discord पर समुदाय में शामिल हों।