Compatibilite S3

Utilisez le SDK AWS pour telecharger, telecharger et gerer des fichiers sur IPFS Ninja avec le meme code que celui que vous utilisez pour Amazon S3.

Endpoint

https://s3.ipfs.ninja

Identifiants

L'API S3 utilise votre cle API IPFS Ninja pour l'authentification. Votre cle API sert a la fois de cle d'acces et de cle secrete.

Comment obtenir vos identifiants

1. Allez dans Tableau de bord > Cles API
2. Cliquez sur Create API key et donnez-lui un nom (par ex. "Acces S3")
3. Copiez la cle complete immediatement — elle n'est affichee qu'une seule fois et ne peut pas etre recuperee ulterieurement

Votre cle ressemble a ceci :

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

Correspondance avec les identifiants AWS

Parametre AWS	Valeur	Exemple
accessKeyId	Les 12 premiers caracteres de votre cle API	bws_628bba35
secretAccessKey	La cle API complete (les 36 caracteres)	bws_628bba35e9e0079d9ff9c392b1b55a7b
region	Toujours us-east-1	us-east-1

WARNING

La cle API complete n'est affichee qu'une seule fois lors de sa creation. Si vous la perdez, supprimez la cle et creez-en une nouvelle depuis la page Cles API.

Demarrage rapide

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 = Dossiers

Les buckets S3 correspondent a vos dossiers IPFS Ninja. Lorsque vous telechargez un fichier dans un bucket, il est stocke dans le dossier correspondant. Lorsque vous listez les objets d'un bucket, vous voyez les fichiers de ce dossier.

Operation S3	Equivalent IPFS Ninja
CreateBucket	Creer un nouveau dossier
ListBuckets	Lister vos dossiers
DeleteBucket	Supprimer un dossier et tous ses fichiers
PutObject dans un bucket	Telecharger un fichier dans le dossier
ListObjectsV2 sur un bucket	Lister les fichiers du dossier

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

Les dossiers crees via l'API S3 sont les memes que ceux visibles dans votre Tableau de bord. Vous pouvez organiser vos fichiers depuis l'API S3, l'API REST ou l'interface web — ils partagent tous le meme systeme de dossiers.

INFO

Contrairement a Amazon S3, les dossiers IPFS Ninja sont plats par defaut. Pour creer des structures imbriquees, utilisez les endpoints de dossiers de l'API REST avec parentFolderId. Depuis l'API S3, utilisez des prefixes de cle (par ex. images/photo.png) pour organiser les fichiers au sein d'un dossier.

Operations supportees

PutObject

Telechargez un fichier sur IPFS. Le fichier est epingle, analyse pour la securite, et le CID est retourne dans les en-tetes ETag et 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

Telechargez un fichier par sa cle (nom de fichier) ou son 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

Obtenez les metadonnees d'un fichier sans telecharger le contenu.

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

Desepinglez un fichier d'IPFS et supprimez-le de votre compte.

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

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

ListObjectsV2

Listez les fichiers d'un bucket avec filtrage optionnel par prefixe et pagination.

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

Telechargez de gros fichiers (jusqu'a 5 Go) en utilisant le telechargement multipart. Le SDK AWS gere cela automatiquement :

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

Ou controlez manuellement les parties :

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

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

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

Differences avec Amazon S3

Fonctionnalite	Amazon S3	IPFS Ninja S3
Modele de stockage	Objets modifiables	Adressage par contenu (CID immuables)
Comportement d'ecrasement	Remplace l'objet sur place	Cree un nouveau CID, l'ancien CID reste accessible
Versioning	Supporte	Non supporte (utilisez les CID pour le versioning)
Chiffrement cote serveur	Supporte	Non supporte (le contenu est sur IPFS)
Politiques de cycle de vie	Supportees	Non supportees
Politiques de bucket / ACL	Supportees	Utilisez les modes d'acces du gateway
URL presignees	Supportees	Utilisez les tokens de telechargement signes
Taille max d'objet	5 To	5 Go (multipart), 100 Mo (PUT unique)
Regions	Multi-region	us-east-1 uniquement
Valeur ETag	Hash MD5	IPFS CID
En-tetes supplementaires	S3 standard	x-amz-meta-cid (IPFS CID)

Migration depuis Amazon S3

Remplacez la configuration de votre client 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
 });

Vos appels PutObject, GetObject, ListObjectsV2 et DeleteObject existants fonctionnent sans modification.

Migration depuis Filebase

Remplacez l'URL du 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
 });