Blob Object Post - Square Cloud

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

import fs from 'node:fs';

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

const params = new URLSearchParams({
  name: 'myfile',
  prefix: 'images',
  expire: '30',
});

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

import requests

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

{
    "status": "success",
    "response": {
        "id": "3155597145698959364/images/test_lxch4k7y-07ee.png",
        "name": "test",
        "prefix": "images",
        "size": 416230,
        "url": "https://public-blob.squarecloud.dev/3155597145698959364/images/test_lxch4k7y-07ee.png"
    }
}

Authorization

string

obbligatorio

La chiave API del tuo account. Puoi trovarla nelle impostazioni del tuo account.

file

obbligatorio

Usa FormData. (multipart/form-data)

name

string

obbligatorio

Una stringa che rappresenta il nome del file. (senza estensione)
Deve rispettare il pattern a-z, A-Z, 0-9 e _. (da 3 a 32 caratteri)

prefix

string

Una stringa che rappresenta il prefisso del file.
Deve rispettare il pattern a-z, A-Z, 0-9 e _. (da 3 a 32 caratteri)

expire

number

Un numero che indica il periodo di scadenza del file, compreso tra 1 e 365 giorni.

security_hash

boolean

Imposta su true se è richiesto un hash di sicurezza.

auto_download

boolean

Imposta su true se il file deve essere configurato per il download automatico.

Limiti di frequenza e concorrenza

Il caricamento richiede un piano a pagamento.

I piani Hobby e Standard sono limitati a 1 caricamento al secondo.
I piani Pro ed Enterprise non sono soggetti al limite al secondo: possono invece eseguire fino a 4 caricamenti contemporaneamente.

In tutti i piani a pagamento, un account può avere al massimo 4 caricamenti in corso simultaneamente. Avviare un altro caricamento mentre 4 sono ancora in esecuzione restituisce TOO_MANY_CONCURRENT_UPLOADS (429).

Per motivi di sicurezza, i file .html e .svg vengono sempre consegnati come download (serviti come application/octet-stream) invece di essere renderizzati inline.

Risposta

status

string

Indica se la chiamata è andata a buon fine. “success” se riuscita, “error” in caso contrario.

response

object

Mostra Toggle object

string

L’ID del file caricato.

name

string

Il nome del file caricato.

prefix

string

Il prefisso sotto cui il file è stato memorizzato (riportato dalla query prefix; omesso quando non ne è stato inviato alcuno).

size

number

La dimensione del file caricato, in byte.

url

string

L’URL del file caricato. (File distribuito nella CDN di Square Cloud)

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

import fs from 'node:fs';

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

const params = new URLSearchParams({
  name: 'myfile',
  prefix: 'images',
  expire: '30',
});

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

import requests

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

{
    "status": "success",
    "response": {
        "id": "3155597145698959364/images/test_lxch4k7y-07ee.png",
        "name": "test",
        "prefix": "images",
        "size": 416230,
        "url": "https://public-blob.squarecloud.dev/3155597145698959364/images/test_lxch4k7y-07ee.png"
    }
}

Risoluzione dei problemi

Relativi all’oggetto

// The provided object name is invalid.
// Must adhere to the a to z, A to Z, 0 to 9, and _ pattern.
{
    "status": "error",
    "code": "INVALID_OBJECT_NAME"
}

// The provided object prefix is invalid.
// Must adhere to the a to z, A to Z, 0 to 9, and _ pattern.
{
    "status": "error",
    "code": "INVALID_OBJECT_PREFIX"
}

// The provided expiration value for the object is invalid.
// Must be a number ranging from 1 to 365. (value in days).
{
    "status": "error",
    "code": "INVALID_OBJECT_EXPIRE"
}

// The provided security hash boolean is invalid.
// Just set to true or false. 😅
{
    "status": "error",
    "code": "INVALID_OBJECT_SECURITY_HASH"
}

// The provided auto-download boolean is invalid.
// Just set to true or false. 😅
{
    "status": "error",
    "code": "INVALID_STORAGE_AUTO_DOWNLOAD"
}

Relativi al file

La dimensione massima attuale del file è 100MB. In futuro prevediamo di aumentarla a 10GB. Per ora il limite è 100MB a causa di vincoli tecnici e di bilanciamento del carico.

// The provided file is invalid.
{
    "status": "error",
    "code": "INVALID_FILE"
}

// The provided file type is invalid.
{
    "status": "error",
    "code": "INVALID_FILETYPE"
}

// The file size is too small (< 1kb).
{
    "status": "error",
    "code": "FILE_TOO_SMALL"
}

Non autorizzato

// The API key is missing or invalid. Set a valid key in the Authorization header.
// Also returned when the account is on the free plan — uploading requires a paid plan.
{
    "status": "error",
    "code": "ACCESS_DENIED"
}

Quota di archiviazione superata

// You have exceeded your storage quota. Delete some files or upgrade your plan.
{
    "status": "error",
    "code": "STORAGE_QUOTA_EXCEEDED"
}

Tipo di contenuto non valido

// This route only accepts multipart/form-data requests.
{
    "status": "error",
    "code": "INVALID_CONTENT_TYPE"
}

Payload troppo grande

La dimensione massima attuale del file è 100MB.

// The uploaded file exceeds the maximum allowed size of 100 MB.
{
    "status": "error",
    "code": "PAYLOAD_TOO_LARGE"
}

Frequenza limitata

// Per-second upload limit reached (Hobby/Standard: max 1 upload per second).
{
    "status": "error",
    "code": "RATELIMIT"
}

// Too many simultaneous uploads (max 4 in progress at a time per account).
{
    "status": "error",
    "code": "TOO_MANY_CONCURRENT_UPLOADS"
}

Caricamento fallito

// Failed to upload object to storage. Please try again later.
{
    "status": "error",
    "code": "UPLOAD_FAILED"
}

Objects DeleteQuesta documentazione fornisce una panoramica completa dell'endpoint DELETE /v1/objects della SquareCloud Blob API.

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

import fs from 'node:fs';

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

const params = new URLSearchParams({
  name: 'myfile',
  prefix: 'images',
  expire: '30',
});

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

import requests

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

{
    "status": "success",
    "response": {
        "id": "3155597145698959364/images/test_lxch4k7y-07ee.png",
        "name": "test",
        "prefix": "images",
        "size": 416230,
        "url": "https://public-blob.squarecloud.dev/3155597145698959364/images/test_lxch4k7y-07ee.png"
    }
}

​Limiti di frequenza e concorrenza

​Risposta

​Risoluzione dei problemi

​Relativi all’oggetto

​Relativi al file

​Non autorizzato

​Quota di archiviazione superata

​Tipo di contenuto non valido

​Payload troppo grande

​Frequenza limitata

​Caricamento fallito

Limiti di frequenza e concorrenza

Risposta

Risoluzione dei problemi

Relativi all’oggetto

Relativi al file

Non autorizzato

Quota di archiviazione superata

Tipo di contenuto non valido

Payload troppo grande

Frequenza limitata

Caricamento fallito