S3 互換性

AWS SDK を使用して、Amazon S3 と同じコードで IPFS Ninja 上のファイルをアップロード、ダウンロード、管理できます。

Endpoint

https://s3.ipfs.ninja

認証情報

S3 API は認証に IPFS Ninja の API キーを使用します。API キーが access key と secret key の両方として機能します。

認証情報の取得方法

Dashboard > API Keys にアクセス
Create API key をクリックし、名前を付けます（例: "S3 access"）
すぐにキー全体をコピーしてください — キーは一度だけ表示され、後から確認することはできません

キーは以下のような形式です:

bws_628bba35e9e0079d9ff9c392b1b55a7b
├──────────┘└──────────────────────────┘
 prefix (12 chars)    rest of key

AWS 認証情報へのマッピング

AWS パラメータ	値	例
`accessKeyId`	API キーの最初の 12 文字	`bws_628bba35`
`secretAccessKey`	API キー全体（36 文字すべて）	`bws_628bba35e9e0079d9ff9c392b1b55a7b`
`region`	常に `us-east-1`	`us-east-1`

WARNING

完全な API キーは作成時に一度だけ表示されます。紛失した場合は、キーを削除して API Keys ページから新しいキーを作成してください。

クイックスタート

javascript

import { S3Client, PutObjectCommand, GetObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: "https://s3.ipfs.ninja",
  credentials: {
    accessKeyId: "bws_628bba35",
    secretAccessKey: "bws_628bba35e9e0079d9ff9c392b1b55a7b"
  },
  region: "us-east-1",
  forcePathStyle: true
});

// Upload a file
const put = await s3.send(new PutObjectCommand({
  Bucket: "my-project",
  Key: "hello.json",
  Body: JSON.stringify({ hello: "IPFS" }),
  ContentType: "application/json"
}));

console.log("CID:", put.Metadata?.cid);
// CID: QmXnnyufdzAWL5CqZ2RnSNgPbvCc1ALT73s6epPrRnZ1Xy

Bucket = フォルダ

S3 の bucket は IPFS Ninja のフォルダに対応します。bucket にファイルをアップロードすると、対応するフォルダに保存されます。bucket 内のオブジェクトを一覧表示すると、そのフォルダ内のファイルが表示されます。

S3 操作	IPFS Ninja での対応
`CreateBucket`	新しいフォルダを作成
`ListBuckets`	フォルダの一覧を表示
`DeleteBucket`	フォルダとその中の全ファイルを削除
`PutObject` (bucket へ)	フォルダ内にファイルをアップロード
`ListObjectsV2` (bucket に対して)	フォルダ内のファイルを一覧表示

javascript

import { ListBucketsCommand, CreateBucketCommand, PutObjectCommand } from "@aws-sdk/client-s3";

// Create a bucket (= create a folder)
await s3.send(new CreateBucketCommand({ Bucket: "nft-metadata" }));

// Upload a file into the folder
await s3.send(new PutObjectCommand({
  Bucket: "nft-metadata",      // ← folder name
  Key: "token-42.json",        // ← filename within the folder
  Body: JSON.stringify({ name: "My NFT #42" })
}));

// List buckets (= list your folders)
const { Buckets } = await s3.send(new ListBucketsCommand({}));
console.log(Buckets);
// [{ Name: "nft-metadata", CreationDate: "2026-04-13T..." }]

TIP

S3 API で作成したフォルダは Dashboard に表示されるフォルダと同じです。S3 API、REST API、Web インターフェースのいずれからでもファイルを整理できます — すべて同じフォルダシステムを共有しています。

INFO

Amazon S3 とは異なり、IPFS Ninja のフォルダはデフォルトでフラットです。ネストされた構造を作成するには、REST API のフォルダ endpoint で parentFolderId を使用してください。S3 API からは、キーのプレフィックス（例: images/photo.png）を使ってフォルダ内のファイルを整理できます。

サポートされている操作

PutObject

ファイルを IPFS にアップロードします。ファイルはピン留めされ、セキュリティスキャンが実行され、CID が ETag および x-amz-meta-cid ヘッダーで返されます。

javascript

import { PutObjectCommand } from "@aws-sdk/client-s3";
import fs from "fs";

const result = await s3.send(new PutObjectCommand({
  Bucket: "my-project",
  Key: "photo.png",
  Body: fs.readFileSync("photo.png"),
  ContentType: "image/png"
}));

console.log("CID:", result.ETag);

bash

# curl equivalent
curl -X PUT "https://s3.ipfs.ninja/my-project/photo.png" \
  --data-binary @photo.png \
  -H "Content-Type: image/png" \
  --aws-sigv4 "aws:amz:us-east-1:s3" \
  --user "bws_628bba35:bws_628bba35e9e0079d9ff9c392b1b55a7b"

GetObject

キー（ファイル名）または CID でファイルをダウンロードします。

javascript

import { GetObjectCommand } from "@aws-sdk/client-s3";

const result = await s3.send(new GetObjectCommand({
  Bucket: "my-project",
  Key: "photo.png"
}));

const body = await result.Body.transformToByteArray();
console.log("Size:", body.length);
console.log("CID:", result.Metadata?.cid);

HeadObject

コンテンツをダウンロードせずにファイルのメタデータを取得します。

javascript

import { HeadObjectCommand } from "@aws-sdk/client-s3";

const head = await s3.send(new HeadObjectCommand({
  Bucket: "my-project",
  Key: "photo.png"
}));

console.log("Size:", head.ContentLength);
console.log("Type:", head.ContentType);
console.log("CID:", head.Metadata?.cid);

DeleteObject

ファイルの IPFS ピンを解除し、アカウントから削除します。

javascript

import { DeleteObjectCommand } from "@aws-sdk/client-s3";

await s3.send(new DeleteObjectCommand({
  Bucket: "my-project",
  Key: "photo.png"
}));

ListObjectsV2

オプションのプレフィックスフィルタリングとページネーションで bucket 内のファイルを一覧表示します。

javascript

import { ListObjectsV2Command } from "@aws-sdk/client-s3";

const list = await s3.send(new ListObjectsV2Command({
  Bucket: "my-project",
  Prefix: "images/",
  MaxKeys: 100
}));

for (const obj of list.Contents ?? []) {
  console.log(obj.Key, obj.Size, obj.ETag); // ETag = CID
}

Multipart Upload

マルチパートアップロードを使用して大きなファイル（最大 5 GB）をアップロードします。AWS SDK が自動的に処理します:

javascript

import { Upload } from "@aws-sdk/lib-storage";
import fs from "fs";

const upload = new Upload({
  client: s3,
  params: {
    Bucket: "my-project",
    Key: "large-dataset.tar.gz",
    Body: fs.createReadStream("large-dataset.tar.gz"),
    ContentType: "application/gzip"
  },
  partSize: 10 * 1024 * 1024, // 10 MB per part
});

upload.on("httpUploadProgress", (progress) => {
  console.log(`Uploaded ${progress.loaded} of ${progress.total} bytes`);
});

const result = await upload.done();
console.log("CID:", result.ETag);

または手動でパートを制御:

javascript

import {
  CreateMultipartUploadCommand,
  UploadPartCommand,
  CompleteMultipartUploadCommand
} from "@aws-sdk/client-s3";

// 1. Start
const { UploadId } = await s3.send(new CreateMultipartUploadCommand({
  Bucket: "my-project",
  Key: "big-file.bin"
}));

// 2. Upload parts
const part1 = await s3.send(new UploadPartCommand({
  Bucket: "my-project",
  Key: "big-file.bin",
  UploadId,
  PartNumber: 1,
  Body: chunk1
}));

// 3. Complete
const result = await s3.send(new CompleteMultipartUploadCommand({
  Bucket: "my-project",
  Key: "big-file.bin",
  UploadId,
  MultipartUpload: {
    Parts: [{ PartNumber: 1, ETag: part1.ETag }]
  }
}));

Python の例

python

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.ipfs.ninja",
    aws_access_key_id="bws_628bba35",
    aws_secret_access_key="bws_628bba35e9e0079d9ff9c392b1b55a7b",
    region_name="us-east-1"
)

# Upload
s3.put_object(
    Bucket="my-project",
    Key="data.json",
    Body=b'{"hello": "IPFS"}',
    ContentType="application/json"
)

# List files
response = s3.list_objects_v2(Bucket="my-project")
for obj in response.get("Contents", []):
    print(obj["Key"], obj["Size"])

# Download
result = s3.get_object(Bucket="my-project", Key="data.json")
print(result["Body"].read())

Go の例

package main

import (
    "context"
    "fmt"
    "strings"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/credentials"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

func main() {
    client := s3.New(s3.Options{
        BaseEndpoint: aws.String("https://s3.ipfs.ninja"),
        Region:       "us-east-1",
        Credentials:  credentials.NewStaticCredentialsProvider("bws_628bba35", "bws_628bba35e9e0...", ""),
        UsePathStyle: true,
    })

    _, err := client.PutObject(context.TODO(), &s3.PutObjectInput{
        Bucket:      aws.String("my-project"),
        Key:         aws.String("hello.txt"),
        Body:        strings.NewReader("Hello, IPFS!"),
        ContentType: aws.String("text/plain"),
    })
    if err != nil {
        panic(err)
    }
    fmt.Println("Uploaded!")
}

Amazon S3 との違い

機能	Amazon S3	IPFS Ninja S3
ストレージモデル	変更可能なオブジェクト	コンテンツアドレス（不変の CID）
上書き動作	オブジェクトをその場で置換	新しい CID を作成、古い CID は引き続きアクセス可能
Versioning	サポート	非サポート（CID を使用してバージョン管理）
サーバーサイド暗号化	サポート	非サポート（コンテンツは IPFS 上）
ライフサイクルポリシー	サポート	非サポート
Bucket ポリシー / ACL	サポート	gateway アクセスモードを使用
Presigned URL	サポート	署名付きアップロードトークンを使用
最大オブジェクトサイズ	5 TB	5 GB（multipart）、100 MB（single PUT）
リージョン	マルチリージョン	`us-east-1` のみ
`ETag` の値	MD5 ハッシュ	IPFS CID
追加ヘッダー	標準 S3	`x-amz-meta-cid`（IPFS CID）

Amazon S3 からの移行

S3 クライアントの設定を置き換えてください:

diff

 const s3 = new S3Client({
+  endpoint: "https://s3.ipfs.ninja",
   credentials: {
-    accessKeyId: "AKIA...",
-    secretAccessKey: "wJalrX..."
+    accessKeyId: "bws_628bba35",
+    secretAccessKey: "bws_628bba35e9e0..."
   },
   region: "us-east-1",
+  forcePathStyle: true
 });

既存の PutObject、GetObject、ListObjectsV2、DeleteObject の呼び出しはそのまま動作します。

Filebase からの移行

endpoint URL を置き換えてください:

diff

 const s3 = new S3Client({
-  endpoint: "https://s3.filebase.com",
+  endpoint: "https://s3.ipfs.ninja",
   credentials: {
-    accessKeyId: "FILEBASE_KEY",
-    secretAccessKey: "FILEBASE_SECRET"
+    accessKeyId: "bws_628bba35",
+    secretAccessKey: "bws_628bba35e9e0..."
   },
   region: "us-east-1",
   forcePathStyle: true
 });

S3 互換性 ​

Endpoint ​

認証情報 ​

認証情報の取得方法 ​

AWS 認証情報へのマッピング ​

クイックスタート ​

Bucket = フォルダ ​

サポートされている操作 ​

PutObject ​

GetObject ​

HeadObject ​

DeleteObject ​

ListObjectsV2 ​

Multipart Upload ​

Python の例 ​

Go の例 ​

Amazon S3 との違い ​

Amazon S3 からの移行 ​

Filebase からの移行 ​

S3 互換性

Endpoint

認証情報

認証情報の取得方法

AWS 認証情報へのマッピング

クイックスタート

Bucket = フォルダ

サポートされている操作

PutObject

GetObject

HeadObject

DeleteObject

ListObjectsV2

Multipart Upload

Python の例

Go の例

Amazon S3 との違い

Amazon S3 からの移行

Filebase からの移行