冻结BgFilter抠图服务契约

记录flat与complex模式及auto背景色行为补充服务器认证头和当前运行版本
2026-09-16 19:59:34 +08:00
parent 4b6df610af
commit f42d8ee811
1 changed files with 4 additions and 1 deletions
@@ -6,15 +6,18 @@

 ## 当前 BgFilter 契约

-生产服务器 `/root/BGfilter` 的服务契约为 `POST /remove-background` multipart：
+已登录生产服务器核对 `/root/BGfilter`，当前代码版本为 `f1a0833`，运行进程为 `python -m uvicorn app:app --host 0.0.0.0 --port 6006 --workers 1 --no-access-log`。服务契约为 `POST /remove-background` multipart：

 - `background_mode`：可选，`flat` 或 `complex`；
 - `screen_color`：可选，支持 `#RRGGBB`、`auto` 或省略；省略/`auto` 时由 BgFilter 从图片边框自动检测；
 - `complex` 模式忽略 `screen_color`；
 - 自动检测失败由 BgFilter 返回 400。
+- 若配置 `BGFILTER_AUTH_TOKEN`，必须发送 `X-Genarrative-Image-Token`；缺失或错误返回 401；未配置时该接口不在服务层做 token 校验。

 主站向 BgFilter 发送 `#RRGGBB` 时保留 `#`，`auto` 也原样发送，不做所谓的“hex 转换”。

+服务器实现细节：`screen_color` 在 `auto` 或省略时传入内部 pipeline 的 `None`，由边框颜色自动检测；`#RRGGBB` 才会经过颜色解析用于色键。`background_mode` 缺省在 BgFilter 侧为 `flat`，因此主站必须为 External v1 旧请求显式归一化为 `complex`，不能把 BgFilter 的默认值直接当成主站默认值。
+
 ## External v1 请求契约

 接口保持：