피닝

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

CID로 피닝

POST /pin

매개변수	유형	필수	설명
`cid`	string	예	IPFS 콘텐츠 식별자 (`Qm` 또는 `bafy`로 시작).
`description`	string	아니요	참조용 간단한 설명.
`metadata`	object	아니요	피닝에 첨부할 사용자 정의 키-값 쌍. 최대 10개 키. 키는 영숫자 또는 밑줄이어야 하며 1-64자. 값은 문자열이어야 하며 각 최대 256자. 메타데이터 총 크기는 4 KB를 초과할 수 없습니다.

요청 예시

bash

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

응답 `202 Accepted`

json

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

TIP

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

피닝 상태 확인

GET /pin/:cid

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

응답 `200 OK`

json

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

상태 값

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

피닝 작동 방식

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

WARNING

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

저장 공간

피닝된 콘텐츠는 플랜의 저장 공간 한도에 포함됩니다. 파일 크기는 피닝 완료 시 기록됩니다 — 저장 공간이 한도에 가까워도 피닝을 시작할 수 있지만, 피닝으로 인해 한도를 초과하면 이후 업로드가 차단됩니다.

피닝 ​

CID로 피닝 ​

요청 예시 ​

응답 202 Accepted ​

피닝 상태 확인 ​

응답 200 OK ​

상태 값 ​

피닝 작동 방식 ​

저장 공간 ​

피닝