ピンニング

既存の 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 の背後にあるワークステーションなど — デフォルトのピン留めフローではそれを見つけられません。1 つ以上の 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> で終わる必要があります。上限：1 ピンにつき最大 5 件のヒント。

ノードのマルチアドレスを取得する

ピン留め元にしたいピア上で ipfs id を実行し、Addresses のエントリのうち /p2p/<PeerID> で終わるものをコピーしてください。クラスターが AWS からそのピアに到達できるよう、パブリックにルーティング可能なアドレス（/ip4/YOUR_PUBLIC_IP/…）または DNS ベースのアドレス（/dnsaddr/your.domain/…）を優先してください。

非常に大きなディレクトリのピン留め

POST /pin は、すでに IPFS ネットワーク上に存在するコンテンツを対象としています — クラスターはピアから DAG をブロック単位で取得するため、1,000 ファイル以上のディレクトリでは数分かかることがあります。この取得中の期間は、一部の子ファイルがまだローカルで利用可能になっておらず、それらへのゲートウェイリクエストがタイムアウトすることがあります。親の status が pinned になった時点で、すべての子ファイルはローカルで利用可能になり、ゲートウェイ経由でアクセスできます。

ファイルをローカルに持っている場合（CID だけでなく）、大規模な NFT コレクションやデータセットには CAR インポートを利用することをお勧めします — DAG 全体を 1 回のアトミックなリクエストで 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

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

ストレージ

ピン留めされたコンテンツはプランのストレージ制限に計上されます。ファイルサイズはピン留め完了時に記録されます。ストレージ制限に近づいた場合、不要なファイルを削除するか、より大きな容量のプランにアップグレードすることで空き容量を確保できます。