PlacePix Entwicklerhandbuch

Was ist PlacePix?

PlacePix ist ein selbstgehosteter Placeholder-Bilderdienst, der für Entwickler und Designteams entwickelt wurde. Im Gegensatz zu Drittanbieter-Placeholder-Diensten, die externe Netzwerkaufrufe erfordern und verschwinden können, läuft PlacePix vollständig auf Ihrer eigenen Infrastruktur. Legen Sie Bilder in Ordnern ab und erhalten Sie sofort URL-Endpunkte, die verkleinerte, gefilterte und formatierte Bilder ausliefern.

Der Dienst ist in Python mit FastAPI geschrieben und verwendet Pillow und OpenCV für die Bildverarbeitung. Er unterstützt Docker-Bereitstellung und S3-kompatiblen Objektspeicher.

Funktionen

• Zero Configuration — Bilder in Ordnern ablegen und loslegen
• Gesichterkennendes Zuschneiden — OpenCV erkennt und zentriert Gesichter
• Gradient- & SVG-Placeholder — keine Bilder erforderlich
• Social-Media-Voreinstellungen — Instagram, YouTube, TikTok-Größen integriert
• Farbensuche — Bilder finden, die zu Ihrer Markenfarbpalette passen
• Buchstaben-Avatare — deterministische Profilbilder aus Namen

Docker-Bereitstellungshandbuch

Der schnellste Weg, PlacePix auszuführen, ist mit Docker. Ein einzelner Befehl stellt den gesamten Dienst mit intelligentem Scannen, Farbextraktion und dem eingebetteten URL-Builder bereit.

Einzeilen-Bereitstellung

docker run -d -p 3000:3000 \
  -v ./images:/app/images \
  riadvice/placepix:latest

Docker Compose (Empfohlen)

services:
  placepix:
    image: riadvice/placepix:latest
    ports:
      - "3000:3000"
    volumes:
      - ./images:/app/images
      - ./data:/app/data
    environment:
      - HOST=0.0.0.0:3000
      - UPLOAD_ENABLED=true
      - WATERMARK_ENABLED=false
    restart: unless-stopped

Persistente Daten und Umgebung

Binden Sie sowohl /app/images (Ihre Bildbibliothek) als auch /app/data (Scan-Cache und Metadaten) ein, um den Zustand über Container-Neustarts hinweg zu erhalten. Konfigurieren Sie das Verhalten über Umgebungsvariablen oder eine .env-Datei.

OVHcloud S3-kompatibler Speicher

PlacePix unterstützt jedes S3-kompatible Backend. Für OVHcloud Object Storage setzen Sie:

S3_ENABLED=true
S3_ENDPOINT=https://s3.rbx.io.cloud.ovh.net
S3_ACCESS_KEY=ihr-key
S3_SECRET_KEY=ihr-secret
S3_BUCKET=ihr-bucket
S3_REGION=rbx

Gesichterkennendes intelligentes Zuschneiden

Standardmäßiges Zentrum-Zuschneiden kann bei Porträtfotografien durch Gesichter schneiden. PlacePix löst dies mit gesichterkennendem intelligentem Zuschneiden, unterstützt durch OpenCV Haar-Kaskaden.

Wie es funktioniert

Wenn eine Anfrage ?fit=smart enthält, scannt PlacePix das Bild mit OpenCV auf menschliche Gesichter. Werden Gesichter erkannt, wird das Zuschneide-Fenster verschoben, sodass der Gesichtsschwerpunkt so nah wie möglich an den goldenen Schnitt-Schnittpunkten liegt. Werden keine Gesichter gefunden, greift es auf Standard-Zentrum-Zuschneiden zurück.

API-Beispiele

# Gesichterkennendes Zuschneiden (erkennt und zentriert Gesichter)
/400/300/people?fit=smart

# Standard-Zentrum-Zuschneiden
/400/300/people?fit=crop

# Cover-Füllung (kann strecken)
/400/300/people?fit=cover

# Contain (Letterboxing)
/400/300/people?fit=contain

Wann Smart Crop verwenden

• Porträtfotografie und Headshots
• Teamseiten, wo Gesichter wichtig sind
• Social-Media-Thumbnails
• Jedes Szenario, wo geometrisches Zentrum-Zuschneiden die Komposition ruiniert

Gradient-Placeholder-API

Generieren Sie lineare und radiale Gradientenbilder on-the-fly, ohne Assets hochzuladen. Perfekt für Hero-Hintergründe, Ladezustände und Design-Mockups.

Endpunkt-Syntax

/gradient/{width}/{height}/{from_hex}/{to_hex}

Beispiele

# Einfacher linearer Gradient (oben nach unten)
/gradient/800/400/3b82f6/10b981

# 45-Grad-Winkel-Gradient
/gradient/800/400/e11d48/f59e0b?angle=45

# Radialer Gradient von der Mitte
/gradient/800/400/1e293b/64748b?gradient_type=radial

# Mit Ausgabeformat
/gradient/800/400/0ea5e9/ffffff?format=webp&quality=80

Parameter-Referenz

• {from_hex} / {to_hex} — Hex-Farben ohne #-Präfix
• ?angle=45 — linearer Winkel in Grad (0-360)
• ?gradient_type=radial — wechselt zu radialem Gradient
• ?format=webp — WebP-Ausgabe (kleinere Dateigröße)

SVG-Placeholder-Generator

SVG-Placeholder erfordern keine serverseitige Bildverarbeitung. Sie werden als Inline-SVG mit anpassbarer Hintergrundfarbe, Vordergrundfarbe und Textbeschriftung generiert.

Endpunkt

/svg/{width}/{height}?bg={hex}&fg={hex}&text={label}

Beispiele

# Standard Wireframe-Placeholder
/svg/400/300

# Benutzerdefinierte Markenfarben
/svg/400/300?bg=1c1917&fg=0ea5e9

# Mit benutzerdefiniertem Text
/svg/400/300?bg=0ea5e9&fg=ffffff&text=Hero+Section

Warum SVG?

• Dateigröße unter 500 Bytes
• Unendlich skalierbar ohne Qualitätsverlust
• Keine Server-Verarbeitungs-Overhead
• Perfekt für Wireframes und Low-Fidelity-Prototypen

Social-Media-Voreinstellungen

PlacePix enthält vordefinierte Abmessungen für beliebte Social-Media-Plattformen und Bildschirmgrößen. Verwenden Sie diese, um perfekt dimensionierte Placeholder-Bilder für Instagram, YouTube, TikTok, LinkedIn, X (Twitter) und Standard-Displays zu generieren.

Instagram

/preset/instagram-square/nature     # 1080x1080
/preset/instagram-portrait/nature  # 1080x1350
/preset/instagram-story/nature     # 1080x1920

YouTube

/preset/youtube-thumbnail/nature   # 1280x720
/preset/youtube-banner/nature      # 2560x423

TikTok

/preset/tiktok-video/nature        # 1080x1920 (9:16)

LinkedIn

/preset/linkedin-post/nature       # 1200x627

X (Twitter)

/preset/twitter-header/nature      # 1500x500

Bildschirmgrößen

/preset/mobile/nature              # 375x812
/preset/tablet/nature              # 768x1024
/preset/desktop/nature             # 1920x1080
/preset/4k/nature                  # 3840x2160

Long-Tail-Anwendungsfall: Instagram Story API

Wenn Sie ein Social-Media-Management-Tool erstellen und Instagram-Story-Größen-Placeholder-Bilder benötigen, verwenden Sie /preset/instagram-story/{category}. Kombinieren Sie mit ?fit=smart für Porträtfotos und ?format=webp&quality=70 für optimierte Auslieferung.

Farbensuche-API

Jedes Bild in PlacePix wird auf seine 3 dominantesten Farben gescannt. Sie können die gesamte Bibliothek nach Hex-Farben durchsuchen, um Bilder zu finden, die zu Ihrer Markenfarbpalette passen.

Endpunkte

# Bild mit bestimmter Hex-Farbe abrufen
/color/0ea5e9/400/300

# Beliebigen Endpunkt nach dominanter Farbe filtern
/400/300/nature?color=d97706

# Alle Bilder mit einer Farbe auflisten
/api/color/3b82f6

Wie die Farbscanning funktioniert

Beim Start extrahiert PlacePix die häufigsten Farben aus jedem Bild mit k-Means-Clustering im LAB-Farbraum. Dies erzeugt wahrnehmungsgenaue Übereinstimmungen anstelle von reinen RGB-Durchschnitten. Die Palette-Seite (/palette) visualisiert diese Farben und lässt Sie nach Farbtonkategorien browsen.

Ausrichtungsfilter

Filtern Sie zufällige Bilder nach ihrem nativen Seitenverhältnis vor der Auswahl. Das ist nützlich, wenn Sie Bilder benötigen, die natürlich in ein Layout passen — Landschaft für Header, Hochformat für Karten oder Quadrat für Vorschaubilder.

Endpunkte

# Landscape images (width > height)
/400/300?orientation=landscape

# Portrait images (height > width)
/400/300?orientation=portrait

# Squarish images (within 15% of 1:1 by default)
/400/300?orientation=squarish

# Combined with other filters
/400/300/nature?orientation=landscape&seed=spring
/color/0ea5e9/400/300?orientation=portrait
/api/color/3b82f6?orientation=landscape

Konfiguration

Die squarish-Toleranz ist über die Umgebungsvariable ORIENTATION_SQUARISH_TOLERANCE konfigurierbar (Standard: 0.15). Ein Wert von 0.15 bedeutet, dass Bilder mit einem Seitenverhältnis zwischen 0.85 und 1.15 als quadratisch betrachtet werden. Setzen Sie 0.0 für exakt 1:1.

Funktionsweise

PlacePix liest Bildabmessungen aus Datei-Headern während des initialen Scans (lokale Dateien) und während des Hintergrund-Metadaten-Scans (S3-Bilder). Die Abmessungen werden im Speicher gehalten und verwendet, um die Kandidatenliste vor der zufälligen oder deterministischen Auswahl zu filtern. Wenn keine passenden Bilder gefunden werden, wird ein 404 zurückgegeben.

Filter und Effekte

Wenden Sie Echtzeit-Filter und Effekte auf beliebige Bilder über Abfrageparameter an. Die gesamte Verarbeitung erfolgt serverseitig und wird für nachfolgende Anfragen zwischengespeichert.

Farbanpassungen

?grayscale=1               # Schwarz & Weiß
?sepia=1                   # Warmer Sepia-Ton
?tint=0ea5e9               # Hex-Farben-Overlay
?brightness=1.3            # 0,0 bis 2,0
?contrast=1.2              # 0,0 bis 2,0
?saturation=2.0            # 0,0 bis 2,0
?invert=true               # Farben invertieren
?posterize=4               # Farbstufen (1-8)
?duotone=ff0000,0000ff     # Zwei-Farben-Karte

Bildeffekte

?blur=2                    # Gaußscher Weichzeichner (1-10)
?sharpen=1.5               # Schärfemenge
?emboss=true               # 3D-Relief
?edges=sobel               # Kantenerkennung
?edges=canny               # Canny-Kanten
?halftone=4                # Punktmuster
?oil_painting=true         # Ölgemälde-Stil
?pencil_sketch=true        # Bleistiftzeichnung
?cartoon=true              # Cartoon-Effekt
?vignette=0.5              # Kanten abdunkeln (0-1)

Overlay-Parameter

?text=Hello+World          # Text-Overlay
?border=4,ffffff           # Rahmenbreite & -farbe
?watermark=1               # Konfiguriertes Wasserzeichen anwenden
?padding=20                # Interner Abstand

Avatar-Generator

Generiere deterministische Avatare aus jedem Namen oder jeder E-Mail. PlacePix unterstützt zwei Avatar-Typen: Buchstaben-Avatar (farbene Initialen) und Multiavatar (multikulturelle Vektor-Avatare).

Endpoint

/avatar/{size}/{name}
/avatar/{size}/{name}.{ext}

Parameter

• type — avatar type: letter (default) or multiavatar
• size — pixel size (e.g. 64, 128, 256)
• name — any string; used as seed for the avatar

Buchstaben-Avatar (type=letter)

• circle — crop to a circle shape
• border={width} — einen Rahmen hinzufügen
• border_color={hex} — Rahmenfarbe
• bg={hex} — override background color
• fg={hex} — override text/foreground color
• single=true — use only the first letter
• uppercase=false — preserve lowercase letters
• palette={name} — choose from flatui, material, pastel, neon, cool, warm

Multiavatar (type=multiavatar)

• env — include environment background (true by default, false to omit)
• part — specific part code (optional, e.g. 11)
• theme — specific theme code (optional, e.g. C)

Beispiele

# Simple 128px letter avatar
/avatar/128/John+Doe

# Circle letter avatar with custom border
/avatar/128/John+Doe?circle=true&border=2&border_color=ffffff

# Single initial, pastel palette
/avatar/64/Alice?single=true&palette=pastel

# SVG letter output (scalable, under 500 bytes)
/avatar/128/John+Doe.svg

# Multiavatar (multicultural vector avatar)
/avatar/128/Binx+Bond?type=multiavatar

# Multiavatar without environment background
/avatar/128/Binx+Bond?type=multiavatar&env=false

# Specific multiavatar version
/avatar/128/Binx+Bond?type=multiavatar&part=11&theme=C

Warum Buchstaben-Avatare verwenden?

• Keine externen Abhängigkeiten — kein Gravatar oder Avatar-Dienst eines Drittanbieters
• Deterministisch — derselbe Name erzeugt immer dieselbe Farbe
• SVG-Unterstützung — unendlich skalierbar, perfekt für HiDPI-Displays
• Sechs integrierte Farbpaletten für jedes Brand-Aesthetic

Warum Multiavatar verwenden?

• 12 Milliarden einzigartige multikulturelle Avatare
• Deterministisch — derselbe Name erzeugt immer denselben Avatar
• Reine SVG-Ausgabe — kleine Dateigröße, unendlich skalierbar
• Keine externen API-Aufrufe erforderlich

REST API-Kurzreferenz

Alle Endpunkte unterstützen CORS und geben Bilder mit Langzeit-Cache-Headern zurück. Base64-JSON-Ausgabe ist für kleine Thumbnails verfügbar.

Bild-Endpunkte

• GET /{width}/{height}/{category} — Zufälliges Bild aus Kategorie
• GET /{width}/{height} — Zufälliges Bild aus allen Kategorien
• GET /id/{id}/{width}/{height} — Bestimmtes Bild nach ID
• GET /ratio/{ratio}/{width}/{category} — Bild mit Seitenverhältnis
• GET /preset/{preset}/{category} — Social-Media-Voreinstellung
• GET /color/{hex}/{width}/{height} — Farbabgestimmtes Bild
• GET /gradient/{w}/{h}/{from}/{to} — Gradientenbild
• GET /svg/{width}/{height} — SVG-Placeholder
• GET /avatar/{size}/{name} — Buchstaben-Avatar (PNG/SVG)

Metadaten-Endpunkte

• GET /api/images — Kategorien und Summen auflisten
• GET /api/info/id/{id} — Bildmetadaten (Abmessungen, Farben, Format)
• GET /api/color/{hex} — Bilder mit einer Farbe

Health-Endpunkte

• GET /health — Liveness-Probe (Docker/K8s)
• GET /ready — Readiness-Probe (503 bis Bilder geladen)

Fachwissen und Referenzen

• Aktive Mitwirkende am Open-Source-Ökosystem seit 2008
• Der gesamte Code ist Open Source unter der MIT-Lizenz und auf GitHub überprüfbar

Häufig gestellte Fragen

Wie stelle ich PlacePix mit Docker bereit?

Führen Sie docker run -d -p 3000:3000 -v ./images:/app/images riadvice/placepix:latest aus. Binden Sie Ihren Bildordner ein und der Dienst startet sofort mit aktiviertem intelligentem Scannen.

Was ist gesichterkennendes intelligentes Zuschneiden?

PlacePix verwendet OpenCV Haar-Kaskaden, um Gesichter in Bildern zu erkennen. Wenn Sie ?fit=smart zu einer beliebigen URL hinzufügen, wird der Zuschneidebereich verschoben, um auf erkannte Gesichter zu zentrieren, anstatt das geometrische Zentrum zu verwenden. Wird kein Gesicht gefunden, greift es auf Standard-Zentrum-Zuschneiden zurück.

Kann ich Gradient-Placeholder-Bilder ohne Hochladen von Fotos generieren?

Ja. Der Endpunkt /gradient/{width}/{height}/{from}/{to} generiert Gradientenbilder vollständig aus URL-Parametern. Es sind keine hochgeladenen Bilder erforderlich. Sie können auch SVG-Placeholder mit /svg/{width}/{height} erstellen.

Wie generiere ich Instagram-Story-Größen-Placeholder-Bilder über die API?

Verwenden Sie den Preset-Endpunkt: /preset/instagram-story/{category}. Dies gibt ein 1080x1920-Bild zurück. Kombinieren Sie mit ?format=webp&quality=70 für optimierte Auslieferung und ?fit=smart für porträtsicheres Zuschneiden.

Unterstützt PlacePix S3-kompatiblen Objektspeicher?

Ja. PlacePix funktioniert mit OVHcloud Object Storage, AWS S3, MinIO und jedem S3-kompatiblen Anbieter. Konfigurieren Sie Endpunkt, Bucket, Access Key und Secret Key über Umgebungsvariablen.

Welche Ausgabeformate werden unterstützt?

WebP, AVIF, JPEG, PNG, SVG und Base64-JSON. Verwenden Sie .webp, .avif oder .png als Dateierweiterung oder fügen Sie ?format=webp als Abfrageparameter hinzu. AVIF erzeugt die kleinsten Dateien; PNG ist verlustfrei.

Ist PlacePix für kommerzielle Nutzung kostenlos?

Ja. PlacePix wird unter der MIT-Lizenz veröffentlicht und ist sowohl für persönliche als auch für kommerzielle Nutzung kostenlos. Da es selbstgehostet ist, gibt es keine Nutzungslimits, keine API-Schlüssel und keine Abrechnung pro Anfrage.