Festing

Fest eksisterende IPFS-innhold til kontoen din. Når du fester et CID, henter klyngen vår innholdet fra IPFS-nettverket og holder det permanent tilgjengelig.

Fest via CID

POST /pin

Parameter	Type	Påkrevd	Beskrivelse
cid	string	Ja	IPFS-innholdsidentifikator. Enhver form godtas: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy… og andre codecs).
description	string	Nei	Kort beskrivelse for din referanse.
metadata	object	Nei	Egendefinerte nøkkel-verdi-par å legge ved festingen. Maks 10 nøkler. Nøkler må være alfanumeriske eller understrek, 1-64 tegn. Verdier må være strenger, maks 256 tegn hver. Total metadatastørrelse må ikke overstige 4 KB.
multiaddresses	string[]	Nei	Valgfrie swarm-connect-hint. Opptil 5 libp2p-multiadresser til noder som er vert for CID-en. Klyngen vår kjører swarm connect mot hver av dem parallelt før festingen, slik at innhold på private/ikke-DHT-noder blir tilgjengelig uten å vente på DHT-oppdagelse. Beste innsats — en mislykket tilkobling får ikke festingen til å feile. Se Festing fra en privat node.

Eksempelforespørsel

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

Svar 202 Accepted

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

For store DAG-er (>500 blokker eller >50 MB) inkluderer svaret et async: true-flagg:

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

Festing fra en privat node

Hvis CID-en du vil feste ligger på en node som ikke deltar i den offentlige DHT-en — en privat staging-node, en selvhostet maskin på et VPN, eller en arbeidsstasjon bak NAT — vil ikke standard festingsflyt finne den. Ved å oppgi én eller flere multiaddresses forteller du klyngen vår nøyaktig hvor den skal se.

Vi kjører ipfs swarm connect <multiaddr> for hvert hint parallelt før festingen kjører. Hvis tilkoblingen lykkes, kan festingens DAG-henting snakke direkte med noden din i stedet for å lete gjennom DHT-en. Hvis den feiler, fortsetter festingen likevel mot det offentlige nettverket (beste-innsats-semantikk).

Eksempel: fest fra en spesifikk node

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"
    ]
  }'

Svaret inkluderer status per hint

{
  "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": { … }
}

Godtatte multiadresseformer

Vanlige former støttes: transportene /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr; protokollene /tcp eller /udp; valgfrie oppgraderinger /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct. Multiadressen må avsluttes med /p2p/<peerId>. Grense: opptil 5 hint per festing.

Finne multiadressen til noden din

På noden du vil feste fra, kjør ipfs id og kopier en av oppføringene under Addresses som avsluttes med /p2p/<PeerID>. Foretrekk offentlig rutbare adresser (/ip4/YOUR_PUBLIC_IP/…) eller DNS-baserte (/dnsaddr/your.domain/…) slik at klyngen vår kan nå noden fra AWS.

Festing av svært store kataloger

POST /pin er for innhold som allerede finnes på IPFS-nettverket — klyngen henter DAG-en blokk for blokk fra noder, noe som kan ta flere minutter for kataloger med 1000+ filer. I løpet av dette hentingsvinduet kan noen underliggende filer ennå ikke være lokalt tilgjengelige, og gateway-forespørsler til dem kan gå i timeout. Når foreldrens status går over til pinned, er alle underliggende filer lokalt tilgjengelige og tilgjengelige via gatewayen din.

Hvis du har filene lokalt (i stedet for bare en CID), foretrekk CAR-import for store NFT-samlinger eller datasett — det laster opp hele DAG-en til IPFS Ninja i én atomisk forespørsel, så det finnes ikke noe hentingsvindu eller noen delvis-festet tilstand. Opprett en CAR med:

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

Importer den deretter via POST /upload/new med car: true.

TIP

Festing er asynkron. Svaret returneres umiddelbart med status pinning. Poll statusendepunktet for å sjekke når festingen er fullført.

Sjekk festingsstatus

GET /pin/:cid

Parameter	Type	Påkrevd	Beskrivelse
cid	string	Ja	CID-en du sjekker.

Svar 200 OK

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

Statusverdier

Status	Betydning
pinning	Innholdet hentes fra IPFS-nettverket. Poll igjen om noen sekunder.
pinned	Innholdet er festet og tilgjengelig via kontoen din og gatewayen.
failed	Innholdet kunne ikke finnes på IPFS-nettverket. CID-en kan være ugyldig eller innholdet er ikke lenger tilgjengelig.

Hvordan festing fungerer

1. Du sender et CID via POST /pin
2. IPFS-klyngen vår søker nettverket etter noder som har innholdet
3. Klyngen laster ned og fester innholdet lokalt
4. Når det er festet, vises filen i fillisten din og er tilgjengelig via gatewayen
5. Lagringsbruk registreres når festingen er fullført

WARNING

Festingstiden avhenger av filstørrelse og nettverkstilgjengelighet. Små filer festes vanligvis på sekunder. Store filer eller sjelden festet innhold kan ta minutter.

Lagring

Festet innhold teller mot planens lagringsgrense. Filstørrelsen registreres når festingen er fullført. Hvis du nærmer deg lagringsgrensen din, kan du frigjøre plass ved å slette ubrukte filer eller oppgradere for mer kapasitet.