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

Přejděte na Dashboard > API Keys
Klikněte na Create API key a zadejte název (např. "S3 access")
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

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: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

Buckety = Složky

S3 buckety se mapují na vaše IPFS Ninja složky. 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

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

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.

Názvy bucketů jsou globálně jedinečné

Názvy bucketů žijí v globálním jmenném prostoru napříč všemi zákazníky, stejně jako u AWS S3. To znamená:

První uživatel, který vytvoří bucket s daným názvem, si tento název globálně zabere.
Následná volání CreateBucket se stejným názvem od jakéhokoli účtu vrátí BucketAlreadyExists (409).
Pokud se pokusíte znovu vytvořit svůj vlastní bucket, dostanete BucketAlreadyOwnedByYou (409).
Váš název složky v řídicím panelu je vázán na účet a může být stále jakýkoli — pouze S3-viditelný název bucketu prochází globálním jmenným prostorem.

Pokud je název, který chcete, obsazený, zvolte konkrétněji odlišený název (myapp-photos-2026, acme-nft-metadata) — stejná konvence, jakou byste použili na Amazon S3.

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.

Pro import CAR souboru místo běžného souboru přidejte do požadavku PutObject metadata hlavičku x-amz-meta-import: car. Podrobnosti naleznete v Import CAR.

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

Stažení souboru podle jeho klíče (názvu souboru) nebo 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

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

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

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

javascript

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.

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

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

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

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

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

Příklad v Pythonu

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

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

Konfigurace CORS (přístup z prohlížečového SDK)

Pokud voláte S3 API přímo z JavaScriptu v prohlížeči (SPA, peněženková aplikace, nástroj řídicího panelu), musíte na bucketu nejprve nakonfigurovat CORS. Jinak prohlížeče blokují preflight požadavek a vaše nahrávání selžou s chybou No 'Access-Control-Allow-Origin' header is present.

Stejný tvar jako u AWS S3 — subresource PutBucketCors / GetBucketCors / DeleteBucketCors:

PutBucketCors

javascript

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

await s3.send(new PutBucketCorsCommand({
  Bucket: "my-bucket",
  CORSConfiguration: {
    CORSRules: [{
      AllowedOrigins: ["http://localhost:3000", "https://myapp.com"],
      AllowedMethods: ["GET", "HEAD", "PUT", "POST", "DELETE"],
      AllowedHeaders: ["*"],
      ExposeHeaders: ["ETag", "x-amz-meta-cid", "x-amz-request-id"],
      MaxAgeSeconds: 3600,
    }],
  },
}));

GetBucketCors

javascript

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

const { CORSRules } = await s3.send(new GetBucketCorsCommand({ Bucket: "my-bucket" }));
console.log(CORSRules);

DeleteBucketCors

javascript

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

await s3.send(new DeleteBucketCorsCommand({ Bucket: "my-bucket" }));

Limity a výchozí hodnoty

Až 5 pravidel na bucket (specifikace povoluje 100, my omezujeme na 5, aby odpověď preflightu v prohlížeči zůstala kompaktní).
Celková serializovaná konfigurace je omezena na 64 KB.
Pokud není nastavena žádná CORS konfigurace, preflight požadavky prohlížeče jsou odmítnuty — stejně jako výchozí chování AWS S3. Nastavte explicitní pravidla pro originy, ze kterých skutečně obsluhujete.

Poznámka k bezpečnosti

CORS je pohodlnostní vrstva na straně prohlížeče, nikoli bezpečnostní hranice. Každé volání S3 API stále vyžaduje platný podpis SigV4 vypočítaný z vašeho API klíče — permisivní CORS konfigurace nikomu neumožní použít váš bucket bez tohoto přihlašovacího údaje. Co CORS skutečně brání: aby nezamýšlený origin (např. zastaralá kopie vaší aplikace na dev.myapp.com) posílal podepsané požadavky z kontextu prohlížeče.

Alternativa přes řídicí panel

Stránka Soubory má v nabídce akcí každé složky položku S3 CORS. Stejné podkladové úložiště; pokud nechcete psát kód pro PutBucketCors, nakonfigurujte ho tam.

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)
Formát CID	N/A	Moderní CIDv1 (`bafy…`) pro nová nahrání; starší `Qm…` zůstává platným vstupem
Jmenný prostor bucketů	Globální (v rámci celého AWS)	Globální (napříč všemi účty IPFS Ninja) — stejná sémantika
CORS	Podporováno `PutBucketCors`	Podporováno `PutBucketCors` (limit 5 pravidel)

Migrace z Amazon S3

Nahraďte konfiguraci vašeho S3 klienta:

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

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

Migrace z Filebase

Nahraďte URL endpointu:

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 kompatibilita ​

Endpoint ​

Přihlašovací údaje ​

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

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

Rychlý start ​

Buckety = Složky ​

Názvy bucketů jsou globálně jedinečné ​

Podporované operace ​

PutObject ​

GetObject ​

HeadObject ​

DeleteObject ​

ListObjectsV2 ​

Multipart Upload ​

Příklad v Pythonu ​

Příklad v Go ​

Konfigurace CORS (přístup z prohlížečového SDK) ​

PutBucketCors ​

GetBucketCors ​

DeleteBucketCors ​

Limity a výchozí hodnoty ​

Poznámka k bezpečnosti ​

Alternativa přes řídicí panel ​

Rozdíly oproti Amazon S3 ​

Migrace z Amazon S3 ​

Migrace z Filebase ​

S3 kompatibilita

Endpoint

Přihlašovací údaje

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

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

Rychlý start

Buckety = Složky

Názvy bucketů jsou globálně jedinečné

Podporované operace

PutObject

GetObject

HeadObject

DeleteObject

ListObjectsV2

Multipart Upload

Příklad v Pythonu

Příklad v Go

Konfigurace CORS (přístup z prohlížečového SDK)

PutBucketCors

GetBucketCors

DeleteBucketCors

Limity a výchozí hodnoty

Poznámka k bezpečnosti

Alternativa přes řídicí panel

Rozdíly oproti Amazon S3

Migrace z Amazon S3

Migrace z Filebase