本地 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——这也是它的默认状态。