本機 API

本機 API 將 JPGBoost 以 HTTP/JSON 服務的形式公開在您的裝置上，讓您可以從任何能夠傳送 HTTP 要求的語言中，控制匯入、設定與匯出操作。

啟用 API

API 預設處於關閉狀態，只需幾秒鐘即可啟用：

1. 開啟偏好設定（⌘,），然後進入本機 API分頁。
2. 勾選啟用核取方塊，伺服器會立即啟動。
3. 如有需要，可調整連接埠，預設值為 51823。
4. 複製緊接著顯示的驗證權杖。點選按鈕可隨時重新產生。

身分驗證

每個要求都必須攜帶包含您權杖的 Authorization 標頭。如果缺少該標頭，或權杖無效，API 會傳回 401。

TOKEN="<偏好設定中顯示的權杖>"
BASE="http://127.0.0.1:51823/v1"

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

路由參考

所有路由均以 /v1 為前綴，並傳回結構化的 JSON 資料：處理前後的大小、壓縮比，以及每個檔案可能出現的錯誤資訊。

逐步範例

查詢目前狀態

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

匯入檔案

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

修改畫質與格式

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

列出目前圖片

回應內容會針對每張圖片給出其識別碼、狀態、處理前後的大小、壓縮比，以及可能出現的錯誤資訊。

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

匯出整組圖片

匯出操作會在寫入檔案之前，等待任何正在進行的壓縮工作完成。此等待時間可透過 waitTimeoutSeconds 進行設定，預設為 30 秒。

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

清空清單

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

對特定圖片進行操作

每張圖片都有一個由 /v1/images 傳回的識別碼，藉此可以對其進行單獨操作。

# 針對某張圖片設定特定畫質
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quality": 92}' \
  "$BASE/images/<id>/quality"

# 將該圖片恢復為全域設定
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quality": null}' \
  "$BASE/images/<id>/quality"

# 將某張圖片匯出至指定路徑
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/path/to/output/photo.webp"}' \
  "$BASE/images/<id>/export"

# 從組中移除某張圖片
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/images/<id>"

透過 API 使用匯出設定檔

API 提供的設定檔清單與介面中的完全相同。有關優先順序規則，請參閱匯出設定檔指南。在 JPGBoost Free 中，1 個設定檔的限制在這裡同樣適用：POST /v1/profiles 會拒絕新建第二個設定檔，但仍接受以同名覆寫既有的設定檔。

# 建立或取代設定檔（同名 = 取代）
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Web JPEG", "format": "jpeg", "quality": 70, "destinationFolder": "/path/to/output"}' \
  "$BASE/profiles"

# 列出設定檔
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/profiles"

# 刪除設定檔（空格會在 URL 中轉為 %20）
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/profiles/Web%20JPEG"

# 將設定檔套用於全域設定
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"profile": "Web JPEG"}' "$BASE/settings"

# 匯出至設定檔的資料夾，無需再次指定 "folder"
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"profile": "Web JPEG"}' "$BASE/export"

驗證一切是否正常運作

應用程式內部的 Contents/Resources 目錄下，隨附了兩個指令碼。請在 JPGBoost 處於開啟狀態且已啟用 API 的情況下執行這些指令碼。若未預先設定 TOKEN 環境變數，指令碼會透過鍵盤要求輸入權杖；若已設定，則可將其串聯至持續整合流程中執行。

檢測套件

該指令碼以 ✓/✗ 輸出結果，用於檢測身分驗證、路由與參數驗證。預設情況下僅執行讀取操作；若為其提供一張圖片，還會執行一次完整的匯入與匯出流程。

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

"$SCRIPTS/test_local_api.sh"
"$SCRIPTS/test_local_api.sh" /path/to/image.png

引導式示範

以易於理解的方式，逐步示範上述完整流程：從缺少權杖時的拒絕回應開始，經過狀態查詢、匯入、設定與清單操作，最終完成匯出。

"$SCRIPTS/local_api_demo.sh" /path/to/image.png

安全性與隱私

• 伺服器僅監聽回送介面（127.0.0.1），也就是說，只能從您的 Mac 上進行存取，絕不會暴露在網際網路上。
• 任何圖片都不會經由網際網路傳輸。API 僅用於控制本機的壓縮引擎。
• 權杖在您的裝置上產生。若懷疑權杖可能已外洩（例如貼上到過共用指令碼中），請重新產生權杖。
• 不使用時請關閉 API——這也是它的預設狀態。