ピンニング

既存の IPFS コンテンツをアカウントにピン留めします。CID をピン留めすると、クラスターが IPFS ネットワークからコンテンツを取得し、永続的に利用可能な状態を維持します。

CID でピン留め

POST /pin

パラメータ	型	必須	説明
cid	string	はい	IPFS コンテンツ識別子（Qm または bafy で始まる）。
description	string	いいえ	参照用の短い説明。
metadata	object	いいえ	ピンに添付するカスタムキーバリューペア。最大 10 キー。キーは英数字またはアンダースコアで、1〜64 文字。値は文字列で、各最大 256 文字。メタデータの合計サイズは 4 KB 以下。

リクエスト例

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

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

{
  "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 が無効か、コンテンツが利用できなくなっている可能性があります。

ピン留めの仕組み

1. POST /pin で CID を送信
2. IPFS クラスターがネットワーク上でコンテンツを持つノードを検索
3. クラスターがコンテンツをダウンロードしてローカルにピン留め
4. ピン留め完了後、ファイルがファイルリストに表示され、ゲートウェイ経由でアクセス可能
5. ピン留め完了時にストレージ使用量が記録

WARNING

ピン留め時間はファイルサイズとネットワークの可用性に依存します。小さなファイルは通常数秒でピン留めされます。大きなファイルやあまりピン留めされていないコンテンツは数分かかることがあります。

ストレージ

ピン留めされたコンテンツはプランのストレージ制限に計上されます。ファイルサイズはピン留め完了時に記録されます — ストレージが制限に近くてもピン留めを開始できますが、ピン留めにより制限を超えた場合、以降のアップロードがブロックされます。