Fastgørelse

Fastgør eksisterende IPFS-indhold til din konto. Når du fastgør et CID, henter vores klynge indholdet fra IPFS-netværket og holder det permanent tilgængeligt.

Fastgør via CID

POST /pin

Parameter	Type	Påkrævet	Beskrivelse
cid	string	Ja	IPFS-indholdsidentifikator. Enhver form accepteres: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy… og andre codecs).
description	string	Nej	Kort beskrivelse til din reference.
metadata	object	Nej	Brugerdefinerede nøgle-værdi-par at vedhæfte til fastgørelsen. Maks 10 nøgler. Nøgler skal være alfanumeriske eller underscore, 1-64 tegn. Værdier skal være strenge, maks 256 tegn hver. Total metadatastørrelse må ikke overstige 4 KB.
multiaddresses	string[]	Nej	Valgfri swarm-connect-hints. Op til 5 libp2p-multiadresser for peers, der hoster CID'et. Vores klynge kører swarm connect mod hver af dem parallelt før fastgørelsen, så indhold på private/ikke-DHT-peers kan nås uden at vente på DHT-opdagelse. Bedste-indsats — en mislykket forbindelse fejler ikke fastgørelsen. Se Fastgørelse fra en privat node.

Eksempelforespørgsel

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 blokke eller >50 MB) inkluderer svaret et async: true-flag:

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

Fastgørelse fra en privat node

Hvis det CID, du vil fastgøre, findes på en peer, der ikke deltager i den offentlige DHT — en privat staging-node, en selv-hostet maskine på et VPN eller en arbejdsstation bag NAT — vil standard-fastgørelsesflowet ikke finde det. Ved at angive en eller flere multiaddresses fortæller du vores klynge præcis, hvor den skal kigge.

Vi kører ipfs swarm connect <multiaddr> for hvert hint parallelt før fastgørelsen køres. Hvis forbindelsen lykkes, kan fastgørelsens DAG-hentning tale direkte med din peer i stedet for at søge gennem DHT'en. Hvis den fejler, fortsætter fastgørelsen alligevel mod det offentlige netværk (bedste-indsats-semantik).

Eksempel: fastgør fra en specifik peer

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

Understøttede multiadresse-former

Almindelige former understøttes: /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr-transporter; /tcp eller /udp-protokoller; valgfrie /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct-opgraderinger. Multiadressen skal ende med /p2p/<peerId>. Grænse: op til 5 hints per fastgørelse.

Sådan finder du din nodes multiadresse

På den peer, du vil fastgøre fra, kør ipfs id og kopiér en af Addresses-posterne, der slutter med /p2p/<PeerID>. Foretræk offentligt routebare adresser (/ip4/YOUR_PUBLIC_IP/…) eller DNS-baserede (/dnsaddr/your.domain/…), så vores klynge kan nå peeren fra AWS.

Fastgørelse af meget store mapper

POST /pin er beregnet til indhold, der allerede findes på IPFS-netværket — klyngen henter DAG'en blok for blok fra peers, hvilket kan tage flere minutter for mapper med 1.000+ filer. I dette hentningsvindue er nogle underliggende filer muligvis endnu ikke lokalt tilgængelige, og gateway-forespørgsler til dem kan time out. Når det overordnede elements status skifter til pinned, er hver underliggende fil lokalt tilgængelig og tilgængelig via din gateway.

Hvis du har filerne lokalt (i stedet for blot et CID), foretræk CAR-import for store NFT-samlinger eller datasæt — det uploader hele DAG'en til IPFS Ninja i én atomisk forespørgsel, så der er intet hentningsvindue og ingen delvis fastgørelsestilstand. Opret en CAR med:

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

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

TIP

Fastgørelse er asynkron. Svaret returneres øjeblikkeligt med status pinning. Poll statusendpointet for at tjekke, hvornår fastgørelsen er fuldført.

Tjek fastgørelsesstatus

GET /pin/:cid

Parameter	Type	Påkrævet	Beskrivelse
cid	string	Ja	Det CID du tjekker.

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

Statusværdier

Status	Betydning
pinning	Indholdet hentes fra IPFS-netværket. Poll igen om et par sekunder.
pinned	Indholdet er fastgjort og tilgængeligt via din konto og gateway.
failed	Indholdet kunne ikke findes på IPFS-netværket. CID'et kan være ugyldigt, eller indholdet er ikke længere tilgængeligt.

Hvordan fastgørelse fungerer

1. Du indsender et CID via POST /pin
2. Vores IPFS-klynge søger netværket efter noder, der har indholdet
3. Klyngen downloader og fastgør indholdet lokalt
4. Når det er fastgjort, vises filen i din filliste og er tilgængelig via gateway
5. Lagringsforbrug registreres, når fastgørelsen er fuldført

WARNING

Fastgørelsestiden afhænger af filstørrelse og netværkstilgængelighed. Små filer fastgøres typisk på sekunder. Store filer eller sjældent fastgjort indhold kan tage minutter.

Lagring

Fastgjort indhold tæller mod din plans lagergrænse. Filstørrelsen registreres, når fastgørelsen er fuldført. Hvis du nærmer dig din lagringsgrænse, kan du frigøre plads ved at slette ubrugte filer eller opgradere for mere kapacitet.