# Bilder

Die [Abo-Seite](https://docs.kalender-sync.de/abo-kalender/abo-seite/) zeigt ein **Logo** neben dem Namen und ein **Banner** oben. Beide lädst du als Rohbild hoch, also das Bild selbst als Request-Body, nicht als JSON oder Formular.

```
PUT    /v1/publisher/calendars/{calendar_id}/images/logo
PUT    /v1/publisher/calendars/{calendar_id}/images/banner
DELETE /v1/publisher/calendars/{calendar_id}/images/logo
DELETE /v1/publisher/calendars/{calendar_id}/images/banner
```

## Hochladen

```bash
curl -X PUT https://api.kalender-sync.de/v1/publisher/calendars/$KS_CAL/images/logo \
  -H "Authorization: Bearer $KS_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @logo.png
```

Wichtig ist `--data-binary`, damit curl das Bild unverändert schickt. Die Antwort ist `200 OK` mit dem vollständigen [Kalender](https://docs.kalender-sync.de/api/calendars/#die-antwort), darin die neue `logo_url` bzw. `banner_url`. Ein neues Bild ersetzt das alte.

| | Logo | Banner |
|---|---|---|
| Formate | PNG, JPEG, WebP | PNG, JPEG, WebP |
| Größe | bis 512 KB | bis 2 MB |
| Empfehlung | quadratisch, mindestens 192 × 192 px | etwa 3:1, mindestens 1200 px breit |

- **Content-Type:** `image/png`, `image/jpeg`, `image/webp` oder `application/octet-stream`. Ob es wirklich ein PNG, JPEG oder WebP ist, prüfen wir am Inhalt der Datei, nicht am Header.
- **Kein SVG.** SVG kann Skripte enthalten und wird deshalb abgelehnt.
- Die Seitenverhältnisse und Mindestgrößen sind Empfehlungen für eine gute Darstellung. Die API prüft nur Format und Dateigröße.

## Entfernen

```bash
curl -X DELETE https://api.kalender-sync.de/v1/publisher/calendars/$KS_CAL/images/banner \
  -H "Authorization: Bearer $KS_KEY"
```

Antwort `204 No Content`.

## Bild-URLs

`logo_url` und `banner_url` zeigen auf unsere eigene Domain, zum Beispiel

```
https://app.kalender-sync.de/api/public/subscribe/cal_XXXXXXXXXXXX/images/logo?v=…
```

Der Parameter `v` ändert sich mit jedem neuen Bild. So können Browser die Bilder lange zwischenspeichern und zeigen trotzdem nach einem Upload das neue. Besucher der Abo-Seite laden dabei nichts von fremden Servern.

## Fehler

| Code | Status | Wann |
|---|---|---|
| [`invalid_image`](https://docs.kalender-sync.de/api/errors/invalid_image/) | 400 | Leerer Body |
| [`image_too_large`](https://docs.kalender-sync.de/api/errors/image_too_large/) | 413 | Logo über 512 KB, Banner über 2 MB |
| [`unsupported_image_type`](https://docs.kalender-sync.de/api/errors/unsupported_image_type/) | 415 | Inhalt ist kein PNG, JPEG oder WebP (z. B. SVG, GIF) |
| [`unsupported_media_type`](https://docs.kalender-sync.de/api/errors/unsupported_media_type/) | 415 | Content-Type wird nicht angenommen |
| [`payload_too_large`](https://docs.kalender-sync.de/api/errors/payload_too_large/) | 413 | Body deutlich größer als 2 MB |