FAQ

Questions fréquemment posées sur IPFS Ninja.

Général

Qu'est-ce qu'IPFS Ninja ?

IPFS Ninja est un service géré d'épinglage IPFS. Vous téléversez n'importe quel fichier via une API REST simple, ou épinglez des CID existants du réseau IPFS. Chaque fichier reçoit un identifiant de contenu (CID) permanent et est accessible via notre gateway à ipfs.ninja/ipfs/<CID>.

ipfs.ninja/ipfs/<CID> sert-il n'importe quel CID du réseau IPFS ?

Non. Le gateway apex ne sert que les CID qui ont été téléversés ou épinglés par un utilisateur d'IPFS Ninja. Les requêtes pour des CID inconnus renvoient HTTP 410 Gone avec un pointeur vers des gateways IPFS publics (ipfs.io, dweb.link). Pour servir un CID tiers via notre gateway, faites d'abord POST /pin sur votre compte — une fois épinglé, le CID devient accessible à la fois via le gateway apex et via l'URL de votre gateway dédié.

Quelle est la différence entre le gateway apex et le gateway dédié ?

Aspect	Apex ipfs.ninja/ipfs/<CID>	Dédié <slug>.gw.ipfs.ninja/ipfs/<CID>
Portée	Partagée entre tous les utilisateurs	Vos CID uniquement
Authentification	Aucune	Token optionnel / liste blanche d'IP / liste blanche d'origines
SLA	Meilleur effort	SLA complet
Recommandé pour	Liens occasionnels	Intégration en production (NFT, vidéo, sites web)
Limites de débit	Partagées par IP + par CID	Par plan, configurable

Les deux servent un contenu identique. Pour le trafic de production, utilisez le gateway dédié.

Quels types de fichiers sont pris en charge ?

Tous les types de fichiers sont pris en charge. Les objets et tableaux JSON peuvent être envoyés directement. Tous les autres fichiers (images, PDF, HTML, vidéo, audio, binaires) sont envoyés sous forme de contenu encodé en base64.

Y a-t-il une limite de taille de fichier ?

Les téléversements individuels sont limités par la capacité de stockage de votre plan. Il n'y a pas de limite de taille par fichier au-delà de votre stockage disponible.

Puis-je épingler du contenu qui existe déjà sur IPFS ?

Oui. Utilisez POST /pin avec n'importe quel CID valide. Notre cluster récupérera le contenu depuis le réseau IPFS et l'épinglera sur votre compte. Consultez la documentation de l'API d'épinglage pour plus de détails.

Combien de temps prend l'épinglage ?

Cela dépend de la taille du fichier et du nombre de nœuds IPFS possédant le contenu. Les petits fichiers bien distribués s'épinglent en quelques secondes. Le contenu volumineux ou rarement épinglé peut prendre quelques minutes. L'endpoint d'épinglage répond immédiatement avec le statut pinning — interrogez GET /pin/:cid pour vérifier la progression.

Que se passe-t-il si un CID ne peut pas être trouvé ?

Le statut passe à failed. Cela signifie que le CID est invalide ou que le contenu n'est plus disponible sur aucun nœud IPFS accessible.

Les données téléversées sur IPFS sont-elles publiques ?

Oui. Tout contenu épinglé sur IPFS est accessible publiquement via son CID depuis n'importe quel gateway IPFS. Si vous avez besoin d'un accès privé, utilisez un gateway dédié avec le mode token requis — cela restreint l'accès via votre gateway, bien que le contenu reste disponible sur le réseau IPFS plus large.

Pourquoi mes nouveaux CID sont-ils passés de Qm... à bafy... ?

Les nouveaux téléversements et épinglages renvoient un CIDv1 moderne (bafk… pour le contenu à bloc unique de petite taille, bafy… pour les fichiers volumineux et les répertoires) selon le profil IPIP-0499 unixfs-v1-2025 : encodage CIDv1 en base32, chunks de 1 MiB, feuilles brutes. Cela correspond à ce que produisent les outils modernes (Helia, Kubo récent, ipfs-car) pour le même contenu, de sorte qu'un fichier téléversé chez nous obtient le même CID que calculerait n'importe quel client moderne pour les mêmes octets.

Les CID Qm… hérités des téléversements précédents restent entièrement résolubles — le gateway, POST /pin, GET /file, IPNS, et tous les autres endpoints acceptent les deux formats indéfiniment. Rien de ce que vous avez déjà ne cesse de fonctionner.

Comment épingler du contenu qui vit sur un nœud privé / non-DHT ?

POST /pin accepte des multiaddresses[] optionnelles (jusqu'à 5). Si elles sont fournies, notre cluster exécute ipfs swarm connect <multiaddr> pour chaque indice avant l'exécution de l'épinglage, afin que le contenu sur des pairs qui ne s'annoncent pas via le DHT public (nœuds privés, environnements de staging, machines locales sur VPN) soit accessible. Consultez le guide Épingler depuis un nœud IPFS privé.

Mes fichiers resteront-ils sur IPFS si j'annule mon compte ?

Nous désépinglons vos fichiers de nos nœuds lorsque vous annulez. Si d'autres nœuds IPFS ont mis votre contenu en cache, il peut rester accessible. Cependant, sans épinglage actif, les fichiers finiront par être supprimés par le ramasse-miettes du réseau.

Authentification et API

Comment authentifier les requêtes API ?

Passez votre clé API via l'en-tête X-Api-Key. Générez des clés depuis la page Clés API de votre tableau de bord.

Y a-t-il des limites de débit sur l'API ?

Non. IPFS Ninja n'impose aucune limite de débit sur les requêtes API. Vous pouvez effectuer autant de requêtes que nécessaire sur n'importe quel plan.

Les clés API expirent-elles ?

Non. Les clés API restent valides jusqu'à ce que vous les supprimiez. Vous pouvez créer plusieurs clés et les révoquer individuellement.

Quelle est la différence entre les clés API et les tokens de gateway ?

Les clés API (bws_) ont un accès complet — téléversement, suppression, listage des fichiers. Les tokens de gateway (gwt_) sont en lecture seule et ne peuvent accéder aux fichiers que via votre gateway dédié. Les tokens de gateway peuvent sans risque être intégrés dans des applications frontend.

Gateways dédiés

Qu'est-ce qu'un gateway dédié ?

Un gateway IPFS privé sur votre propre sous-domaine (par ex. abc123.gw.ipfs.ninja) qui ne sert que les fichiers épinglés sur votre compte. Contrairement au gateway public, il ne résoudra pas les CID d'autres utilisateurs.

Quels plans incluent un gateway dédié ?

Les gateways dédiés sont disponibles sur tous les plans payants (Bodhi 5 $/mois, Karma 19 $/mois, Nirvana 59 $/mois). Le quota de bande passante mensuel de chaque plan couvre le trafic à la fois du gateway apex et du gateway dédié. Voir « Y a-t-il des frais de bande passante ? » ci-dessous pour les quotas par plan.

Puis-je restreindre qui accède à mon gateway ?

Oui. Vous pouvez activer le mode token requis (exige un token gwt_ sur chaque requête) et/ou définir une liste blanche d'IP (jusqu'à 100 adresses).

Puis-je restreindre mon gateway par origine/domaine ?

Oui. Configurez allowedOrigins dans vos paramètres de gateway avec une liste d'origines HTTPS. Seules les requêtes de navigateur provenant de ces origines seront autorisées. Les requêtes non-navigateur (sans en-tête Origin) passent sans restriction. Une liste vide autorise toutes les origines.

Qu'est-ce que les tokens de téléversement signés ?

Les tokens de téléversement signés sont des identifiants à durée limitée pour les téléversements côté client. Vous les générez sur votre serveur avec POST /upload/signed-url et les transmettez aux navigateurs ou applications mobiles. Le client s'authentifie avec Authorization: Signed <token> au lieu d'exposer votre clé API. Chaque token suit son utilisation et expire automatiquement. Consultez la documentation des tokens signés pour plus de détails.

Puis-je optimiser les images servies depuis IPFS ?

Oui. Utilisez GET /image/:cid avec des paramètres de requête tels que w, h, format et quality pour redimensionner, convertir et compresser des images à la volée. Les réponses sont mises en cache en fonction du CID adressé par contenu. Cela fonctionne sur tous les plans. Consultez Optimisation d'images.

Puis-je attacher des métadonnées aux fichiers ?

Oui. Incluez un objet metadata avec jusqu'à 10 paires clé-valeur lors du téléversement via POST /upload/new ou de l'épinglage via POST /pin. Les métadonnées sont renvoyées dans les listages de fichiers et l'endpoint de détail du fichier. Consultez la documentation des Fichiers et de l'Épinglage.

Facturation et plans

Existe-t-il un plan gratuit ?

Oui. Le plan Dharma est gratuit à vie — 1 Go de stockage, requêtes API illimitées, aucune carte de crédit requise.

Y a-t-il des frais de bande passante ?

Aucuns frais de bande passante mesurée sur aucun plan. Chaque plan inclut un quota de bande passante mensuel du gateway qui constitue un plafond strict — votre contenu cesse d'être servi sur les gateways apex et dédié une fois le quota atteint, et reprend le 1er du mois suivant ou après une mise à niveau :

Plan	Bande passante mensuelle
Dharma	2 Go
Bodhi	20 Go
Karma	100 Go
Nirvana	500 Go

Vous recevrez des e-mails d'avertissement à 80 % et 100 % de votre quota.

Le stockage se réinitialise-t-il ?

Le stockage ne se réinitialise pas. Votre plan inclut une capacité de stockage totale (Dharma 1 Go / Bodhi 10 Go / Karma 100 Go / Nirvana 1 To). Pour libérer de l'espace, supprimez les fichiers dont vous n'avez plus besoin. La mise à niveau de votre plan augmente votre capacité totale.

Puis-je annuler à tout moment ?

Oui. Annulez votre abonnement via le portail de facturation — sans engagement. Votre compte revient au niveau gratuit, et les fichiers déjà épinglés restent accessibles.

Que se passe-t-il avec mes fichiers si je rétrograde ?

Vos fichiers restent épinglés sur IPFS, mais vous ne pourrez plus en téléverser si votre utilisation actuelle dépasse la limite de stockage du nouveau plan. Supprimez des fichiers pour repasser sous la limite.

Sécurité

Mes données sont-elles chiffrées ?

Toutes les données sont chiffrées en transit via TLS/HTTPS. L'authentification utilise des tokens JWT (Cognito) et des clés API stockées de manière sécurisée. Le contenu des fichiers sur IPFS n'est pas chiffré au repos — IPFS est un réseau public par conception.

Est-il sûr d'utiliser des clés API dans mon code côté serveur ?

Oui. Les clés API sont conçues pour une utilisation côté serveur. Ne les exposez jamais dans du code côté client. Pour l'accès aux fichiers côté client, utilisez des tokens de gateway (gwt_), qui sont en lecture seule.

Support

Comment obtenir de l'aide ?

Envoyez un e-mail à info@ipfs.ninja ou consultez la documentation de la Référence de l'API.

Y a-t-il un SLA ?

Nous visons une haute disponibilité mais ne proposons pas de SLA formel pour le moment. Le service est fourni « tel quel ».