Datei in Blob Storage hochladen

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

erforderlich

Der API-Schlüssel für dein Konto. Du findest ihn in deinen Kontoeinstellungen.

Object Post lädt eine Datei hoch und gibt ihre id sowie, bei öffentlichen Dateien, eine CDN-url zurück, die du direkt einbetten oder teilen kannst. Der Endpoint dient für Anhänge, generierte Exporte und von Nutzern hochgeladene Medien der auf der Plattform gehosteten Anwendungen. Ein einzelner Request akzeptiert Dateien von 512 Bytes bis 100 MB. Größere Dateien, bis 10 GiB, laufen über den Chunked-Upload-Ablauf oder das S3-Gateway. Erfordert den Scope blob:write oder ein in Authorization gesendetes Upload-Token sowie einen aktiven Plan.

Behandle die zurückgegebene id als opak: Speichere sie so, wie sie kommt, und sende sie an die anderen Routen zurück. Sie beginnt mit pub/ oder prv/ und kann sich ändern, wenn die Datei ihre Sichtbarkeit oder ihren Ablauf ändert. Legacy-Dateien, gespeichert vor dem Update im September 2026, behalten ids ohne dieses Präfix, und jede Route akzeptiert beide.

Parameter

file

erforderlich

Verwende FormData (multipart/form-data), genau eine Datei pro Request.
Sende einen echten Dateinamen: Die gespeicherte Endung stammt daraus (reads.fastq.gz bleibt .fastq.gz).

string

erforderlich

Der Dateiname, ohne Endung. 1 bis 128 Zeichen: Buchstaben, Ziffern, _, . und -, beginnend mit einem Buchstaben, einer Ziffer oder _. Er darf .. nicht enthalten.

string

Ein Ordnerpfad für die Datei, bis zu 8 durch / getrennte Segmente und insgesamt 256 Zeichen. Jedes Segment folgt demselben Muster wie name, bis 64 Zeichen. Ein abschließendes / wird ignoriert.

boolean

Standard:"false"

true speichert die Datei ohne öffentliche URL. Lies sie über Object Download, einen Freigabelink oder das S3-Gateway. Wenn weggelassen, entscheidet die Regel für das Präfix.

string

Löscht die Datei nach dieser Zeit automatisch: 30 oder 30d für Tage, 6h für Stunden. Von 1 Stunde bis 1825 Tage (5 Jahre). Ablaufzeiten unter 7 Tagen erfordern den Enterprise-Plan. Wenn weggelassen, entscheidet die Regel für das Präfix.

boolean

Standard:"false"

true fügt dem Namen ein zufälliges Suffix hinzu, sodass die URL nicht erraten werden kann und ein neuer Upload nie einen alten ersetzt. Private Dateien erhalten es immer (false zusammen mit private=true wird abgelehnt).

boolean

Standard:"true"

Ohne Security Hash ersetzt ein neuer Upload mit demselben Namen und Präfix die Datei. false lehnt ihn stattdessen mit 409 OBJECT_ALREADY_EXISTS ab.

string

inline (im Browser öffnen) oder attachment (herunterladen, mit dem ursprünglichen Dateinamen).

boolean

Standard:"false"

true lässt Browser die Datei herunterladen statt sie zu öffnen, unabhängig von ihrem Typ.

string

Wie lange das CDN und Browser die Datei vorhalten: immutable (1 Jahr), max-age=N mit N von 60 bis 31536000 Sekunden, oder no-cache (jeder Lesezugriff geht an den Speicher; nur Enterprise). Dateien mit Security Hash verwenden standardmäßig immutable. Der Cache überdauert nie den Ablauf der Datei.

string

Ein JSON-Objekt mit String-Werten, zurückgegeben von Object Info. Schlüssel verwenden a-z, 0-9 und - (bis 64 Zeichen). Bis zu 5 Schlüssel und insgesamt 512 Bytes. Nur Pro und Enterprise.

string

Der SHA-256 der Datei. Stimmt er nicht überein, wird der Upload mit CHECKSUM_MISMATCH abgelehnt und nichts gespeichert.

Rate Limits & Parallelität

Jedes Konto darf höchstens 4 Uploads gleichzeitig laufen haben (TOO_MANY_CONCURRENT_UPLOADS, 429).
Die Pläne Hobby und Standard sind auf 1 Upload pro Sekunde begrenzt (RATE_LIMITED, 429). Pro und Enterprise sind davon ausgenommen.
Uploads über den enthaltenen Speicher des Kontos hinaus werden mit STORAGE_QUOTA_EXCEEDED abgelehnt.

Dateitypen

Praktisch jede Endung wird akzeptiert, einschließlich Formaten ohne registrierten MIME-Typ (.bam, .vcf, .fasta, .parquet, .h5, .npy und so weiter).

Der ausgelieferte Content-Type wird serverseitig aus der Endung bestimmt. Unbekannte Formate werden als application/octet-stream ausgeliefert.
Formate, die ein Browser rendert (.html, .svg, .xml und ähnliche), werden immer als Downloads ausgeliefert.
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.
Eine Regel für das Präfix oder ein Upload-Token kann die akzeptierten Endungen und die Größe einschränken.

Antwort

string

“success” bei Erfolg, “error” bei Misserfolg.

object

Anzeigen Objekt umschalten

string

Die Objekt-id: pub/<user_id>/<path> oder prv/<user_id>/<path>. Behandle sie als opak.

boolean

Ob die Datei privat ist.

string | null

Die öffentliche CDN-URL (https://blob.squarecloud.dev/pub/...) oder null bei privaten Dateien.

ISO 8601

Wann die Datei gelöscht wird. Nur vorhanden, wenn sie abläuft.

number

Die Dateigröße in Bytes.

string

Der im Request gesendete Name.

string

Das Präfix, falls eines gesendet wurde.

string

Der SHA-256 der gespeicherten Datei, in Hex.

boolean

true, wenn der Upload eine bestehende Datei mit demselben Namen ersetzt hat.

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

Fehler

Code	HTTP	Wann
`INVALID_OBJECT_NAME` / `INVALID_OBJECT_PREFIX`	400	`name` oder `prefix` entspricht nicht dem Muster.
`INVALID_OBJECT_EXPIRE`	400	`expire` ist keine Dauer von 1 Stunde bis 1825 Tage.
`INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_OVERWRITE` / `INVALID_STORAGE_AUTO_DOWNLOAD`	400	Das Flag ist nicht `true` oder `false`.
`INVALID_OBJECT_SECURITY_HASH`	400	Kein Boolean, oder `false` bei einer privaten Datei.
`INVALID_OBJECT_DISPOSITION` / `INVALID_OBJECT_CACHE_CONTROL` / `INVALID_OBJECT_METADATA` / `INVALID_CHECKSUM`	400	Der Wert liegt außerhalb der akzeptierten Formen.
`INVALID_FILE` / `INVALID_FILE_TYPE` / `BLOCKED_FILE_TYPE` / `FILE_TYPE_NOT_ALLOWED`	400	Der Dateiteil fehlt, seine Endung ist fehlerhaft oder gesperrt, oder die Regel bzw. das Token erlaubt sie nicht.
`FILE_TOO_SMALL`	400	Die Datei hat weniger als 512 Bytes.
`CHECKSUM_MISMATCH`	400	Die Datei stimmt nicht mit `checksum_sha256` überein. Es wurde nichts gespeichert.
`PERMISSION_DENIED`	401	Das Konto hat keinen aktiven Plan.
`UPLOAD_TOKEN_USED`	401	Das Upload-Token hat keine Nutzungen mehr übrig. Ein abgelaufenes Token antwortet mit `ACCESS_DENIED`.
`STORAGE_QUOTA_EXCEEDED`	403	Der Upload würde den enthaltenen Speicher überschreiten.
`PREFIX_NOT_ALLOWED`	403	Das Upload-Token ist an ein anderes Präfix gebunden.
`UPGRADE_REQUIRED`	403	Eine Option erfordert einen höheren Plan. Die `message` nennt welchen.
`ACCOUNT_BLOCKED`	403	Das Konto ist für das Speichern von Dateien gesperrt.
`INVALID_CONTENT_TYPE`	409	Der Request ist nicht `multipart/form-data`.
`OBJECT_ALREADY_EXISTS`	409	Der Name existiert und `overwrite=false`.
`FILE_TOO_LARGE`	413	Über 100 MB oder über der von der Regel oder dem Token erlaubten Größe.
`RATE_LIMITED` / `TOO_MANY_CONCURRENT_UPLOADS`	429	1 Upload pro Sekunde (Hobby und Standard) oder 4 laufende Uploads.
`UPLOAD_FAILED`	500	Der Speicher ist fehlgeschlagen. Versuche es erneut.
`PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE`	503	Der Speicher ist vorübergehend nicht verfügbar. Versuche es erneut.

Die vollständige Liste findest du unter Fehler.

Siehe auch

Blob SDK: 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
    }
}

Erste Schritte

Objekte

Chunked-Uploads

Konto

Freigabelinks

S3

Datei in Blob Storage hochladen

Parameter

Rate Limits & Parallelität

Dateitypen

Antwort

Fehler

Siehe auch

​Parameter

​Rate Limits & Parallelität

​Dateitypen

​Antwort

​Fehler

​Siehe auch

Parameter

Rate Limits & Parallelität

Dateitypen

Antwort

Fehler

Siehe auch