피닝

기존 IPFS 콘텐츠를 계정에 피닝하세요. CID를 피닝하면 클러스터가 IPFS 네트워크에서 콘텐츠를 가져와 영구적으로 가용하게 유지합니다.

CID로 피닝

POST /pin

매개변수	유형	필수	설명
cid	string	예	IPFS 콘텐츠 식별자. 모든 형태 허용: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy… 및 기타 코덱).
description	string	아니요	참조용 간단한 설명.
metadata	object	아니요	피닝에 첨부할 사용자 정의 키-값 쌍. 최대 10개 키. 키는 영숫자 또는 밑줄이어야 하며 1-64자. 값은 문자열이어야 하며 각 최대 256자. 메타데이터 총 크기는 4 KB를 초과할 수 없습니다.
multiaddresses	string[]	아니요	선택적 swarm-connect 힌트. CID를 호스팅하는 피어의 libp2p 멀티어드레스를 최대 5개까지 지정. 클러스터는 피닝 전에 각 항목에 대해 병렬로 swarm connect를 실행하므로, 프라이빗 / 비-DHT 피어의 콘텐츠도 DHT 검색을 기다리지 않고 접근할 수 있습니다. 최선 노력 방식으로 동작하며, 연결 실패가 피닝 자체를 실패시키지는 않습니다. 프라이빗 노드에서 피닝을 참조하세요.

요청 예시

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

응답 202 Accepted

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

대형 DAG(500개 이상의 블록 또는 50 MB 이상)의 경우, 응답에 async: true 플래그가 포함됩니다:

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

프라이빗 노드에서 피닝

피닝하려는 CID가 공개 DHT에 참여하지 않는 피어 — 프라이빗 스테이징 노드, VPN상의 자체 호스팅 머신, 또는 NAT 뒤의 워크스테이션 — 에 있다면, 기본 피닝 플로우는 이를 찾지 못합니다. 하나 이상의 multiaddresses를 전달하면 클러스터에 정확히 어디를 찾아야 하는지 알려줄 수 있습니다.

피닝이 실행되기 전에 각 힌트에 대해 병렬로 ipfs swarm connect <multiaddr>를 실행합니다. 연결에 성공하면 피닝의 DAG 가져오기가 DHT를 뒤지는 대신 피어와 직접 통신할 수 있습니다. 실패하더라도 피닝은 공개 네트워크를 대상으로 계속 진행됩니다 (최선 노력 방식).

예시: 특정 피어에서 피닝

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

응답에 힌트별 상태 포함

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

허용되는 멀티어드레스 형태

일반적인 형태가 지원됩니다: /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr 전송 방식; /tcp 또는 /udp 프로토콜; 선택적으로 /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct 업그레이드. 멀티어드레스는 반드시 /p2p/<peerId>로 끝나야 합니다. 상한: 피닝당 최대 5개 힌트.

노드의 멀티어드레스 얻기

피닝하려는 피어에서 ipfs id를 실행하고 /p2p/<PeerID>로 끝나는 Addresses 항목 중 하나를 복사하세요. 클러스터가 AWS에서 해당 피어에 도달할 수 있도록 공개적으로 라우팅 가능한 주소(/ip4/YOUR_PUBLIC_IP/…) 또는 DNS 기반 주소(/dnsaddr/your.domain/…)를 권장합니다.

매우 큰 디렉터리 피닝

POST /pin은 이미 IPFS 네트워크에 존재하는 콘텐츠를 위한 것입니다 — 클러스터는 피어로부터 DAG를 블록 단위로 가져오며, 1,000개 이상의 파일이 있는 디렉터리의 경우 몇 분이 걸릴 수 있습니다. 이 가져오기 창 동안 일부 자식 파일은 아직 로컬에서 사용할 수 없어 게이트웨이 요청이 타임아웃될 수 있습니다. 부모의 status가 pinned로 바뀌면 모든 자식이 로컬에서 사용 가능해지고 게이트웨이를 통해 접근할 수 있습니다.

CID만이 아니라 파일을 로컬에 가지고 있다면, 대형 NFT 컬렉션이나 데이터셋에는 CAR 가져오기를 사용하는 것이 좋습니다 — 전체 DAG를 하나의 원자적 요청으로 IPFS Ninja에 업로드하므로 가져오기 창도, 부분 피닝 상태도 없습니다. 다음으로 CAR를 생성하세요:

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

그런 다음 car: true와 함께 POST /upload/new로 가져오세요.

TIP

피닝은 비동기적입니다. 응답은 즉시 pinning 상태로 반환됩니다. 상태 엔드포인트를 폴링하여 피닝 완료를 확인하세요.

피닝 상태 확인

GET /pin/:cid

매개변수	유형	필수	설명
cid	string	예	확인할 CID.

응답 200 OK

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

상태 값

상태	의미
pinning	IPFS 네트워크에서 콘텐츠를 가져오는 중입니다. 몇 초 후에 다시 폴링하세요.
pinned	콘텐츠가 피닝되어 계정과 게이트웨이를 통해 접근할 수 있습니다.
failed	IPFS 네트워크에서 콘텐츠를 찾을 수 없습니다. CID가 유효하지 않거나 콘텐츠가 더 이상 사용할 수 없을 수 있습니다.

피닝 작동 방식

1. POST /pin으로 CID를 제출합니다
2. IPFS 클러스터가 네트워크에서 콘텐츠를 보유한 노드를 검색합니다
3. 클러스터가 콘텐츠를 다운로드하고 로컬에 피닝합니다
4. 피닝 완료 후 파일이 파일 목록에 표시되고 게이트웨이를 통해 접근 가능합니다
5. 피닝 완료 시 저장 공간 사용량이 기록됩니다

WARNING

피닝 시간은 파일 크기와 네트워크 가용성에 따라 달라집니다. 작은 파일은 일반적으로 몇 초 내에 피닝됩니다. 큰 파일이나 드물게 피닝된 콘텐츠는 몇 분이 걸릴 수 있습니다.

저장 공간

피닝된 콘텐츠는 플랜의 저장 공간 한도에 포함됩니다. 파일 크기는 피닝 완료 시 기록됩니다. 저장 공간 한도에 가까워지면 사용하지 않는 파일을 삭제하여 공간을 확보하거나 더 많은 용량을 위해 업그레이드할 수 있습니다.