Envoyer un fichier vers Blob Storage

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images&security_hash=true' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./logo.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./logo.png')]), 'logo.png');

const params = new URLSearchParams({
  name: 'logo',
  prefix: 'images',
  security_hash: 'true',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
  body: form,
});

import requests

with open('logo.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'logo', 'prefix': 'images', 'security_hash': 'true'},
        files={'file': ('logo.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "name": "logo",
        "prefix": "images",
        "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
        "replaced": false
    }
}

{
    "status": "success",
    "response": {
        "id": "prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf",
        "private": true,
        "url": null,
        "size": 88412,
        "name": "2026-09",
        "prefix": "invoices",
        "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
        "replaced": false
    }
}

string

requis

La clé d’API de votre compte. Vous pouvez la trouver dans les paramètres de votre compte.

Object Post envoie un fichier et renvoie son id et, pour les fichiers publics, une url CDN que vous pouvez intégrer ou partager directement. Il sert de base aux pièces jointes, aux exports générés et aux médias envoyés par les utilisateurs des applications hébergées sur la plateforme. Une seule requête accepte des fichiers de 512 octets à 100 Mo. Les fichiers plus volumineux, jusqu’à 10 GiB, passent par le flux d’envoi chunked ou la passerelle S3. Nécessite le scope blob:write, ou un jeton d’envoi envoyé dans Authorization, ainsi qu’un plan actif.

Traitez l’id renvoyé comme opaque : stockez-le tel quel et renvoyez-le aux autres routes. Il commence par pub/ ou prv/ et peut changer lorsque le fichier change de visibilité ou d’expiration. Les fichiers hérités, stockés avant la mise à jour de septembre 2026, conservent des id sans ce préfixe, et chaque route accepte les deux.

Paramètres

file

requis

Utilisez FormData (multipart/form-data), exactement un fichier par requête.
Envoyez un vrai nom de fichier : l’extension stockée en provient (reads.fastq.gz reste .fastq.gz).

string

requis

Le nom du fichier, sans extension. De 1 à 128 caractères : lettres, chiffres, _, . et -, commençant par une lettre, un chiffre ou _. Il ne peut pas contenir ...

string

Un chemin de dossier pour le fichier, jusqu’à 8 segments séparés par / et 256 caractères au total. Chaque segment suit le même motif que name, jusqu’à 64 caractères. Un / final est ignoré.

boolean

défaut:"false"

true stocke le fichier sans URL publique. Lisez-le via Téléchargement d’objet, un lien de partage ou la passerelle S3. S’il est omis, la règle du préfixe décide.

string

Supprime automatiquement le fichier après cette durée : 30 ou 30d pour des jours, 6h pour des heures. De 1 heure à 1825 jours (5 ans). Les expirations inférieures à 7 jours nécessitent le plan Enterprise. S’il est omis, la règle du préfixe décide.

boolean

défaut:"false"

true ajoute un suffixe aléatoire au nom, de sorte que l’URL ne peut pas être devinée et qu’un nouvel envoi ne remplace jamais un ancien. Les fichiers privés le reçoivent toujours (false combiné à private=true est refusé).

boolean

défaut:"true"

Sans security hash, un nouvel envoi avec le même nom et le même préfixe remplace le fichier. false le refuse plutôt avec 409 OBJECT_ALREADY_EXISTS.

string

inline (ouvrir dans le navigateur) ou attachment (télécharger, avec le nom de fichier d’origine).

boolean

défaut:"false"

true fait télécharger le fichier par les navigateurs au lieu de l’ouvrir, quel que soit son type.

string

Durée pendant laquelle le CDN et les navigateurs conservent le fichier : immutable (1 an), max-age=N avec N de 60 à 31536000 secondes, ou no-cache (chaque lecture va jusqu’au stockage ; Enterprise uniquement). Les fichiers avec un security hash utilisent immutable par défaut. Le cache ne dure jamais plus longtemps que l’expiration du fichier.

string

Un objet JSON de valeurs de type chaîne, renvoyé par Informations sur l’objet. Les clés utilisent a-z, 0-9 et - (jusqu’à 64 caractères). Jusqu’à 5 clés et 512 octets au total. Pro et Enterprise uniquement.

string

Le SHA-256 du fichier. S’il ne correspond pas, l’envoi est refusé avec CHECKSUM_MISMATCH et rien n’est stocké.

Limites de débit et concurrence

Chaque compte peut avoir au maximum 4 envois en cours en même temps (TOO_MANY_CONCURRENT_UPLOADS, 429).
Les plans Hobby et Standard sont limités à 1 envoi par seconde (RATE_LIMITED, 429). Pro et Enterprise en sont exemptés.
Les envois qui dépassent le stockage inclus du compte sont refusés avec STORAGE_QUOTA_EXCEEDED.

Types de fichiers

Pratiquement toutes les extensions sont acceptées, y compris les formats sans type MIME enregistré (.bam, .vcf, .fasta, .parquet, .h5, .npy et ainsi de suite).

Le Content-Type servi est dérivé côté serveur à partir de l’extension. Les formats inconnus sont servis en application/octet-stream.
Les formats qu’un navigateur affiche (.html, .svg, .xml et similaires) sont toujours servis en tant que téléchargements.
Les exécutables et les installateurs sont refusés avec BLOCKED_FILE_TYPE : exe, msi, dll, bat, cmd, com, scr, cpl, pif, hta, vbs, vbe, jse, wsf, wsh, msc, reg, lnk, sys, drv, ps1, apk, xpi.
Une règle du préfixe ou un jeton d’envoi peut restreindre les extensions et la taille acceptées.

Réponse

string

“success” en cas de succès, “error” sinon.

object

Afficher Afficher l'objet

string

L’id de l’objet : pub/<user_id>/<path> ou prv/<user_id>/<path>. Traitez-le comme opaque.

boolean

Indique si le fichier est privé.

string | null

L’URL CDN publique (https://blob.squarecloud.dev/pub/...), ou null pour les fichiers privés.

ISO 8601

Date à laquelle le fichier sera supprimé. Présent uniquement lorsqu’il expire.

number

La taille du fichier, en octets.

string

Le nom envoyé dans la requête.

string

Le préfixe, lorsqu’il a été envoyé.

string

Le SHA-256 du fichier stocké, en hexadécimal.

boolean

true lorsque l’envoi a remplacé un fichier existant portant le même nom.

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images&security_hash=true' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./logo.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./logo.png')]), 'logo.png');

const params = new URLSearchParams({
  name: 'logo',
  prefix: 'images',
  security_hash: 'true',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
  body: form,
});

import requests

with open('logo.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'logo', 'prefix': 'images', 'security_hash': 'true'},
        files={'file': ('logo.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "name": "logo",
        "prefix": "images",
        "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
        "replaced": false
    }
}

{
    "status": "success",
    "response": {
        "id": "prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf",
        "private": true,
        "url": null,
        "size": 88412,
        "name": "2026-09",
        "prefix": "invoices",
        "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
        "replaced": false
    }
}

Erreurs

Code	HTTP	Quand
`INVALID_OBJECT_NAME` / `INVALID_OBJECT_PREFIX`	400	`name` ou `prefix` ne correspond pas au motif.
`INVALID_OBJECT_EXPIRE`	400	`expire` n’est pas une durée comprise entre 1 heure et 1825 jours.
`INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_OVERWRITE` / `INVALID_STORAGE_AUTO_DOWNLOAD`	400	L’option ne vaut ni `true` ni `false`.
`INVALID_OBJECT_SECURITY_HASH`	400	N’est pas un booléen, ou vaut `false` sur un fichier privé.
`INVALID_OBJECT_DISPOSITION` / `INVALID_OBJECT_CACHE_CONTROL` / `INVALID_OBJECT_METADATA` / `INVALID_CHECKSUM`	400	La valeur ne correspond à aucune des formes acceptées.
`INVALID_FILE` / `INVALID_FILE_TYPE` / `BLOCKED_FILE_TYPE` / `FILE_TYPE_NOT_ALLOWED`	400	La partie fichier est absente, son extension est mal formée ou bloquée, ou la règle ou le jeton ne l’autorise pas.
`FILE_TOO_SMALL`	400	Le fichier fait moins de 512 octets.
`CHECKSUM_MISMATCH`	400	Le fichier ne correspond pas à `checksum_sha256`. Rien n’a été stocké.
`PERMISSION_DENIED`	401	Le compte n’a pas de plan actif.
`UPLOAD_TOKEN_USED`	401	Le jeton d’envoi n’a plus d’utilisations disponibles. Un jeton expiré répond `ACCESS_DENIED`.
`STORAGE_QUOTA_EXCEEDED`	403	L’envoi dépasserait le stockage inclus.
`PREFIX_NOT_ALLOWED`	403	Le jeton d’envoi est lié à un autre préfixe.
`UPGRADE_REQUIRED`	403	Une option nécessite un plan supérieur. Le `message` indique lequel.
`ACCOUNT_BLOCKED`	403	Le compte n’est pas autorisé à stocker des fichiers.
`INVALID_CONTENT_TYPE`	409	La requête n’est pas en `multipart/form-data`.
`OBJECT_ALREADY_EXISTS`	409	Le nom existe et `overwrite=false`.
`FILE_TOO_LARGE`	413	Au-delà de 100 Mo, ou au-delà de la taille autorisée par la règle ou le jeton.
`RATE_LIMITED` / `TOO_MANY_CONCURRENT_UPLOADS`	429	1 envoi par seconde (Hobby et Standard), ou 4 en cours.
`UPLOAD_FAILED`	500	Le stockage a échoué. Réessayez.
`PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE`	503	Le stockage est temporairement indisponible. Réessayez.

Consultez Erreurs pour la liste complète.

Voir aussi

SDK Blob : blob.put()

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images&security_hash=true' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./logo.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./logo.png')]), 'logo.png');

const params = new URLSearchParams({
  name: 'logo',
  prefix: 'images',
  security_hash: 'true',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
  body: form,
});

import requests

with open('logo.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'logo', 'prefix': 'images', 'security_hash': 'true'},
        files={'file': ('logo.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "name": "logo",
        "prefix": "images",
        "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
        "replaced": false
    }
}

{
    "status": "success",
    "response": {
        "id": "prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf",
        "private": true,
        "url": null,
        "size": 88412,
        "name": "2026-09",
        "prefix": "invoices",
        "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
        "replaced": false
    }
}

Premiers pas

Objets

Uploads par morceaux

Compte

Liens de partage

S3

Envoyer un fichier vers Blob Storage

Paramètres

Limites de débit et concurrence

Types de fichiers

Réponse

Erreurs

Voir aussi

​Paramètres

​Limites de débit et concurrence

​Types de fichiers

​Réponse

​Erreurs

​Voir aussi

Paramètres

Limites de débit et concurrence

Types de fichiers

Réponse

Erreurs

Voir aussi