> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Blob Storage : stockage d'objets compatible S3 avec CDN

> Stockage d'objets compatible S3 avec CDN mondial, fichiers privés, liens temporaires et de partage, sans frais de transfert. Inclus dans tous les plans.

![Aperçu du service Square Cloud Blob Storage](https://squarecloud.app/banners/fr/blob.png)

## Pourquoi choisir Square Cloud Blob Storage ?

En tant que **plus grande plateforme d'hébergement de bots d'Amérique latine**, à laquelle font confiance **80 des 100 plus grands serveurs Discord brésiliens**, nous avons conçu Blob Storage pour résoudre un problème que notre propre communauté rencontrait sans cesse : **le CDN de Discord n'a jamais été conçu pour servir de backend de stockage**, et les liens se cassent, expirent ou sont soumis à des limites de débit. Blob Storage remplace cela par un stockage d'objets conçu pour la durabilité.

L'architecture est volontairement simple : **un stockage d'objets compatible S3 est la source de vérité** pour vos fichiers, et un **CDN global** les distribue depuis la périphérie. Vous bénéficiez de la **durabilité à 11 neuf** d'une conception S3 avec la latence de lecture d'un cache global, et chaque plan payant inclut un quota de stockage, avec le [dépassement](#dépassement) quand vous avez besoin de plus.

## Fonctionnalités clés

> [card] Aucun frais de transfert
>
> **Zéro frais d'ingress et d'egress.** Envoyez et servez autant que nécessaire : vous payez pour le stockage, jamais pour la bande passante.

> [card] CDN global
>
> Les fichiers publics sont servis depuis un **CDN global**, en périphérie, au plus près de vos utilisateurs, où qu'ils soient.

> [card] Fichiers privés
>
> Stockez des fichiers **sans URL publique** et distribuez-les via des [liens temporaires ou des liens de partage](https://docs.squarecloud.app/fr/blob-reference/links-and-sharing.md). Passez n'importe quel fichier de public à privé, et inversement, à tout moment.

> [card] Liens de partage
>
> Des liens qui **expirent**, peuvent être **révoqués**, limitent le **nombre de téléchargements** et, sur Pro et Enterprise, demandent un **mot de passe**.

> [card] Compatible S3
>
> Utilisez **aws-cli, boto3, rclone** ou n'importe quel SDK AWS via la [passerelle S3](https://docs.squarecloud.app/fr/blob-reference/s3-compatibility.md), avec des identifiants dérivés de votre clé API.

> [card] Envois depuis le navigateur
>
> Votre serveur génère un [jeton d'envoi](https://docs.squarecloud.app/fr/blob-reference/endpoint/upload-tokens.md) et le **navigateur envoie directement**, sans jamais voir votre clé API.

> [card] Règles par préfixe
>
> Définissez des valeurs par défaut (visibilité, expiration, cache), des limites (taille, types de fichiers) et une **suppression automatique après N jours** pour tout ce qui se trouve sous un préfixe, avec les [paramètres du compte](https://docs.squarecloud.app/fr/blob-reference/endpoint/settings-put.md).

> [card] Opérations côté serveur
>
> [Copiez, déplacez et renommez](https://docs.squarecloud.app/fr/blob-reference/endpoint/copy.md) des fichiers sans les télécharger, et [modifiez les en-têtes](https://docs.squarecloud.app/fr/blob-reference/endpoint/update.md) (cache, disposition, métadonnées) sur place.

## Comment ça marche

Les fichiers arrivent par l'API REST, par le navigateur (avec un jeton d'envoi) ou par n'importe quel outil S3. Chaque fichier est soit **public**, soit **privé**, et ressort par une URL publique, un lien temporaire ou un lien de partage.

Les fichiers entrent dans Blob Storage depuis votre app, le navigateur ou des outils S3, et en sortent par une URL publique, un lien temporaire ou un lien de partage.

Les fichiers entrent dans Blob Storage depuis votre app, le navigateur ou des outils S3, et en sortent par une URL publique, un lien temporaire ou un lien de partage.

## Stockage et tarification

Le stockage est inclus dans votre plan, et il n'y a aucun frais de transfert : les téléchargements sont toujours gratuits, et vous ne payez le stockage au-delà du quota inclus que si vous activez le [dépassement](#dépassement).

### Stockage inclus

Chaque plan payant, de Hobby à Enterprise, inclut un quota de stockage sans coût supplémentaire, affiché sur la page [Utilisation](https://squarecloud.app/fr/account/usage) du tableau de bord. Le quota et le dépassement sont mesurés en gigaoctets décimaux : 1 Go = 1 000 000 000 octets. Blob Storage nécessite un plan actif : il n'existe pas de plan gratuit.

> [!NOTE]
>
> **Quotas précédents.** Si votre plan était actif lorsqu'un changement du quota inclus a été annoncé, vous conservez votre quota précédent pendant **90 jours après l'annonce**, ou jusqu'à la fin de la période que vous aviez déjà payée, si elle se termine plus tard. Les plans à vie conservent le quota précédent. Tant qu'il s'applique, c'est votre quota inclus. La page [Utilisation](https://squarecloud.app/fr/account/usage) du tableau de bord indique la date exacte pour votre compte, et [Statistiques du compte](https://docs.squarecloud.app/fr/blob-reference/endpoint/stats.md) la renvoie dans `plan.legacy`.

### Atteindre votre quota

Avec le dépassement désactivé, **les envois qui dépasseraient le quota inclus sont refusés** avec `STORAGE_QUOTA_EXCEEDED` jusqu'à ce que vous libériez de l'espace ou activiez le dépassement. Rien de ce qui est déjà stocké n'est supprimé, et tout continue d'être servi normalement.

### Dépassement

Le dépassement vous permet de stocker plus que le quota inclus et de ne payer que ce qui le dépasse. Il est **facultatif et désactivé par défaut**.

* **Activez-le** depuis la page [Utilisation](https://squarecloud.app/fr/account/usage) du tableau de bord, connecté à votre compte. Une clé API ne peut pas l'activer.
* **Fixez un plafond** en Go entiers au-delà du quota inclus : jusqu'à **1 To** en Standard, jusqu'à **100 To** en Pro et sans limite en Enterprise. Le plan Hobby n'a pas de dépassement. Les envois peuvent alors atteindre le quota inclus plus le plafond.

> [card] Stockage au-delà du quota inclus
>
> **R\$ 0,20 par Go-mois** au-delà du quota inclus, et **R\$ 0,15** pour chaque Go-mois au-delà du premier To de dépassement, appliqué automatiquement. Les téléchargements restent gratuits.

* **Moyenne quotidienne :** chaque jour (UTC) compte ce que vous stockez au-delà du quota inclus, dans la limite de votre plafond, et chaque période de facturation est facturée sur la moyenne de ses jours, arrondie au Go entier supérieur.
* **Facturé avec votre plan :** le dépassement est facturé sur le cycle de votre plan, sur la même facture que le renouvellement. Quand aucun renouvellement ne peut l'inclure, il passe sur une facture de consommation séparée : tous les 30 jours pour les plans de plus d'un mois, une fois par mois pour les plans à vie, et à la fin d'un plan non renouvelé. La facture de consommation est débitée sur votre carte enregistrée ou payée par PIX.
* **Minimum de R\$ 10** sur la consommation de chaque facture, en additionnant Blob Storage et le [paiement à l'usage de l'AI Gateway](https://docs.squarecloud.app/fr/api-reference/ai-gateway.md). Une période sans consommation ne coûte rien.
* **7 jours pour payer :** si une facture de consommation reste impayée après 7 jours, le dépassement est suspendu et les envois s'arrêtent au quota inclus jusqu'au paiement (le paiement à l'usage de l'AI Gateway est aussi suspendu).
* **Le désactiver :** c'est refusé tant que vous stockez plus que le quota inclus, supprimez donc d'abord des fichiers. Un plafond inférieur à ce que vous stockez déjà au-delà du quota est également refusé. Ce que vous avez déjà utilisé reste facturé.

> [!NOTE]
>
> [Statistiques du compte](https://docs.squarecloud.app/fr/blob-reference/endpoint/stats.md) indique votre utilisation, le stockage quotidien du mois en cours, vos réglages de dépassement et une estimation du dépassement du mois. La page [Utilisation](https://squarecloud.app/fr/account/usage) du tableau de bord affiche la consommation du cycle en cours et sa date de clôture.

> [!NOTE]
>
> Blob Storage est **uniquement disponible** pour les abonnés disposant d'un **plan actif**. Un compte sans plan actif peut toujours lister, télécharger, supprimer et rendre privés ses fichiers. Lorsqu'un plan expire ou est annulé, les fichiers stockés entrent dans une **file de suppression** : renouvelez donc dès que possible, les fichiers déjà supprimés ne peuvent pas être récupérés.

### Fonctionnalités par plan

Chaque plan a accès à l'API complète : fichiers publics et privés, liens temporaires, liens de partage, passerelle S3, jetons d'envoi et règles par préfixe. Quelques options dépendent du plan, et toutes répondent avec le même code `403 UPGRADE_REQUIRED`, accompagné d'un `message` indiquant le plan (ou la limite) qui s'applique :

| Fonctionnalité | Disponible sur |
| - | - |
| Règles par préfixe | **5** sur Hobby et Standard, **10** sur Pro, **20** sur Enterprise |
| Envois sans la limite de 1 par seconde | Pro et Enterprise |
| Métadonnées personnalisées (jusqu'à 5 clés, 512 octets) | Pro et Enterprise |
| Liens de partage protégés par mot de passe | Pro et Enterprise |
| Expirations et suppression automatique en dessous de 7 jours (jusqu'à 1 heure) | Enterprise |
| Fichiers servis sans cache en périphérie (`no-cache`) | Enterprise |
| Cache de moins d'un jour (`max-age` inférieur à 86400) | Enterprise |

## Fichiers publics et privés

Chaque objet est soit **public**, soit **privé**, et son `id` l'indique : `pub/<user_id>/<path>` ou `prv/<user_id>/<path>`.

* Les **fichiers publics** ont une URL CDN permanente : `https://blob.squarecloud.dev/pub/<user_id>/<path>`.
* Les **fichiers privés** n'ont pas d'URL publique (`url` vaut `null`). Vous les lisez via un [lien temporaire](https://docs.squarecloud.app/fr/blob-reference/endpoint/download.md), un [lien de partage](https://docs.squarecloud.app/fr/blob-reference/endpoint/shares-create.md), l'API ou la [passerelle S3](https://docs.squarecloud.app/fr/blob-reference/s3-compatibility.md).

Lisez [Liens et partage](https://docs.squarecloud.app/fr/blob-reference/links-and-sharing.md) pour savoir comment se comportent la publication, la dépublication et les différents types de liens.

## Types de fichiers pris en charge

Pratiquement **n'importe quel type de fichier est accepté**, y compris les formats sans type MIME enregistré : `.bam`, `.vcf`, `.fasta`, `.fastq`, `.parquet`, `.h5`, `.npy` et ainsi de suite. L'extension stockée provient du **nom de fichier que vous envoyez**, et les suffixes de compression composés sont préservés (`reads.fastq.gz` reste `.fastq.gz`).

La seule exception est une liste noire d'**exécutables et d'installateurs** (`.exe`, `.msi`, `.bat`, `.apk` et similaires), refusés avec `BLOCKED_FILE_TYPE`.

> [!WARNING]
>
> **La diffusion est sûre par conception** : le `Content-Type` servi est dérivé côté serveur, jamais du client. Les formats inconnus et les types rendus par le navigateur (`.html`, `.svg`, `.xml`) sont toujours servis en tant que **téléchargements** (`application/octet-stream`), afin que les envois malveillants ne s'affichent jamais dans le navigateur.

## Performances et durabilité

Blob Storage a fait l'objet de **benchmarks approfondis** avant son lancement. Principaux résultats :

* **Latence** : les fichiers sont reçus en **\~11 ms** en moyenne.
* **Durabilité** : conçue pour **99,999999999 % (11 neuf)**.
* **Distribution en périphérie** : les fichiers publics sont mis en cache en périphérie du CDN, de sorte que les lectures répétées ne repassent jamais par l'origine.
* **Health check** : `https://blob.squarecloud.dev/pub/status` répond `OK` et n'est jamais mis en cache, vous pouvez donc y brancher votre monitoring.

![Benchmark de latence globale de Blob Storage](https://cdn.squarecloud.app/docs/services/blob-global-latency-test.webp)

> [!NOTE]
>
> **Remarque** : les résultats des benchmarks proviennent de tests contrôlés et varient selon la **localisation géographique**, la **taille des fichiers**, la **qualité du réseau** et les **pics d'utilisation**. Pour obtenir les chiffres les plus précis, testez depuis votre environnement de production.

> [!WARNING]
>
> **Limitations régionales** : les utilisateurs en **Afrique** et dans certaines **régions d'Asie** peuvent constater des latences plus élevées en raison de la **distance physique par rapport aux centres de données** et de l'**infrastructure réseau locale**.

## Comment héberger vos fichiers

**1. Obtenir une clé API**

Créez une clé API avec le scope `blob:write` dans les [paramètres de votre compte](https://squarecloud.app/fr/account/security). Voir [Authentification](https://docs.squarecloud.app/fr/blob-reference/authentication.md).

**2. Envoyer**

Envoyez les fichiers jusqu'à **100 Mo** vers [Object Post](https://docs.squarecloud.app/fr/blob-reference/endpoint/post.md). Les fichiers plus volumineux, jusqu'à **10 GiB**, passent par le [flux d'envoi chunked](https://docs.squarecloud.app/fr/blob-reference/endpoint/chunked-init.md). Vous préférez les outils S3 ? Pointez-les plutôt vers la [passerelle S3](https://docs.squarecloud.app/fr/blob-reference/s3-compatibility.md).

**3. Servir**

Utilisez l'`url` de la réponse pour les fichiers publics, ou créez un [lien temporaire](https://docs.squarecloud.app/fr/blob-reference/endpoint/download.md) ou un [lien de partage](https://docs.squarecloud.app/fr/blob-reference/endpoint/shares-create.md) pour les fichiers privés.

Pour un premier envoi et un premier téléchargement avec curl, suivez le [guide de démarrage rapide de l'API Blob Storage](https://docs.squarecloud.app/fr/blob-reference/quickstart.md).

> [!TIP]
>
> Vous utilisez JavaScript ? Le [SDK Blob](https://docs.squarecloud.app/fr/sdks/blob/client.md) (`@squarecloud/blob`) gère pour vous les envois simples et multipart, les liens, les partages, les règles et la passerelle S3, sur Node.js et dans le navigateur.

## Questions fréquentes

> [accordion] De quel plan ai-je besoin pour Blob Storage ?
>
> Blob Storage est disponible sur **tous les plans** payants, à partir de Hobby. Chaque plan inclut un quota de stockage, et vous pouvez activer le [dépassement](#dépassement) pour stocker plus. Consultez [Plans et tarifs](https://docs.squarecloud.app/fr/platform/plans.md) pour la comparaison complète.

> [accordion] Que se passe-t-il lorsque j'atteins mon quota de stockage inclus ?
>
> Avec le dépassement désactivé, les envois qui dépasseraient le quota sont refusés avec `STORAGE_QUOTA_EXCEEDED` jusqu'à ce que vous supprimiez des objets ou activiez le [dépassement](#dépassement). Rien de ce qui est déjà stocké n'est supprimé, et tout continue d'être servi normalement. [Statistiques du compte](https://docs.squarecloud.app/fr/blob-reference/endpoint/stats.md) affiche votre utilisation et l'estimation du mois à tout moment.

> [accordion] Lien temporaire ou lien de partage ?
>
> Un [lien temporaire](https://docs.squarecloud.app/fr/blob-reference/endpoint/download.md) est valable **jusqu'à 24 heures** et **ne peut pas être révoqué** : utilisez-le pour remettre un fichier à un utilisateur sur le moment. Un [lien de partage](https://docs.squarecloud.app/fr/blob-reference/endpoint/shares-create.md) dure **jusqu'à 30 jours**, **peut être révoqué**, peut limiter le nombre de téléchargements et, sur Pro et Enterprise, peut demander un mot de passe. Voir [Liens et partage](https://docs.squarecloud.app/fr/blob-reference/links-and-sharing.md).

> [accordion] Puis-je utiliser des outils S3 ?
>
> Oui. La [passerelle S3](https://docs.squarecloud.app/fr/blob-reference/s3-compatibility.md) à l'adresse `https://s3-blob.squarecloud.app` fonctionne avec aws-cli, boto3, rclone et les SDK AWS. Obtenez la paire de clés d'accès via [Identifiants S3](https://docs.squarecloud.app/fr/blob-reference/endpoint/s3-credentials.md) : elle est dérivée de votre clé API, donc révoquer la clé révoque la paire.

> [accordion] Quelles fonctionnalités dépendent du plan ?
>
> Chaque plan a droit aux règles par préfixe (5 sur Hobby et Standard, 10 sur Pro, 20 sur Enterprise). Les métadonnées personnalisées et les liens de partage protégés par mot de passe nécessitent **Pro ou Enterprise**. Les expirations et la suppression automatique en dessous de 7 jours, ainsi que les fichiers servis sans cache en périphérie, nécessitent **Enterprise**. En dehors de ces plans, la requête est refusée avec `403 UPGRADE_REQUIRED`, et son `message` indique le plan qui débloque la fonctionnalité.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.