Penyematan

Semat kandungan IPFS sedia ada ke akaun anda. Apabila anda menyemat CID, kluster kami mendapatkan kandungan dari rangkaian IPFS dan memastikan ia kekal tersedia secara kekal.

Semat mengikut CID

POST /pin

Parameter	Jenis	Diperlukan	Penerangan
cid	string	Ya	Pengecam kandungan IPFS. Sebarang bentuk diterima: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy…, dan codec lain).
description	string	Tidak	Penerangan ringkas untuk rujukan anda.
metadata	object	Tidak	Pasangan kunci-nilai tersuai untuk dilampirkan pada sematan. Maks 10 kunci. Kunci mestilah alfanumerik atau garis bawah, 1-64 aksara. Nilai mestilah rentetan, maks 256 aksara setiap satu. Jumlah saiz metadata tidak boleh melebihi 4 KB.
multiaddresses	string[]	Tidak	Petunjuk swarm-connect pilihan. Sehingga 5 multiaddress libp2p bagi peer yang mempunyai CID tersebut. Kluster kami menjalankan swarm connect terhadap setiap satu secara selari sebelum sematan dilakukan, jadi kandungan pada peer peribadi / bukan-DHT boleh dicapai tanpa menunggu penemuan DHT. Best-effort — sambungan yang gagal tidak menggagalkan sematan. Lihat Menyemat dari nod peribadi.

Contoh permintaan

curl -X POST https://api.ipfs.ninja/pin \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "description": "NFT metadata",
    "metadata": {
      "collection": "my-nfts",
      "token_id": "42"
    }
  }'

Respons 202 Accepted

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "description": "NFT metadata",
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Untuk DAG yang besar (>500 blok atau >50 MB), respons menyertakan flag async: true:

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "async": true,
  "note": "Large DAG detected — pin running in background. Check status via GET /pin/bafybei…",
  "uris": { ... }
}

Menyemat dari nod peribadi

Jika CID yang ingin anda semat berada pada peer yang tidak menyertai DHT awam — nod staging peribadi, mesin self-hosted pada VPN, atau workstation di sebalik NAT — aliran sematan lalai tidak akan menemuinya. Menghantar satu atau lebih multiaddresses memberitahu kluster kami dengan tepat di mana hendak mencari.

Kami menjalankan ipfs swarm connect <multiaddr> untuk setiap petunjuk secara selari sebelum sematan dijalankan. Jika sambungan berjaya, pengambilan DAG sematan boleh berhubung terus dengan peer anda dan bukannya memburu melalui DHT. Jika ia gagal, sematan tetap diteruskan terhadap rangkaian awam (semantik best-effort).

Contoh: semat dari peer tertentu

curl -X POST https://api.ipfs.ninja/pin \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "description": "internal staging build",
    "multiaddresses": [
      "/ip4/203.0.113.42/tcp/4001/p2p/12D3KooWH3uVF6wv47WnArKHk5p6cvgCJEb74UTmxztmQDc298L3",
      "/dns4/node.internal.example/tcp/443/wss/p2p/12D3KooWH3uVF6wv47WnArKHk5p6cvgCJEb74UTmxztmQDc298L3"
    ]
  }'

Respons menyertakan status setiap petunjuk

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "swarmConnected": [
    { "multiaddr": "/ip4/203.0.113.42/tcp/4001/p2p/12D3KooW…", "ok": true,  "strings": ["connect 12D3KooW… success"] },
    { "multiaddr": "/dns4/node.internal.example/tcp/443/…",   "ok": false, "error": "dial to peer: no route" }
  ],
  "uris": { … }
}

Bentuk multiaddress yang diterima

Bentuk biasa disokong: pengangkutan /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr; protokol /tcp atau /udp; peningkatan pilihan /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct. Multiaddress mesti berakhir dengan /p2p/<peerId>. Had: sehingga 5 petunjuk setiap sematan.

Mendapatkan multiaddress nod anda

Pada peer yang ingin anda semat, jalankan ipfs id dan salin mana-mana entri Addresses yang berakhir dengan /p2p/<PeerID>. Utamakan alamat routable awam (/ip4/YOUR_PUBLIC_IP/…) atau yang berasaskan DNS (/dnsaddr/your.domain/…) supaya kluster kami boleh mencapai peer tersebut dari AWS.

Menyemat direktori yang sangat besar

POST /pin adalah untuk kandungan yang sudah wujud pada rangkaian IPFS — kluster mengambil DAG blok demi blok dari peer, yang boleh mengambil masa beberapa minit untuk direktori dengan 1,000+ fail. Semasa tempoh pengambilan tersebut, sesetengah fail anak mungkin belum tersedia secara setempat dan permintaan gateway kepadanya mungkin timeout. Setelah status induk bertukar kepada pinned, setiap anak tersedia secara setempat dan boleh diakses melalui gateway anda.

Jika anda mempunyai fail tersebut secara setempat (bukan sekadar CID), utamakan import CAR untuk koleksi NFT atau set data yang besar — ia memuat naik keseluruhan DAG ke IPFS Ninja dalam satu permintaan atom, jadi tiada tempoh pengambilan dan tiada keadaan sematan separa. Cipta CAR dengan:

npx ipfs-car pack ./my-collection -o collection.car

Kemudian import melalui POST /upload/new dengan car: true.

TIP

Penyematan adalah tak segerak. Respons dikembalikan serta-merta dengan status pinning. Poll endpoint status untuk menyemak apabila sematan selesai.

Semak Status Sematan

GET /pin/:cid

Parameter	Jenis	Diperlukan	Penerangan
cid	string	Ya	CID yang anda semak.

Respons 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinned",
  "sizeMB": 0.042,
  "fileName": "NFT metadata",
  "pinnedAt": 1711036800000,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Nilai status

Status	Makna
pinning	Kandungan sedang diambil dari rangkaian IPFS. Poll semula dalam beberapa saat.
pinned	Kandungan disemat dan tersedia melalui akaun dan gateway anda.
failed	Kandungan tidak dapat ditemui di rangkaian IPFS. CID mungkin tidak sah atau kandungan tidak lagi tersedia.

Bagaimana penyematan berfungsi

1. Anda menghantar CID melalui POST /pin
2. Kluster IPFS kami mencari rangkaian untuk nod yang mempunyai kandungan tersebut
3. Kluster memuat turun dan menyemat kandungan secara setempat
4. Setelah disemat, fail muncul dalam senarai fail anda dan boleh diakses melalui gateway
5. Penggunaan storan direkodkan apabila sematan selesai

WARNING

Masa penyematan bergantung pada saiz fail dan ketersediaan rangkaian. Fail kecil biasanya disemat dalam beberapa saat. Fail besar atau kandungan yang jarang disemat mungkin mengambil beberapa minit.

Storan

Kandungan yang disemat dikira ke dalam had storan pelan anda. Saiz fail direkodkan apabila sematan selesai. Jika anda menghampiri had storan, anda boleh membebaskan ruang dengan memadam fail yang tidak digunakan atau menaik taraf untuk kapasiti lebih besar.