Совместимость с S3

Используйте AWS SDK для загрузки, скачивания и управления файлами на IPFS Ninja с тем же кодом, который вы используете для Amazon S3.

Endpoint

https://s3.ipfs.ninja

Учётные данные

API S3 использует ваш API-ключ IPFS Ninja для аутентификации. Ваш API-ключ служит одновременно как access key и secret key.

Как получить учётные данные

1. Перейдите в Dashboard > API Keys
2. Нажмите Create API key и задайте имя (например, "S3 access")
3. Скопируйте полный ключ сразу — он показывается только один раз и не может быть восстановлен позже

Ваш ключ выглядит так:

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

Сопоставление с учётными данными AWS

Параметр AWS	Значение	Пример
accessKeyId	Первые 12 символов вашего API-ключа	bws_628bba35
secretAccessKey	Полный API-ключ (все 36 символов)	bws_628bba35e9e0079d9ff9c392b1b55a7b
region	Всегда us-east-1	us-east-1

WARNING

Полный API-ключ показывается только один раз при создании. Если вы его потеряете, удалите ключ и создайте новый на странице API Keys.

Быстрый старт

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 = Папки

Bucket-ы S3 соответствуют вашим папкам в IPFS Ninja. Когда вы загружаете файл в bucket, он сохраняется в соответствующей папке. Когда вы перечисляете объекты в bucket-е, вы видите файлы в этой папке.

Операция S3	Эквивалент в IPFS Ninja
CreateBucket	Создать новую папку
ListBuckets	Показать ваши папки
DeleteBucket	Удалить папку и все файлы в ней
PutObject в bucket	Загрузить файл в папку
ListObjectsV2 для bucket	Показать файлы в папке

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

Папки, созданные через API S3, — это те же папки, которые видны в вашем Dashboard. Вы можете организовывать файлы через API S3, REST API или веб-интерфейс — все они используют одну и ту же систему папок.

INFO

В отличие от Amazon S3, папки IPFS Ninja по умолчанию плоские. Для создания вложенных структур используйте endpoint-ы папок REST API с parentFolderId. Через API S3 используйте префиксы ключей (например, images/photo.png) для организации внутри папки.

Поддерживаемые операции

PutObject

Загружает файл в IPFS. Файл закрепляется (pin), проходит проверку безопасности, а CID возвращается в заголовках ETag и 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

Скачивает файл по его ключу (имени файла) или 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

Получает метаданные файла без скачивания содержимого.

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

Открепляет (unpin) файл от IPFS и удаляет его из вашего аккаунта.

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

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

ListObjectsV2

Перечисляет файлы в bucket-е с опциональной фильтрацией по префиксу и пагинацией.

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 ГБ) с помощью multipart upload. AWS SDK обрабатывает это автоматически:

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

Или управляйте частями вручную:

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

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 остаётся доступным
Версионирование	Поддерживается	Не поддерживается (используйте CID для версионирования)
Шифрование на сервере	Поддерживается	Не поддерживается (контент находится в IPFS)
Политики жизненного цикла	Поддерживаются	Не поддерживаются
Политики bucket / ACL	Поддерживаются	Используйте режимы доступа шлюза
Предподписанные URL	Поддерживаются	Используйте подписанные токены загрузки
Максимальный размер объекта	5 ТБ	5 ГБ (multipart), 100 МБ (одиночный PUT)
Регионы	Мультирегион	Только us-east-1
Значение ETag	Хеш MD5	IPFS CID
Дополнительные заголовки	Стандартные S3	x-amz-meta-cid (IPFS CID)

Миграция с Amazon S3

Замените конфигурацию вашего S3-клиента:

 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

Замените URL endpoint-а:

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