Mula Pantas

Muat naik fail pertama anda ke IPFS dalam masa kurang dari dua minit.

1. Dapatkan API key anda

Daftar di ipfs.ninja dengan akaun Google anda. API key lalai dicipta secara automatik. Pergi ke halaman Profil anda untuk melihat dan mengurus API key anda.

WARNING

Nota: API key tidak luput. Anda boleh mencipta berbilang kunci dan membatalkannya secara individu dari halaman Profil anda.

2. Muat naik fail

Hantar permintaan POST ke /upload/new dengan kandungan anda. Berikut ialah contoh memuat naik objek JSON:

curl

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": "My NFT",
      "description": "A permanent file on IPFS",
      "image": "ipfs://bafybeiExampleCID..."
    },
    "description": "NFT metadata"
  }'

JavaScript

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: {
      name: "My NFT",
      description: "A permanent file on IPFS",
      image: "ipfs://bafybeiExampleCID..."
    },
    description: "NFT metadata"
  })
});

const data = await response.json();
console.log(data.cid);       // "bafybeigdyrzt5..."
console.log(data.uris.url);  // "https://ipfs.ninja/ipfs/bafybeigdyrzt5..."

CIDv1 secara lalai

Muat naik baharu menghasilkan CIDv1 moden (bafk… untuk kandungan blok tunggal yang kecil, bafy… untuk fail dan direktori yang lebih besar) mengikut IPIP-0499. CID Qm… lama daripada muat naik terdahulu masih boleh diselesaikan di mana-mana sahaja — kedua-dua format berfungsi sebagai input untuk setiap endpoint.

API mengembalikan CID, saiz fail dan URI akses:

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

3. Dapatkan semula fail anda

Akses fail anda dengan dua cara:

Melalui gateway IPFS (tiada pengesahan diperlukan)

curl https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

TIP

Gateway apex https://ipfs.ninja/ipfs/<CID> menyajikan CID yang dimuat naik atau disematkan oleh mana-mana pengguna IPFS Ninja. CID yang tidak diketahui oleh platform mengembalikan HTTP 410 Gone — untuknya, gunakan gateway awam (ipfs.io, dweb.link) atau lakukan POST /pin CID ke akaun anda terlebih dahulu.

Melalui API (mengembalikan metadata fail)

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

Respons:

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

Alternatif: Guna AWS SDK (serasi S3)

Sudah menggunakan S3? Arahkan AWS SDK sedia ada anda ke https://s3.ipfs.ninja dan gunakan API key anda sebagai kelayakan:

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: "https://s3.ipfs.ninja",
  credentials: { accessKeyId: "bws_prefix", secretAccessKey: "bws_fullkey" },
  region: "us-east-1",
  forcePathStyle: true
});

await s3.send(new PutObjectCommand({
  Bucket: "my-project",
  Key: "my-file.json",
  Body: JSON.stringify({ hello: "IPFS" })
}));

Lihat Keserasian S3 untuk dokumentasi penuh dengan contoh Python, Go, dan panduan migrasi.

Lebih suka klik? Guna Papan Pemuka

Jika anda tidak mahu menulis kod, ipfs.ninja/upload menerima drag-and-drop untuk:

• Sebarang fail — lepaskan pada zon muat naik, disemat + anda dapat CID
• Folder — dibungkus menjadi direktori UnixFS dalam pelayar anda, dimuat naik sebagai satu import, boleh diselesaikan pada /ipfs/{cid}/{subpath} untuk setiap fail anak
• Arkib .car — dikesan secara automatik, CID akar dikekalkan dengan tepat (lihat Import CAR)

Setelah dimuat naik, fail muncul pada halaman Fail di mana anda boleh namakan semula, alihkan antara folder, dapatkan CID direktori IPFS untuk keseluruhan folder (snapshot), dan konfigurasikan S3 CORS per-bucket untuk akses SDK pelayar.

Langkah seterusnya

• Rujukan API — Dokumentasi penuh untuk semua endpoint, parameter dan kod ralat.
• Keserasian S3 — Gunakan AWS SDK untuk berinteraksi dengan IPFS Ninja.
• Gateway Khusus — Dapatkan gateway peribadi yang hanya menyajikan fail anda.