S3 kompatibilita

Použijte AWS SDK k nahrávání, stahování a správě souborů na IPFS Ninja se stejným kódem, který používáte pro Amazon S3.

Endpoint

https://s3.ipfs.ninja

Přihlašovací údaje

S3 API používá váš IPFS Ninja API klíč k ověření. Váš API klíč slouží jako access key i secret key zároveň.

Jak získat přihlašovací údaje

1. Přejděte na Dashboard > API Keys
2. Klikněte na Create API key a zadejte název (např. "S3 access")
3. Okamžitě si zkopírujte celý klíč — zobrazí se pouze jednou a nelze ho později získat zpět

Váš klíč vypadá takto:

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

Mapování na AWS přihlašovací údaje

AWS parametr	Hodnota	Příklad
accessKeyId	Prvních 12 znaků vašeho API klíče	bws_628bba35
secretAccessKey	Celý API klíč (všech 36 znaků)	bws_628bba35e9e0079d9ff9c392b1b55a7b
region	Vždy us-east-1	us-east-1

WARNING

Celý API klíč se zobrazí pouze jednou při jeho vytvoření. Pokud ho ztratíte, smažte klíč a vytvořte nový na stránce API Keys.

Rychlý start

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 = Složky

S3 buckety se mapují na vaše složky v IPFS Ninja. Když nahrajete soubor do bucketu, uloží se do odpovídající složky. Když vypíšete objekty v bucketu, uvidíte soubory v dané složce.

S3 operace	Ekvivalent v IPFS Ninja
CreateBucket	Vytvoření nové složky
ListBuckets	Výpis vašich složek
DeleteBucket	Smazání složky a všech souborů v ní
PutObject do bucketu	Nahrání souboru do složky
ListObjectsV2 na bucketu	Výpis souborů ve složce

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

Složky vytvořené přes S3 API jsou stejné složky viditelné ve vašem Dashboard. Soubory můžete organizovat z S3 API, REST API nebo webového rozhraní — všechny sdílejí stejný systém složek.

INFO

Na rozdíl od Amazon S3 jsou složky IPFS Ninja ve výchozím stavu ploché. Pro vytvoření vnořených struktur použijte endpointy složek REST API s parentFolderId. Z S3 API použijte prefixy klíčů (např. images/photo.png) pro organizaci uvnitř složky.

Podporované operace

PutObject

Nahrání souboru na IPFS. Soubor je připnut, bezpečnostně prověřen a CID je vrácen v hlavičkách ETag a x-amz-meta-cid.

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

Stažení souboru podle jeho klíče (názvu souboru) nebo CID.

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

Získání metadat souboru bez stahování obsahu.

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

Odpojení (unpin) souboru z IPFS a jeho smazání z vašeho účtu.

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

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

ListObjectsV2

Výpis souborů v bucketu s volitelným filtrováním podle prefixu a stránkováním.

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

Nahrávání velkých souborů (až 5 GB) pomocí multipart upload. AWS SDK to zvládne automaticky:

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

Nebo ovládejte části ručně:

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

Příklad v Pythonu

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

Příklad v 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!")
}

Rozdíly oproti Amazon S3

Funkce	Amazon S3	IPFS Ninja S3
Model úložiště	Měnitelné objekty	Adresování obsahem (neměnné CID)
Chování při přepsání	Nahradí objekt na místě	Vytvoří nový CID, starý CID zůstává přístupný
Verzování	Podporováno	Nepodporováno (použijte CID pro verzování)
Šifrování na straně serveru	Podporováno	Nepodporováno (obsah je na IPFS)
Politiky životního cyklu	Podporovány	Nepodporovány
Politiky bucketů / ACL	Podporovány	Použijte režimy přístupu gateway
Předpodepsané URL	Podporovány	Použijte podepsané tokeny pro nahrávání
Maximální velikost objektu	5 TB	5 GB (multipart), 100 MB (jednorázový PUT)
Regiony	Multi-region	Pouze us-east-1
Hodnota ETag	MD5 hash	IPFS CID
Další hlavičky	Standardní S3	x-amz-meta-cid (IPFS CID)

Migrace z Amazon S3

Nahraďte konfiguraci vašeho S3 klienta:

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

Vaše stávající volání PutObject, GetObject, ListObjectsV2 a DeleteObject fungují beze změn.

Migrace z Filebase

Nahraďte URL endpointu:

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