API locale

L'API locale expose JPGBoost sous forme de service HTTP/JSON sur votre machine. Elle permet de piloter l'import, les réglages et l'export depuis n'importe quel langage capable d'envoyer une requête HTTP.

Activer l'API

L'API est désactivée par défaut. Elle s'active en quelques secondes :

1. Ouvrez Réglages (⌘,) puis l'onglet API locale.
2. Cochez la case d'activation. Le serveur démarre aussitôt.
3. Ajustez le port si nécessaire. La valeur par défaut est 51823.
4. Copiez le jeton d'authentification affiché juste en dessous. Un bouton permet de le régénérer à tout moment.

Authentification

Chaque requête doit porter l'en-tête Authorization avec votre jeton. Sans lui, ou avec un jeton invalide, l'API répond 401.

TOKEN="<jeton affiché dans Réglages>"
BASE="http://127.0.0.1:51823/v1"

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

Référence des routes

Toutes les routes sont préfixées par /v1 et renvoient du JSON structuré : taille avant et après, ratio de compression, et erreur éventuelle pour chaque fichier.

Exemples pas à pas

Connaître l'état courant

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

Importer des fichiers

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"paths": ["/chemin/vers/image1.png", "/chemin/vers/image2.jpg"]}' \
  "$BASE/import"

Changer la qualité et le format

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

Lister les images en cours

La réponse donne, pour chaque image, son identifiant, son état, sa taille avant et après, son ratio et l'erreur éventuelle.

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

Exporter le lot

L'export attend la fin de la compression en cours avant d'écrire les fichiers. Ce délai d'attente est réglable avec waitTimeoutSeconds, fixé à 30 secondes par défaut.

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

Vider la liste

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

Agir sur une image précise

Chaque image possède un identifiant, renvoyé par /v1/images. Il permet de la traiter individuellement.

# Qualité propre à une image
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quality": 92}' \
  "$BASE/images/<id>/quality"

# Revenir au réglage global pour cette image
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quality": null}' \
  "$BASE/images/<id>/quality"

# Exporter une seule image vers un chemin précis
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/chemin/de/sortie/photo.webp"}' \
  "$BASE/images/<id>/export"

# Retirer une image du lot
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/images/<id>"

Profils d'export via l'API

L'API expose la même liste de profils que l'interface. Voir le guide Profils d'export pour la règle de priorité. Sur JPGBoost Free, la limite d'un seul profil s'applique aussi ici : POST /v1/profiles refuse la création d'un second profil, mais accepte toujours l'écrasement du profil existant par le même nom.

# Créer ou remplacer un profil (même nom = écrasement)
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Web JPEG", "format": "jpeg", "quality": 70, "destinationFolder": "/chemin/de/sortie"}' \
  "$BASE/profiles"

# Lister les profils
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/profiles"

# Supprimer un profil (l'espace devient %20 dans l'URL)
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/profiles/Web%20JPEG"

# Appliquer un profil aux réglages globaux
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"profile": "Web JPEG"}' "$BASE/settings"

# Exporter vers le dossier du profil, sans repasser "folder"
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"profile": "Web JPEG"}' "$BASE/export"

Vérifier que tout fonctionne

Deux scripts sont livrés dans l'application, sous Contents/Resources. Lancez-les avec JPGBoost ouvert et l'API activée. Ils demandent le jeton au clavier, sauf si la variable d'environnement TOKEN est déjà définie, ce qui permet de les enchaîner dans une intégration continue.

Suite de vérifications

Contrôle l'authentification, le routage et la validation des paramètres, avec une sortie ✓/✗. En lecture seule par défaut ; en lui passant une image, elle effectue en plus un véritable cycle d'import et d'export.

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

"$SCRIPTS/test_local_api.sh"
"$SCRIPTS/test_local_api.sh" /chemin/vers/image.png

Parcours guidé

Déroule pas à pas la séquence complète décrite plus haut de manière lisible, depuis le refus sans jeton jusqu'à l'export final, en passant par l'état, l'import, les réglages et la liste.

"$SCRIPTS/local_api_demo.sh" /chemin/vers/image.png

Sécurité et confidentialité

• Le serveur n'écoute que sur l'interface de bouclage (127.0.0.1), c'est-à-dire qu'il n'est accessible que depuis votre Mac. Il n'est jamais exposé à Internet.
• Aucune image ne transite par Internet. L'API pilote uniquement le moteur de compression exécuté en local.
• Le jeton est généré sur votre machine. Régénérez-le si vous pensez qu'il a pu être divulgué, par exemple après l'avoir collé dans un script partagé.
• Désactivez l'API lorsque vous ne l'utilisez pas : c'est son état par défaut.