ローカル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"

# 1枚の画像を特定のパスへ書き出し
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は2つ目の新規作成を拒否しますが、同じ名前による既存プロファイルの上書きは引き続き受け付けます。

# プロファイルの作成または置き換え(同名 = 置き換え)
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内、アプリ内部に2つのスクリプトが含まれています。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を無効にしてください。これがデフォルトの状態です。