ファイル

IPFS 上のファイルをアップロード、一覧表示、取得します。

ファイルのアップロード

POST /upload/new

任意のファイルを IPFS にアップロードします。ファイルはピン留めされ、永続的な CID が返されます。

リクエストボディ

パラメータ	型	必須	説明
content	string | object	はい	JSON オブジェクト/配列、または base64 エンコードされたファイルデータ（画像、PDF、HTML、または任意のファイルタイプ）。CAR インポートの場合は、base64 エンコードされた CAR ファイル。
car	boolean	いいえ	CAR ファイル（DAG インポート）をインポートする場合は true に設定します。正確な CID を保持します。
description	string	いいえ	アップロードされたコンテンツの短い説明。
metadata	object	いいえ	ファイルに添付するカスタムキーバリューペア。最大 10 キー。キーは英数字またはアンダースコアで、1〜64 文字。値は文字列で、各最大 256 文字。メタデータの合計サイズは 4 KB 以下。

リクエスト例

curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": { "name": "example", "value": 42 },
    "description": "Test upload",
    "metadata": {
      "project": "my-app",
      "environment": "production"
    }
  }'

画像のアップロード（base64）

const fs = require("fs");
const image = fs.readFileSync("photo.png").toString("base64");

const response = await fetch("https://api.ipfs.ninja/upload/new", {
  method: "POST",
  headers: {
    "X-Api-Key": "bws_your_api_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    content: image,
    description: "Profile photo"
  })
});

レスポンス 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "sizeMB": 0.042,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

デフォルトで CIDv1

新規アップロードは、IPIP-0499 unixfs-v1-2025 プロファイル（1 MiB チャンク、raw leaves 使用）に従い、最新の CIDv1（小さな単一ブロックのコンテンツには bafk…、より大きなファイルやディレクトリには bafy…）を返します。以前のアップロードによるレガシーな Qm… CID も引き続き完全に解決可能で、すべてのエンドポイントで問題なく動作します。

ダッシュボードでの代替方法

ダッシュボードの /upload ページでは、ファイル、フォルダ（ブラウザ内で UnixFS ディレクトリにパックされます）、.car アーカイブをドラッグ＆ドロップでアップロードできます。いずれもこの同じエンドポイントを経由します。CAR 経路の詳細については CAR Import を参照してください。

ファイル名の変更

PUT /files/:cid/name

ファイルに表示される名前を更新します。CID はコンテンツのハッシュ値であるため変更されません。変更されるのは、ファイル一覧に表示されるラベルのみです。

リクエストボディ

パラメータ	型	必須	説明
name	string	はい	新しい表示名。1〜200 文字。パス区切り文字（/、\）を含めることはできません。空白のみの名前は拒否されます。

リクエスト例

curl -X PUT https://api.ipfs.ninja/files/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/name \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Season 1 promo art" }'

レスポンス 200 OK

{
  "success": true,
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "name": "Season 1 promo art"
}

ダッシュボード

ファイルページの各行のアクションメニュー（三点ボタン）に 名前の変更 項目があります。コードを書かずに同じ効果が得られます。

ファイルの一覧

GET /upload/list

時間範囲内のアップロード済み IPFS ファイルのリストを取得します。

クエリパラメータ

パラメータ	型	必須	説明
from	number	はい	時間範囲の開始、Unix タイムスタンプ（ミリ秒）。
to	number	はい	時間範囲の終了、Unix タイムスタンプ（ミリ秒）。

リクエスト例

curl "https://api.ipfs.ninja/upload/list?from=1704067200000&to=1735689600000" \
  -H "X-Api-Key: bws_your_api_key_here"

レスポンス 200 OK

[
  {
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "fileName": "Test upload",
    "fileType": "json",
    "sizeMB": 0.001,
    "createdAt": 1711036800000,
    "metadata": {
      "project": "my-app",
      "environment": "production"
    },
    "uris": {
      "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
      "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
    }
  }
]

ファイルの取得

GET /file/:cid

CID で特定のアップロード済みファイルのメタデータを取得します。

パスパラメータ

パラメータ	型	必須	説明
cid	string	はい	ファイルの IPFS コンテンツ識別子。

リクエスト例

curl https://api.ipfs.ninja/file/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi \
  -H "X-Api-Key: bws_your_api_key_here"

レスポンス 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "fileName": "Test upload",
  "fileType": "json",
  "sizeMB": 0.001,
  "createdAt": 1711036800000,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}