> ## 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.

# Schnellstart für die Blob Storage API

> Lade deine erste Datei mit der Blob Storage API hoch und wieder herunter: Basis-URL v1, Authorization-Header, curl-Upload, Antwort und Download-Link.

Blob Storage bewahrt deine Dateien auf, liefert öffentliche über ein CDN aus und stellt Links zu privaten aus. Diese Seite führt dich mit `curl` von einem API-Schlüssel zu einer hochgeladenen Datei und einem Download-Link. Speicher ist in jedem Plan enthalten: Pläne, Preise und FAQ findest du unter [Blob Storage](/de/services/blob).

## Basis-URL

Jeder Endpoint dieser Referenz ist relativ zu:

```bash theme={"system"}
https://blob.squarecloud.app/v1
```

## Authentifizierung

Blob Storage nimmt dieselben API-Schlüssel an wie die [Square Cloud API](/de/api-reference/introduction), im Header `Authorization`. Der Schlüssel braucht den Scope `blob:write` zum Hochladen und `blob:read` zum Auflisten und Herunterladen, und er darf nicht auf bestimmte Anwendungen beschränkt sein. Erstelle einen in deinen [Sicherheitseinstellungen des Kontos](https://squarecloud.app/de/account/security) und bewahre ihn in einer Umgebungsvariable auf:

```bash theme={"system"}
export SQUARECLOUD_API_KEY="your-api-key"
```

Mehr zu Scopes und Upload-Tokens unter [Authentifizierung](/de/blob-reference/authentication).

## Eine Datei hochladen

[Object Post](/de/blob-reference/endpoint/post) nimmt die Datei als `multipart/form-data` entgegen und ihren Namen, ohne Endung, in der Query:

```bash theme={"system"}
curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --form 'file=@./logo.png'
```

```json theme={"system"}
{
  "status": "success",
  "response": {
    "id": "pub/3155597145698959364/images/logo.png",
    "private": false,
    "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo.png",
    "size": 416230,
    "name": "logo",
    "prefix": "images",
    "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
    "replaced": false
  }
}
```

Die Datei ist standardmäßig öffentlich: `url` funktioniert sofort im Browser oder in einem `<img>`-Tag. Speichere die `id` so, wie sie kommt, denn jede andere Route erwartet sie.

Eine einzelne Anfrage nimmt Dateien von 512 Bytes bis 100 MB an. Größere Dateien bis 10 GiB laufen über den [Chunked Upload](/de/blob-reference/endpoint/chunked-init) oder das [S3-Gateway](/de/blob-reference/s3-compatibility).

## Eine private Datei hochladen

Füge `private=true` hinzu, und die Datei bekommt keine öffentliche URL (`url` ist `null`):

```bash theme={"system"}
curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=invoice&prefix=invoices&private=true' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --form 'file=@./invoice.pdf'
```

## Eine Datei herunterladen

Eine öffentliche Datei lädst du über ihre `url` herunter. Für eine private signiert [Object Download](/de/blob-reference/endpoint/download) einen temporären Link, der ohne Zugangsdaten funktioniert, und leitet dorthin weiter, sodass `curl -L` die Datei speichert:

```bash theme={"system"}
curl -L --output invoice.pdf \
  --url 'https://blob.squarecloud.app/v1/objects/download?object=<id>' \
  --header "Authorization: $SQUARECLOUD_API_KEY"
```

Ersetze `<id>` durch die `id` des Uploads. Füge `redirect=false` hinzu, um den Link als JSON zu erhalten und an jemand anderen weiterzugeben. Für Links, die du widerrufen oder mit einem Passwort schützen kannst, erstelle einen [Freigabelink](/de/blob-reference/endpoint/shares-create).

## Dateien auflisten und löschen

[Object List](/de/blob-reference/endpoint/list) liefert deine Dateien seitenweise:

```bash theme={"system"}
curl --url 'https://blob.squarecloud.app/v1/objects?prefix=images/' \
  --header "Authorization: $SQUARECLOUD_API_KEY"
```

[Objects Delete](/de/blob-reference/endpoint/delete) entfernt eine Datei oder bis zu 100 in einer Anfrage:

```bash theme={"system"}
curl --request DELETE \
  --url 'https://blob.squarecloud.app/v1/objects' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "object": "<id>" }'
```

## Wenn etwas schiefgeht

Fehler kommen als `{ "status": "error", "code": "..." }`. Die, denen du am ehesten zuerst begegnest:

| Code | HTTP | Lösung |
| - | - | - |
| `ACCESS_DENIED` | 401 | Der Schlüssel fehlt oder wird nicht erkannt. Prüfe den Header `Authorization`. |
| `PERMISSION_DENIED` | 401 | Das Konto hat keinen aktiven Plan und kann daher nicht hochladen. |
| `MISSING_SCOPE` | 403 | Dem Schlüssel fehlt `blob:write` oder `blob:read`. Erstelle einen Schlüssel mit diesem Scope. |
| `RESOURCE_NOT_ALLOWED` | 403 | Der Schlüssel ist auf Anwendungen beschränkt. Verwende einen Schlüssel ohne diese Beschränkung. |
| `FILE_TOO_LARGE` | 413 | Die Datei ist größer als 100 MB. Verwende den Chunked Upload. |

Alle Codes stehen unter [Fehler](/de/blob-reference/errors).

## Nächste Schritte

<CardGroup cols={2}>
  <Card title="Blob SDK" icon="js" href="/de/sdks/blob/client">
    Dateien aus JavaScript hochladen und verwalten, Chunked Uploads inklusive.
  </Card>

  <Card title="S3-Kompatibilität" icon="bucket" href="/de/blob-reference/s3-compatibility">
    Nutze aws-cli, boto3, rclone oder ein beliebiges AWS SDK.
  </Card>

  <Card title="Links und Freigaben" icon="share-nodes" href="/de/blob-reference/links-and-sharing">
    Temporäre Links, Freigabelinks und wann du welchen verwendest.
  </Card>

  <Card title="Upload aus dem Browser" icon="upload" href="/de/blob-reference/endpoint/upload-tokens">
    Lass Besucher hochladen, ohne deinen API-Schlüssel preiszugeben.
  </Card>
</CardGroup>