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

# Uploads

> Lade Dateien mit put() hoch: Dateipfade, Blob/File oder Bytes, automatische Multipart-Uploads über 90 MiB und Upload-Tokens zum Hochladen direkt aus dem Browser.

## `put(file, options)`

`put()` lädt eine Datei hoch und gibt das neue Objekt zurück.

```typescript theme={"system"}
const { id, url } = await blob.put("./photo.png", {
    name: "photo",
    prefix: "avatars",
});
```

### Eingaben

| Eingabe                                | Umgebung            | Hinweise                                                                                                                                                         |
| -------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `string` (Dateipfad)                   | **Nur Node.js**     | Wird mit `fs.openAsBlob` geöffnet und **von der Festplatte gestreamt**, nie vollständig in den Speicher gelesen. Die Endung stammt aus dem Basisnamen des Pfads. |
| `Blob` / `File`                        | Node.js und Browser | Eine `File` liefert ihren `name` (und ihre Endung).                                                                                                              |
| `Uint8Array` (einschließlich `Buffer`) | Node.js und Browser | Übergib `filename`, um die Endung festzulegen.                                                                                                                   |
| `ArrayBuffer`                          | Node.js und Browser | Übergib `filename`, um die Endung festzulegen.                                                                                                                   |

Die Endung des Objekts stammt aus `filename`, sonst aus dem Basisnamen des Pfads oder dem Namen der `File`. Bytes und ein einfacher `Blob` haben keinen Namen, also **übergib `filename`** (zum Beispiel `"data.json"`), wenn du sie hochlädst.

<Note>
  In Node.js wirft ein Pfad, der sich nicht öffnen lässt, einen einfachen `Error` (`Cannot open file: <path>`, mit dem ursprünglichen Fehler in `cause`). Im Browser schlägt die Übergabe eines Pfads schon früher fehl, mit dem Fehler beim Import von `node:fs`. Verwende stattdessen eine `File` aus einem `<input type="file">`.
</Note>

### Optionen

| Option            | Typ                          | Beschreibung                                                                                                                                                                    |
| ----------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`            | `string`                     | Objektname **ohne Endung**, entsprechend `^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$`, ohne `..`, nicht auf `-ex<digits>` endend. Erforderlich, sofern ihn kein Upload-Token festlegt. |
| `prefix`          | `string`                     | Ordnerähnlicher Pfad: bis zu 8 Segmente der Form `^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$`, 256 Zeichen.                                                                             |
| `private`         | `boolean`                    | Standard `false`. Private Objekte erhalten immer einen Security-Hash und haben `url: null`.                                                                                     |
| `security_hash`   | `boolean`                    | Hängt `_<hash>` an den Namen an.                                                                                                                                                |
| `expire`          | `string`                     | `"30"` (Tage), `"30d"` oder `"168h"`; von 7 bis 1825 Tagen (Enterprise bis hinunter zu 1 Stunde). Der Ablauf wird Teil der ID.                                                  |
| `overwrite`       | `boolean`                    | `false` schlägt mit `OBJECT_ALREADY_EXISTS` fehl, wenn der Name vergeben ist. **Nur einfache Uploads.**                                                                         |
| `disposition`     | `"inline"` \| `"attachment"` | `Content-Disposition` des Objekts.                                                                                                                                              |
| `auto_download`   | `boolean`                    | Erzwingt einen Download (`application/octet-stream`).                                                                                                                           |
| `cache_control`   | `string`                     | `immutable`, `max-age=60..31536000` oder `no-cache` (Enterprise).                                                                                                               |
| `metadata`        | `Record<string, string>`     | Pro und Enterprise. Schlüssel `^[a-z0-9-]{1,64}$` (nie `sq-*`), bis zu 5 Schlüssel und 512 Bytes.                                                                               |
| `checksum_sha256` | `string`                     | 64 kleingeschriebene Hex-Zeichen. Eine Abweichung schlägt mit `CHECKSUM_MISMATCH` fehl, und nichts wird gespeichert. **Nur einfache Uploads.**                                  |
| `filename`        | `string`                     | Dateiname, dessen Endung zur Endung des Objekts wird. Standardmäßig der Name der `File` oder der Basisname des Pfads.                                                           |
| `mime_type`       | `string`                     | Wird nur verwendet, um die Endung zu wählen, wenn `filename` keine hat. Der Server leitet den `Content-Type` ab.                                                                |

Die vollständigen serverseitigen Regeln findest du unter [Object Post](/de/blob-reference/endpoint/post).

### Ergebnis

| Feld                                   | Typ              | Beschreibung                                                                                                             |
| -------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `id`                                   | `string`         | Opake Objekt-ID. [Speichere sie unverändert](/de/sdks/blob/client#objekt-ids).                                           |
| `private`                              | `boolean`        | Ob das Objekt privat ist.                                                                                                |
| `url`                                  | `string \| null` | Öffentliche URL, oder `null` für ein privates Objekt (verwende [`downloadUrl()`](/de/sdks/blob/objects#download-links)). |
| `expires_at`                           | `string`         | Wann das Objekt abläuft, falls es einen Ablauf hat.                                                                      |
| `size`                                 | `number`         | Größe in Bytes.                                                                                                          |
| `name`, `prefix`, `sha256`, `replaced` |                  | Nur einfache Uploads.                                                                                                    |
| `parts`                                | `number`         | Nur Multipart-Uploads: Anzahl der gesendeten Teile.                                                                      |

## Einfache und Multipart-Uploads

`put()` wählt den Upload-Ablauf anhand der Dateigröße:

| Dateigröße                                       | Ablauf                         | Endpoint                                                 |
| ------------------------------------------------ | ------------------------------ | -------------------------------------------------------- |
| Bis einschließlich **90 MiB** (94.371.840 Bytes) | Einfacher Upload, eine Anfrage | [Object Post](/de/blob-reference/endpoint/post)          |
| Über 90 MiB, bis **10 GiB**                      | Multipart-Upload (Chunked)     | [Chunked Init](/de/blob-reference/endpoint/chunked-init) |

Jede Datei muss **mindestens 512 Bytes** groß sein; kleinere Dateien schlagen mit `FILE_TOO_SMALL` fehl. Ein `max_size` aus einer Regel oder einem Upload-Token oder dein Speicherkontingent kann die Obergrenze von 10 GiB senken.

### So läuft ein Multipart-Upload ab

1. Das SDK startet den Upload, und der Server antwortet mit seinen Teillimits (`max_size`, `max_parts`).
2. Die Datei wird in Teile von `min(max_size, max(16 MiB, ceil(size / max_parts)))` Bytes aufgeteilt. Ein Teil ist meist 16 MiB oder größer, aber kleiner, wenn das `max_size` des Servers kleiner ist.
3. Die Teile werden **6 gleichzeitig** gesendet, das Limit des Servers für gleichzeitig laufende Teile. Ein fehlgeschlagener Teil wird innerhalb von `maxRetries` [wiederholt](/de/sdks/blob/errors#wiederholungsrichtlinie).
4. Wenn alle Teile angekommen sind, schließt das SDK den Upload ab.

Schlägt ein Teil endgültig fehl oder schlägt der Abschluss fehl, **wartet das SDK auf die noch laufenden Teile** und **bricht** den Upload dann **ab**, sodass kein Teil nach dem Abbruch ankommt. Der ursprüngliche Fehler wird geworfen. Es gibt **keine Fortsetzung**: Rufe `put()` erneut auf.

<Warning>
  Ein Multipart-Upload **prüft weder `overwrite: false` noch `checksum_sha256`**. Er ersetzt ein vorhandenes Objekt mit demselben Namen immer.
</Warning>

<Note>
  Ein Konto kann höchstens **32 offene Multipart-Uploads** haben (gemeinsam mit dem S3-Gateway); ein weiterer schlägt mit `TOO_MANY_OPEN_UPLOADS` fehl. Da Teile pro Konto 6 gleichzeitig gesendet werden, führe **jeweils nur einen großen Upload** aus.
</Note>

## Hochladen aus dem Browser

Sende den API-Schlüssel nie an einen Browser. Stattdessen erstellt dein Server ein kurzlebiges **Upload-Token**, und der Browser lädt damit hoch.

<Tabs>
  <Tab title="Server">
    ```typescript theme={"system"}
    import { SquareCloudBlob } from "@squarecloud/blob";

    const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);

    // e.g. inside your API route
    const { token } = await blob.uploadTokens.create({
        prefix: "avatars/",
        security_hash: true,
        max_size: 5 * 1024 * 1024,
        allowed_extensions: ["png", "jpg"],
    });
    // send only `token` to the browser
    ```
  </Tab>

  <Tab title="Browser">
    ```typescript theme={"system"}
    import { SquareCloudBlob } from "@squarecloud/blob";

    const upload = new SquareCloudBlob(token);
    const { url } = await upload.put(input.files[0], { name: "avatar" });
    ```
  </Tab>
</Tabs>

Ein mit einem Token erstellter Client kann **nur `put()` aufrufen**, einschließlich Multipart-Uploads. Jede andere Methode schlägt mit `403 UPLOAD_TOKEN_NOT_ALLOWED` fehl.

### `uploadTokens.create(options)`

Das Token legt jede Option fest, mit der es erstellt wurde.

| Option               | Typ                      | Beschreibung                                                                                     |
| -------------------- | ------------------------ | ------------------------------------------------------------------------------------------------ |
| `name`               | `string`                 | Legt den Objektnamen fest. Ohne ihn wird immer der Security-Hash angewendet.                     |
| `prefix`             | `string`                 | Legt das Präfix fest.                                                                            |
| `private`            | `boolean`                | Legt die Sichtbarkeit fest.                                                                      |
| `security_hash`      | `boolean`                | Hängt `_<hash>` an den Namen an.                                                                 |
| `expire`             | `string`                 | Ablauf des Objekts, wie bei `put()`.                                                             |
| `max_size`           | `number`                 | Maximale Dateigröße in Bytes.                                                                    |
| `allowed_extensions` | `string[]`               | 1 bis 20 Endungen.                                                                               |
| `metadata`           | `Record<string, string>` | Metadaten, die auf das hochgeladene Objekt angewendet werden.                                    |
| `expires_in`         | `number`                 | Lebensdauer des Tokens in Sekunden, 60 bis 3600 (Standard 900).                                  |
| `max_uses`           | `number`                 | Erlaubte Uploads, 1 bis 100 (Standard 1). Danach schlägt das Token mit `UPLOAD_TOKEN_USED` fehl. |

Die Methode gibt `{ token, expires_at, max_uses }` zurück. Die serverseitigen Regeln findest du unter [Upload Tokens](/de/blob-reference/endpoint/upload-tokens).

<Note>
  `uploadTokens.create()` ist ein Schreibvorgang und erhält **einen einzigen Versuch**: Er wird nie wiederholt.
</Note>