Local API

Local API 让您自己的软件通过 HTTP 控制正在运行的 Q-Booth——可以在同一台电脑上，也可以在局域网中的其他设备上。开启活动、引导宾客完成拍摄、打印、显示二维码，并随时读取拍照亭当前的状态。

快速开始

1. 打开应用设置窗口，进入高级 → Local API，打开开启 Local API。（如果看不到高级，请先打开显示全部设置。）
2. 密码留空会自动生成，也可以自行输入。默认端口为 8730。
3. 如需从其他设备调用，请打开允许网络中的其他设备。Windows 可能会询问一次是否允许 Q-Booth 通过防火墙——请选择允许。
4. 点击保存设置，然后点击打开测试页面。测试页面为每个命令提供一个按钮，并附有拍照亭自带的这份参考文档。

地址为 http://<拍照亭电脑>:8730（在拍照亭电脑本机上为 http://localhost:8730）。所有命令都位于 /api/v1/ 之下。

curl http://localhost:8730/api/v1/status -H "Authorization: Bearer 您的密码"

密码

除 GET /api/v1/commands 外，每次调用都需要密码。可用以下任一方式发送：

• Authorization: Bearer <密码>（推荐）
• X-QBooth-Key: <密码>
• 在网址中加 ?key=<密码>，适用于只能打开链接的工具

密码错误或缺失时返回 401。同一地址在一分钟内输错十次，将被封锁一分钟（429）。密码相当于操作员的钥匙——任何拿到它的人都能控制拍照亭，请妥善保管。

返回格式

读取类命令使用 GET，返回 200 和数据：

{ "ok": true, "data": { ... } }

操作类命令使用 POST，参数放在 JSON 正文（或查询字符串）中。也可以用 GET，方便只能发送 GET 的触发工具。操作被接受后，拍照亭一收到就返回 202——不会等待拍照、打印或宾客操作完成：

{ "ok": true, "accepted": "camera/capture" }

被拒绝的调用会说明原因，并附带可供程序判断的代码：

{ "ok": false, "error": { "code": "wrong_page", "message": "The booth is on the welcome page. This needs the Camera page." } }

API 不会把命令排队稍后执行。如果拍照亭当前状态不允许，会立即拒绝。错误信息始终为英文；请在程序中使用 code 进行判断。

状态

GET /api/v1/status 告诉您拍照亭当前所处的位置。执行操作后可定时调用来跟进结果——每 300 到 1000 毫秒一次即可。如果完全无法连接，说明 Q-Booth 没有运行（或 Local API 未开启）。

{
  "app":     { "name": "QBooth", "version": "5.9.1.0", "apiVersion": "1" },
  "event":   { "id": "1781706869_H5A4", "name": "Wedding" },
  "page":    "camera",
  "session": { "active": true, "templateId": "…", "templateName": "Strip 3" },
  "camera":  { "phase": "review", "shot": 3, "shots": 3, "captured": 3, "feed": "live", "retakesLeft": 1 },
  "result":  null,
  "busy":    { "dialog": false, "processing": false },
  "available": ["camera/retake", "camera/process", "session/end", "event/stop"]
}

一位宾客的完整流程

典型流程，每一步都在 status 中等待所示的页面或阶段：

命令

所有路径都以 /api/v1/ 开头。index 从 1 开始，顺序与宾客看到的卡片一致（左上方的图库在前）。id 和 index 二选一；如果两者都发送，以 id 为准。

错误

日志

每次调用都会写入应用日志文件夹 log\local_api\，每天一个文件：调用方地址、命令及其参数、返回结果以及被拒绝的原因。密码从不写入日志。成功的 status 轮询不会记录。

版本历史