Medien

Die Media API ermöglicht das Hochladen, Verwalten und Organisieren von Bildern, Videos und Dokumenten.

Endpunkte

Methode	Endpunkt	Beschreibung
`GET`	`/api/v1/media`	Alle Medien auflisten
`POST`	`/api/v1/media`	Neue Datei hochladen
`GET`	`/api/v1/media/{id}`	Einzelnes Medium abrufen
`PUT`	`/api/v1/media/{id}`	Medium-Metadaten aktualisieren
`DELETE`	`/api/v1/media/{id}`	Medium löschen
`GET`	`/api/v1/media/{id}/status`	Upload-Status prüfen
`DELETE`	`/api/v1/media/batch`	Mehrere Medien löschen

Das Media-Objekt

{
  "id": "med_abc123",
  "organizationId": "org_xyz789",
  "projectId": "proj_def456",
  "filename": "hero-image.jpg",
  "originalFilename": "IMG_20260122_143022.jpg",
  "mimeType": "image/jpeg",
  "size": 245760,
  "width": 1920,
  "height": 1080,
  "url": "https://cdn.codefluss.com/media/org_xyz789/hero-image.jpg",
  "thumbnailUrl": "https://cdn.codefluss.com/media/org_xyz789/hero-image_thumb.jpg",
  "alt": "Modernes Bürogebäude bei Sonnenuntergang",
  "caption": "Unser Hauptsitz in Frankfurt",
  "folder": "bilder/hero",
  "tags": ["hero", "büro", "header"],
  "status": "ready",
  "createdAt": "2026-01-22T14:30:00Z",
  "updatedAt": "2026-01-22T14:30:00Z"
}

Attribute

Attribut	Typ	Beschreibung
`id`	string	Eindeutige Media-ID
`organizationId`	string	Zugehörige Organisation
`projectId`	string	Optionales Projekt
`filename`	string	Gespeicherter Dateiname
`originalFilename`	string	Ursprünglicher Dateiname
`mimeType`	string	MIME-Typ der Datei
`size`	integer	Dateigröße in Bytes
`width`	integer	Breite (bei Bildern/Videos)
`height`	integer	Höhe (bei Bildern/Videos)
`url`	string	Öffentliche URL
`thumbnailUrl`	string	Thumbnail-URL (bei Bildern)
`alt`	string	Alt-Text für Barrierefreiheit
`caption`	string	Bildunterschrift
`folder`	string	Ordnerpfad
`tags`	array	Tags für Suche/Filter
`status`	string	`uploading`, `processing`, `ready`, `error`
`createdAt`	string	Erstellungszeitpunkt
`updatedAt`	string	Letzte Aktualisierung

Unterstützte Formate

Bilder

Format	MIME-Type	Max. Größe
JPEG	`image/jpeg`	10 MB
PNG	`image/png`	10 MB
GIF	`image/gif`	5 MB
WebP	`image/webp`	10 MB
SVG	`image/svg+xml`	2 MB
AVIF	`image/avif`	10 MB

Videos

Format	MIME-Type	Max. Größe
MP4	`video/mp4`	100 MB
WebM	`video/webm`	100 MB

Dokumente

Format	MIME-Type	Max. Größe
PDF	`application/pdf`	20 MB

Medien auflisten

GET /api/v1/media

Query-Parameter

Parameter	Typ	Default	Beschreibung
`organizationId`	string	Pflicht	Organisations-ID
`projectId`	string	–	Filter nach Projekt
`folder`	string	–	Filter nach Ordner
`mimeType`	string	–	Filter nach MIME-Typ (Präfix)
`tags`	string	–	Komma-separierte Tags
`search`	string	–	Suche in Dateiname/Alt/Caption
`page`	integer	`1`	Seitennummer
`pageSize`	integer	`20`	Einträge pro Seite
`sortBy`	string	`createdAt`	`createdAt`, `filename`, `size`
`sortOrder`	string	`desc`	`asc`, `desc`

Beispiel-Request

curl -X GET "https://api.codefluss.com/v1/media?organizationId=org_xyz789&mimeType=image&pageSize=10" \
  -H "Authorization: Bearer cf_live_abc123..."

Beispiel-Response

{
  "success": true,
  "data": [
    {
      "id": "med_abc123",
      "filename": "hero-image.jpg",
      "mimeType": "image/jpeg",
      "size": 245760,
      "url": "https://cdn.codefluss.com/media/org_xyz789/hero-image.jpg",
      "thumbnailUrl": "https://cdn.codefluss.com/media/org_xyz789/hero-image_thumb.jpg",
      "status": "ready"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 10,
    "totalItems": 1,
    "totalPages": 1
  }
}

Datei hochladen

POST /api/v1/media
Content-Type: multipart/form-data

Request

curl -X POST "https://api.codefluss.com/v1/media" \
  -H "Authorization: Bearer cf_live_abc123..." \
  -F "file=@/path/to/image.jpg" \
  -F "organizationId=org_xyz789" \
  -F "projectId=proj_def456" \
  -F "folder=bilder/hero" \
  -F "alt=Beschreibung des Bildes" \
  -F "tags=hero,header"

Form-Felder

Feld	Typ	Pflicht	Beschreibung
`file`	file	Ja	Die hochzuladende Datei
`organizationId`	string	Ja	Ziel-Organisation
`projectId`	string	Nein	Optionales Projekt
`folder`	string	Nein	Zielordner
`alt`	string	Nein	Alt-Text
`caption`	string	Nein	Bildunterschrift
`tags`	string	Nein	Komma-separierte Tags

Response

{
  "success": true,
  "data": {
    "id": "med_ghi789",
    "filename": "image.jpg",
    "url": "https://cdn.codefluss.com/media/org_xyz789/image.jpg",
    "status": "processing"
  }
}

Upload-Status prüfen

Bei großen Dateien ist der Upload asynchron. Prüfen Sie den Status:

GET /api/v1/media/{id}/status

Response

{
  "success": true,
  "data": {
    "id": "med_ghi789",
    "status": "ready",
    "progress": 100,
    "url": "https://cdn.codefluss.com/media/org_xyz789/image.jpg",
    "thumbnailUrl": "https://cdn.codefluss.com/media/org_xyz789/image_thumb.jpg"
  }
}

Status-Werte

Status	Beschreibung
`uploading`	Datei wird hochgeladen
`processing`	Thumbnail/Optimierung wird erstellt
`ready`	Bereit zur Verwendung
`error`	Fehler bei der Verarbeitung

Medium aktualisieren

PUT /api/v1/media/{id}

Request-Body

{
  "alt": "Aktualisierter Alt-Text",
  "caption": "Neue Bildunterschrift",
  "folder": "bilder/archiv",
  "tags": ["archiv", "2026"]
}

Medium löschen

DELETE /api/v1/media/{id}

Response

{
  "success": true,
  "data": {
    "deleted": true,
    "id": "med_abc123"
  }
}

Batch-Löschung

DELETE /api/v1/media/batch

Request-Body

{
  "ids": ["med_abc123", "med_def456", "med_ghi789"]
}

Response

{
  "success": true,
  "data": {
    "deleted": 3,
    "failed": 0,
    "results": [
      { "id": "med_abc123", "deleted": true },
      { "id": "med_def456", "deleted": true },
      { "id": "med_ghi789", "deleted": true }
    ]
  }
}

Bildoptimierung

Hochgeladene Bilder werden automatisch optimiert:

Thumbnail: 200x200px (Crop)
Medium: 800px Breite
Large: 1600px Breite
Original: Unverändert

Optimierte URLs

Original:  https://cdn.codefluss.com/media/.../image.jpg
Thumbnail: https://cdn.codefluss.com/media/.../image_thumb.jpg
Medium:    https://cdn.codefluss.com/media/.../image_medium.jpg
Large:     https://cdn.codefluss.com/media/.../image_large.jpg

Speicherlimits

Plan	Speicher	Max. Dateien
Free	100 MB	100
Starter	5 GB	1.000
Professional	50 GB	10.000
Enterprise	Unbegrenzt	Unbegrenzt

Fehler

Code	Beschreibung
`400`	Ungültiges Dateiformat oder zu große Datei
`401`	Nicht authentifiziert
`402`	Speicherlimit erreicht
`403`	Keine Berechtigung
`404`	Medium nicht gefunden

Nächste Schritte

Sections – Medien in Sections verwenden
Blog – Medien in Blog-Einträgen