Локальный 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": ["/путь/к/изображению1.png", "/путь/к/изображению2.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": "/путь/к/выводу", "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": "/путь/к/выводу/фото.webp"}' \
  "$BASE/images/<id>/export"

# Удаление изображения из группы
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/images/<id>"

Профили экспорта через API

API предоставляет тот же список профилей, что и интерфейс. См. руководство Профили экспорта, чтобы узнать правило приоритета. В JPGBoost Free ограничение в один профиль действует и здесь: 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": "/путь/к/выводу"}' \
  "$BASE/profiles"

# Список профилей
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/profiles"

# Удаление профиля (пробел становится %20 в URL)
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" /путь/к/изображению.png

Пошаговый сценарий

Проходит шаг за шагом всю описанную выше последовательность в удобочитаемой форме, от отказа без токена до финального экспорта, через статус, импорт, настройки и список.

"$SCRIPTS/local_api_demo.sh" /путь/к/изображению.png

Безопасность и конфиденциальность

• Сервер слушает только на интерфейсе обратной связи (127.0.0.1), то есть доступен только с вашего Mac. Никогда не выставляется в интернет.
• Ни одно изображение не проходит через интернет. API управляет только локальным движком сжатия.
• Токен генерируется на вашей машине. Перегенерируйте его, если считаете, что он мог стать известным, например после вставки в общий скрипт.
• Отключайте API, когда не используете его: это его состояние по умолчанию.