S3-Kompatibilität

Verwende das AWS SDK, um Dateien auf IPFS Ninja hochzuladen, herunterzuladen und zu verwalten — mit demselben Code, den du für Amazon S3 verwendest.

Endpoint

https://s3.ipfs.ninja

Zugangsdaten

Die S3 API verwendet deinen IPFS Ninja API-Schlüssel zur Authentifizierung. Dein API-Schlüssel dient gleichzeitig als Access Key und Secret Key.

So erhältst du deine Zugangsdaten

1. Gehe zu Dashboard > API Keys
2. Klicke auf Create API key und vergib einen Namen (z.B. „S3-Zugang")
3. Kopiere den vollständigen Schlüssel sofort — er wird nur einmal angezeigt und kann später nicht mehr abgerufen werden

Dein Schlüssel sieht so aus:

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

Zuordnung zu AWS-Zugangsdaten

AWS-Parameter	Wert	Beispiel
accessKeyId	Erste 12 Zeichen deines API-Schlüssels	bws_628bba35
secretAccessKey	Der vollständige API-Schlüssel (alle 36 Zeichen)	bws_628bba35e9e0079d9ff9c392b1b55a7b
region	Immer us-east-1	us-east-1

WARNING

Der vollständige API-Schlüssel wird nur einmal angezeigt, wenn du ihn erstellst. Falls du ihn verlierst, lösche den Schlüssel und erstelle einen neuen auf der API Keys-Seite.

Schnellstart

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

Buckets = Ordner

S3-Buckets entsprechen deinen IPFS Ninja-Ordnern. Wenn du eine Datei in einen Bucket hochlädst, wird sie im entsprechenden Ordner gespeichert. Wenn du Objekte in einem Bucket auflistest, siehst du die Dateien in diesem Ordner.

S3-Operation	IPFS Ninja-Entsprechung
CreateBucket	Neuen Ordner erstellen
ListBuckets	Deine Ordner auflisten
DeleteBucket	Ordner und alle Dateien darin löschen
PutObject in Bucket	Datei in den Ordner hochladen
ListObjectsV2 auf Bucket	Dateien im Ordner auflisten

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

Ordner, die über die S3 API erstellt werden, sind dieselben Ordner, die in deinem Dashboard sichtbar sind. Du kannst Dateien über die S3 API, die REST API oder die Weboberfläche organisieren — alle nutzen dasselbe Ordnersystem.

INFO

Anders als bei Amazon S3 sind IPFS Ninja-Ordner standardmäßig flach. Um verschachtelte Strukturen zu erstellen, verwende die Ordner-Endpoints der REST API mit parentFolderId. Über die S3 API kannst du Schlüssel-Präfixe (z.B. images/photo.png) verwenden, um innerhalb eines Ordners zu organisieren.

Unterstützte Operationen

PutObject

Lade eine Datei auf IPFS hoch. Die Datei wird gepinnt, sicherheitsgeprüft, und der CID wird in den Headern ETag und x-amz-meta-cid zurückgegeben.

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);

# 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

Lade eine Datei anhand ihres Schlüssels (Dateiname) oder CID herunter.

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

Rufe Datei-Metadaten ab, ohne den Inhalt herunterzuladen.

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

Entferne das Pinning einer Datei von IPFS und lösche sie aus deinem Konto.

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

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

ListObjectsV2

Liste Dateien in einem Bucket auf, mit optionaler Präfix-Filterung und Paginierung.

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

Lade große Dateien (bis zu 5 GB) mit Multipart Upload hoch. Das AWS SDK erledigt dies automatisch:

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);

Oder steuere die Teile manuell:

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-Beispiel

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-Beispiel

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!")
}

Unterschiede zu Amazon S3

Merkmal	Amazon S3	IPFS Ninja S3
Speichermodell	Veränderbare Objekte	Inhaltsadressiert (unveränderliche CIDs)
Überschreibverhalten	Ersetzt Objekt direkt	Erstellt neuen CID, alter CID bleibt zugänglich
Versionierung	Unterstützt	Nicht unterstützt (verwende CIDs zur Versionierung)
Serverseitige Verschlüsselung	Unterstützt	Nicht unterstützt (Inhalt liegt auf IPFS)
Lifecycle-Richtlinien	Unterstützt	Nicht unterstützt
Bucket-Richtlinien / ACLs	Unterstützt	Verwende Gateway-Zugriffsmodi
Vorsignierte URLs	Unterstützt	Verwende signierte Upload-Tokens
Maximale Objektgröße	5 TB	5 GB (Multipart), 100 MB (einzelner PUT)
Regionen	Multi-Region	Nur us-east-1
ETag-Wert	MD5-Hash	IPFS CID
Zusätzliche Header	Standard S3	x-amz-meta-cid (IPFS CID)

Migration von Amazon S3

Ersetze deine S3-Client-Konfiguration:

 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
 });

Deine bestehenden Aufrufe von PutObject, GetObject, ListObjectsV2 und DeleteObject funktionieren unverändert weiter.

Migration von Filebase

Ersetze die Endpoint-URL:

 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
 });