API locale

L'API locale espone JPGBoost come servizio HTTP/JSON sulla tua macchina. Ti permette di controllare l'importazione, le impostazioni e l'esportazione da qualsiasi linguaggio in grado di inviare una richiesta HTTP.

Attivare l'API

L'API è disattivata per impostazione predefinita. Si attiva in pochi secondi:

1. Apri Impostazioni (⌘,), poi la scheda API locale.
2. Seleziona la casella di attivazione. Il server si avvia immediatamente.
3. Regola la porta se necessario. Il valore predefinito è 51823.
4. Copia il token di autenticazione mostrato subito sotto. Un pulsante permette di rigenerarlo in qualsiasi momento.

Autenticazione

Ogni richiesta deve includere l'intestazione Authorization con il tuo token. Senza di essa, o con un token non valido, l'API risponde 401.

TOKEN="<token mostrato in Impostazioni>"
BASE="http://127.0.0.1:51823/v1"

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

Riferimento delle rotte

Tutte le rotte hanno il prefisso /v1 e restituiscono JSON strutturato: dimensione prima e dopo, rapporto di compressione, e l'eventuale errore di ciascun file.

Esempi passo passo

Consultare lo stato attuale

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

Importare file

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"paths": ["/percorso/verso/immagine1.png", "/percorso/verso/immagine2.jpg"]}' \
  "$BASE/import"

Modificare la qualità e il formato

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

Elencare le immagini attuali

La risposta indica, per ogni immagine, il suo identificatore, il suo stato, la sua dimensione prima e dopo, il suo rapporto e l'eventuale errore.

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

Esportare il gruppo

L'esportazione attende che qualsiasi compressione in corso termini prima di scrivere i file. Questo tempo di attesa è configurabile con waitTimeoutSeconds, fissato a 30 secondi per impostazione predefinita.

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

Svuotare la lista

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

Agire su un'immagine specifica

Ogni immagine ha un identificatore, restituito da /v1/images. Permette di gestirla individualmente.

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

# Tornare all'impostazione globale per questa immagine
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quality": null}' \
  "$BASE/images/<id>/quality"

# Esportare una singola immagine in un percorso specifico
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/percorso/di/output/foto.webp"}' \
  "$BASE/images/<id>/export"

# Rimuovere un'immagine dal gruppo
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/images/<id>"

Profili di esportazione tramite l'API

L'API espone lo stesso elenco di profili dell'interfaccia. Consulta la guida Profili di esportazione per conoscere la regola di priorità. In JPGBoost Free, il limite di un solo profilo vale anche qui: POST /v1/profiles rifiuta la creazione di un secondo profilo, ma continua ad accettare la sovrascrittura del profilo esistente con lo stesso nome.

# Creare o sostituire un profilo (stesso nome = sostituzione)
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Web JPEG", "format": "jpeg", "quality": 70, "destinationFolder": "/percorso/di/output"}' \
  "$BASE/profiles"

# Elencare i profili
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/profiles"

# Eliminare un profilo (lo spazio diventa %20 nell'URL)
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/profiles/Web%20JPEG"

# Applicare un profilo alle impostazioni globali
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"profile": "Web JPEG"}' "$BASE/settings"

# Esportare nella cartella del profilo, senza indicare nuovamente "folder"
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"profile": "Web JPEG"}' "$BASE/export"

Verificare che tutto funzioni

Due script sono inclusi all'interno dell'applicazione, in Contents/Resources. Eseguili con JPGBoost aperto e l'API attivata. Richiedono il token da tastiera, a meno che la variabile d'ambiente TOKEN non sia già impostata, il che permette di concatenarli in un'integrazione continua.

Insieme di verifiche

Verifica l'autenticazione, l'instradamento e la validazione dei parametri, con un output ✓/✗. Solo lettura per impostazione predefinita; se gli viene fornita un'immagine, esegue anche un ciclo reale di importazione ed esportazione.

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

"$SCRIPTS/test_local_api.sh"
"$SCRIPTS/test_local_api.sh" /percorso/verso/immagine.png

Percorso guidato

Ripercorre passo passo l'intera sequenza descritta sopra in modo leggibile, dal rifiuto senza token fino all'esportazione finale, passando per lo stato, l'importazione, le impostazioni e la lista.

"$SCRIPTS/local_api_demo.sh" /percorso/verso/immagine.png

Sicurezza e privacy

• Il server ascolta solo sull'interfaccia di loopback (127.0.0.1), il che significa che è accessibile solo dal tuo Mac. Non è mai esposto a internet.
• Nessuna immagine viaggia su internet. L'API controlla solo il motore di compressione locale.
• Il token viene generato sulla tua macchina. Rigeneralo se pensi possa essere stato divulgato, ad esempio dopo averlo incollato in uno script condiviso.
• Disattiva l'API quando non la usi: è questo il suo stato predefinito.