Blob Object Post

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"
    }
}

string

erforderlich

Der API-Schlüssel für Ihr Konto. Sie finden ihn in Ihren Kontoeinstellungen.

Object Post lädt eine einzelne Datei in den Square Cloud Blob Storage hoch und gibt eine CDN-gestützte URL zurück, die du direkt einbetten oder teilen kannst, ohne selbst einen Bucket bereitzustellen oder ACLs zu verwalten. Es dient als Grundlage für Anhänge, generierte Exporte und von Nutzern hochgeladene Medien für auf der Plattform gehostete Anwendungen. Die gespeicherte Dateiendung kommt aus dem Dateinamen, den du im Multipart-Teil sendest (mit Fallback auf den deklarierten MIME-Typ, dann auf bin), sende also immer einen echten Dateinamen. Praktisch jeder Dateityp wird akzeptiert; nur ausführbare Dateien und Installer werden abgelehnt. Objekten kann eine automatische Ablaufzeit zwischen 7 und 1825 Tagen (5 Jahre) zugewiesen werden, nach der sie nicht mehr ausgeliefert werden. Eine einzelne Anfrage akzeptiert Dateien von 512 Bytes bis 100 MB, dem größten Body, den Cloudflares Edge annimmt. Größere Dateien, bis zu 1 GiB, laufen über den Chunked-Upload-Ablauf. Sobald eine Datei hochgeladen ist, kannst du sie mit Objektliste durchsuchen, mit Objekt löschen entfernen oder mit Account Stats die Nutzung gegen dein Plan-Kontingent verfolgen.

file

erforderlich

Verwende FormData (multipart/form-data). Genau eine Datei pro Anfrage.
Sende einen echten Dateinamen: Die gespeicherte Dateiendung wird daraus abgeleitet.

string

erforderlich

Eine Zeichenkette, die den Namen der Datei darstellt. (ohne Erweiterung)
Muss dem Muster a bis z, A bis Z, 0 bis 9 und _ entsprechen. (3 bis 32 Zeichen)

string

Eine Zeichenkette, die das Präfix der Datei darstellt.
Muss dem Muster a bis z, A bis Z, 0 bis 9 und _ entsprechen. (3 bis 32 Zeichen)

number

Eine Zahl, die die Ablaufdauer der Datei angibt, im Bereich von 7 bis 1825 Tagen (5 Jahre).

boolean

Auf true setzen, wenn ein Sicherheits-Hash erforderlich ist.

boolean

Auf true setzen, wenn die Datei für automatischen Download vorgesehen werden soll.

Rate Limits & Nebenläufigkeit

Das Hochladen erfordert einen kostenpflichtigen Plan.

Jedes Konto darf höchstens 4 Uploads gleichzeitig in Bearbeitung haben. Das Starten eines weiteren Uploads, während noch 4 laufen, liefert TOO_MANY_CONCURRENT_UPLOADS (429) zurück.
Hobby- und Standard-Pläne sind zusätzlich auf 1 Upload pro Sekunde beschränkt (RATE_LIMITED, 429). Pro- und Enterprise-Pläne sind vom Limit pro Sekunde ausgenommen.

Aus Sicherheitsgründen werden Formate, die ein Browser inline rendert (.html, .svg, .xml, .xhtml und ähnliche), immer als Download ausgeliefert (als application/octet-stream bereitgestellt), anstatt gerendert zu werden. Das Setzen von auto_download=true erzwingt dasselbe Download-Verhalten für jeden Dateityp.

Dateitypen

Praktisch jede Dateiendung wird akzeptiert, einschließlich Formaten ohne registrierten MIME-Typ (.bam, .vcf, .fasta, .fastq, .parquet, .h5, .npy und so weiter). Es gibt keine MIME-Allowlist mehr.

Die gespeicherte Dateiendung wird aus dem im Multipart-Teil gesendeten Dateinamen abgeleitet, mit Fallback auf den deklarierten MIME-Typ, dann auf bin.
Zusammengesetzte Kompressions-Suffixe bleiben erhalten: reads.fastq.gz wird als .fastq.gz gespeichert, nicht als .gz.
Der ausgelieferte Content-Type wird serverseitig aus der Dateiendung abgeleitet. Unbekannte Formate werden als application/octet-stream ausgeliefert, sodass sie heruntergeladen statt gerendert werden.
Ausführbare Dateien und Installer werden mit BLOCKED_FILE_TYPE abgelehnt: exe, msi, dll, bat, cmd, com, scr, cpl, pif, hta, vbs, vbe, jse, wsf, wsh, msc, reg, lnk, sys, drv, ps1, apk, xpi.

Response

string

Gibt an, ob der Aufruf erfolgreich war. “success” bei Erfolg, “error” andernfalls.

object

Anzeigen Objekt ein-/ausblenden

string

Die ID der hochgeladenen Datei.

string

Der Name der hochgeladenen Datei.

string

Das Präfix, unter dem die Datei gespeichert wurde (aus dem prefix-Query gespiegelt; entfällt, wenn keines gesendet wurde).

number

Die Größe der hochgeladenen Datei, in Bytes.

string

Die öffentliche CDN-URL der hochgeladenen Datei: https://public-blob.squarecloud.dev/<user_id>/<key>, wobei der Key [prefix/]name[_hash][-exN].ext ist (Hash- und Ablaufsuffixe erscheinen nur, wenn sie verwendet werden; die Erweiterung wird aus dem hochgeladenen Dateinamen abgeleitet).

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"
    }
}

Fehlerbehebung

Objektbezogen

// 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 7 to 1825. (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"
}

Dateibezogen

Eine einzelne Anfrage akzeptiert bis zu 100 MB. Für Dateien bis zu 1 GiB verwende den Chunked-Upload-Ablauf.

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

// The file extension is malformed or too long.
{
    "status": "error",
    "code": "INVALID_FILE_TYPE"
}

// Executable/installer extensions (exe, msi, bat, apk, ...) are not accepted.
{
    "status": "error",
    "code": "BLOCKED_FILE_TYPE"
}

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

Nicht autorisiert

// The API key is missing or invalid. Set a valid key in the Authorization header.
{
    "status": "error",
    "code": "ACCESS_DENIED"
}

// The account has no active paid plan. Uploading to Blob Storage requires a paid plan.
{
    "status": "error",
    "code": "PERMISSION_DENIED"
}

Speicherkontingent überschritten

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

Ungültiger Content-Type

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

Payload zu groß

Eine einzelne Anfrage akzeptiert bis zu 100 MB. Für Dateien bis zu 1 GiB verwende den Chunked-Upload-Ablauf.

// A single request accepts up to 100 MB. Use /v1/objects/chunked for files up to 1 GiB.
{
    "status": "error",
    "code": "FILE_TOO_LARGE"
}

Rate-limitiert

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

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

Upload fehlgeschlagen

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

Zurück

Objekte löschenDiese Dokumentation bietet einen umfassenden Überblick über den DELETE /v1/objects-Endpoint der SquareCloud Blob API.

Weiter

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"
    }
}

Blob-Endpunkte

Chunked-Uploads

Rate Limits & Nebenläufigkeit

Dateitypen

Response

Fehlerbehebung

Objektbezogen

Dateibezogen

Nicht autorisiert

Speicherkontingent überschritten

Ungültiger Content-Type

Payload zu groß

Rate-limitiert

Upload fehlgeschlagen

​Rate Limits & Nebenläufigkeit

​Dateitypen

​Response

​Fehlerbehebung

​Objektbezogen

​Dateibezogen

​Nicht autorisiert

​Speicherkontingent überschritten

​Ungültiger Content-Type

​Payload zu groß

​Rate-limitiert

​Upload fehlgeschlagen

Rate Limits & Nebenläufigkeit

Dateitypen

Response

Fehlerbehebung

Objektbezogen

Dateibezogen

Nicht autorisiert

Speicherkontingent überschritten

Ungültiger Content-Type

Payload zu groß

Rate-limitiert

Upload fehlgeschlagen