Lokale API

Die lokale API stellt JPGBoost als HTTP/JSON-Dienst auf deinem Rechner bereit. Sie ermöglicht dir, Import, Einstellungen und Export von jeder Sprache aus zu steuern, die eine HTTP-Anfrage senden kann.

Die API aktivieren

Die API ist standardmäßig deaktiviert. Sie wird in Sekunden aktiviert:

1. Öffne Einstellungen (⌘,), dann den Reiter Lokale API.
2. Aktiviere das Kontrollkästchen. Der Server startet sofort.
3. Passe bei Bedarf den Port an. Der Standardwert ist 51823.
4. Kopiere den direkt darunter angezeigten Authentifizierungstoken. Eine Schaltfläche erlaubt es, ihn jederzeit neu zu erzeugen.

Authentifizierung

Jede Anfrage muss den Header Authorization mit deinem Token enthalten. Ohne ihn, oder mit einem ungültigen Token, antwortet die API mit 401.

TOKEN="<in Einstellungen angezeigter Token>"
BASE="http://127.0.0.1:51823/v1"

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/status"

Routenreferenz

Alle Routen haben das Präfix /v1 und liefern strukturiertes JSON zurück: Größe vorher und nachher, Komprimierungsverhältnis und den möglichen Fehler jeder Datei.

Schritt-für-Schritt-Beispiele

Den aktuellen Status abfragen

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/status"

Dateien importieren

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"paths": ["/pfad/zu/bild1.png", "/pfad/zu/bild2.jpg"]}' \
  "$BASE/import"

Qualität und Format ändern

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quality": 80, "format": "webp"}' \
  "$BASE/settings"

Aktuelle Bilder auflisten

Die Antwort gibt für jedes Bild seine Kennung, seinen Status, seine Größe vorher und nachher, sein Verhältnis und den möglichen Fehler an.

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/images"

Die Gruppe exportieren

Der Export wartet, bis eine laufende Komprimierung beendet ist, bevor die Dateien geschrieben werden. Diese Wartezeit ist mit waitTimeoutSeconds konfigurierbar, standardmäßig auf 30 Sekunden festgelegt.

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder": "/pfad/zur/ausgabe", "waitTimeoutSeconds": 30}' \
  "$BASE/export"

Die Liste leeren

curl -s -X POST -H "Authorization: Bearer $TOKEN" "$BASE/clear"

Auf ein bestimmtes Bild einwirken

Jedes Bild hat eine von /v1/images zurückgegebene Kennung. Sie ermöglicht es, es einzeln zu behandeln.

# Spezifische Qualität eines Bildes
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quality": 92}' \
  "$BASE/images/<id>/quality"

# Zur globalen Einstellung für dieses Bild zurückkehren
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quality": null}' \
  "$BASE/images/<id>/quality"

# Ein einzelnes Bild in einen bestimmten Pfad exportieren
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/pfad/zur/ausgabe/foto.webp"}' \
  "$BASE/images/<id>/export"

# Ein Bild aus der Gruppe entfernen
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/images/<id>"

Exportprofile über die API

Die API stellt dieselbe Profilliste wie die Oberfläche bereit. Siehe die Anleitung Exportprofile, um die Prioritätsregel kennenzulernen. In JPGBoost Free gilt das Limit von einem Profil auch hier: POST /v1/profiles lehnt das Anlegen eines zweiten Profils ab, akzeptiert aber weiterhin das Überschreiben des vorhandenen Profils unter demselben Namen.

# Ein Profil erstellen oder ersetzen (gleicher Name = Ersetzung)
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Web JPEG", "format": "jpeg", "quality": 70, "destinationFolder": "/pfad/zur/ausgabe"}' \
  "$BASE/profiles"

# Profile auflisten
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/profiles"

# Ein Profil löschen (das Leerzeichen wird zu %20 in der URL)
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/profiles/Web%20JPEG"

# Ein Profil auf die globalen Einstellungen anwenden
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"profile": "Web JPEG"}' "$BASE/settings"

# In den Ordner des Profils exportieren, ohne "folder" erneut anzugeben
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"profile": "Web JPEG"}' "$BASE/export"

Überprüfen, dass alles funktioniert

Zwei Skripte sind innerhalb der Anwendung enthalten, unter Contents/Resources. Führe sie aus, während JPGBoost geöffnet und die API aktiviert ist. Sie fragen den Token über die Tastatur ab, es sei denn, die Umgebungsvariable TOKEN ist bereits gesetzt, was es ermöglicht, sie in einer kontinuierlichen Integration zu verketten.

Prüfsuite

Überprüft Authentifizierung, Routing und Parametervalidierung, mit einer ✓/✗-Ausgabe. Standardmäßig nur lesend; wird ihr ein Bild übergeben, führt sie auch einen echten Import-Export-Zyklus durch.

SCRIPTS=/Applications/JPGBoost.app/Contents/Resources

"$SCRIPTS/test_local_api.sh"
"$SCRIPTS/test_local_api.sh" /pfad/zu/bild.png

Geführter Durchlauf

Durchläuft Schritt für Schritt die oben beschriebene vollständige Abfolge in lesbarer Form, von der Ablehnung ohne Token bis zum finalen Export, über Status, Import, Einstellungen und Liste.

"$SCRIPTS/local_api_demo.sh" /pfad/zu/bild.png

Sicherheit und Datenschutz

• Der Server hört nur auf der Loopback-Schnittstelle (127.0.0.1), was bedeutet, dass er nur von deinem Mac aus erreichbar ist. Niemals dem Internet ausgesetzt.
• Kein Bild reist über das Internet. Die API steuert nur die lokale Komprimierungs-Engine.
• Der Token wird auf deinem Rechner erzeugt. Erzeuge ihn neu, wenn du denkst, dass er bekannt geworden sein könnte, zum Beispiel nachdem du ihn in ein geteiltes Skript eingefügt hast.
• Deaktiviere die API, wenn du sie nicht verwendest: Das ist ihr Standardzustand.