watermarks-remover HTTP API速查手册：接入/inspect、/clean、/detect端点到你的产品（附curl与OpenAPI示例）
【免费下载链接】watermarks-removerA privacy-first app that strips AI watermarks from content you own.项目地址: https://gitcode.com/gh_mirrors/wa/watermarks-remover
watermarks-remover 是一个隐私优先的 AI 水印去除工具，能把文本、图片和文件中的 AI 来源标记（隐形 Unicode、C2PA/EXIF/XMP 元数据等）从你拥有的内容中剥离。它的清洗管线通过一个仅依赖 Python 标准库的 HTTP 服务对外提供——你的产品只需发几个 JSON 请求，就能接入完整的检查、检测与清洗能力，无需安装任何依赖。
本文是一份速查手册：3 个核心端点/inspect、/clean、/detect的请求格式、curl 示例、批量接口与 OpenAPI 规范，全部一次讲清。
一键启动：3 种方式把服务跑起来
服务入口是 service/scripts/server.py，默认监听http://127.0.0.1:8765（仅回环地址，面向可信网络设计）。
方式一：直接运行（Python 3.10+，零依赖）
python3 service/scripts/server.py --host 127.0.0.1 --port 8765 # 或者用 Makefile 目标：make serve方式二：Docker 核心镜像（预装 exiftool / qpdf / c2patool）
docker run --rm -p 127.0.0.1:8765:8765 --read-only --tmpfs /tmp watermarks-remover方式三：docker compose（可扩展检测器与重型后端）
docker compose up -d # 仅核心服务 docker compose --profile harness up -d # + MarkLLM / MarkDiffusioncompose 栈定义见 compose.yaml，核心镜像构建见 service/Dockerfile。启动后先探活：
curl -s "http://127.0.0.1:8765/health" # {"ok": true, "version": "..."}端点速查表：9 个路由一览
| 方法 | 路径 | 作用 | 关键返回 |
|---|---|---|---|
| GET | /health | 探活 + 版本 | ok、version |
| GET | /capabilities | 查询可用的可选工具与后端 | tools、scorers、pixel_backends |
| GET | /openapi.json | 动态生成的 OpenAPI 3.0.3 规范 | 完整契约文档 |
| POST | /inspect | 只检查，不修改文件 | kind、suspicious、report |
| POST | /detect | 运行水印检测器 | detections |
| POST | /clean | 清洗文件，返回清洗后字节 | cleaned（base64）、report |
| POST | /inspect/batch | 批量检查（默认 ≤50 个文件） | results[] |
| POST | /detect/batch | 批量检测 | results[] |
| POST | /clean/batch | 批量清洗 | results[] |
💡所有 POST 端点共用同一请求格式：文件以 base64 编码放进file字段，name字段提供原始文件名——服务先按扩展名、再按魔数（magic bytes）自动路由到文本 / 图片 / 容器 / 音视频管线，返回的kind取值为text/image/container/av（无法识别时为unknown）。
/inspect 端点：只读体检，不改动文件
适合在入库、上传前做一次"AI 来源体检"。文本会附带统计风格（stylometry）评分，suspicious字段给出是否可疑的综合判断：
WM="http://127.0.0.1:8765" curl -s -X POST "$WM/inspect" -H 'Content-Type: application/json' \ -d "{\"file\": \"$(base64 < shot.png | tr -d '\n')\", \"name\": \"shot.png\"}"响应示例（结构）：
{ "ok": true, "kind": "image", "suspicious": true, "report": { "...": "各项发现（C2PA、AI 元数据、统计评分等）" } }⚠️ 注意：/inspect支持可选的"detect": true标志，用于追加已配置的水印检测器结果——它可能调用外部 API 并把文本发送出去，因此是显式开启的选项。
/clean 端点：一键清洗，返回清洗后的文件
这是最核心的端点：传入 base64 文件，返回清洗后的 base64 字节 + 一份操作报告（做了哪些动作、统计数量）。
curl -s -X POST "$WM/clean" -H 'Content-Type: application/json' \ -d "{\"file\": \"$(base64 < notes.md | tr -d '\n')\", \"name\": \"notes.md\"}" # 响应中 "cleaned" 字段即清洗后的 base64 内容/clean 的可选参数（options）
完整白名单定义在 service/scripts/server.py#L86-L96——未在白名单中的选项会直接被拒绝（400），不会静默忽略：
| 选项 | 类型 | 用途 |
|---|---|---|
nfkc | boolean | 启用 NFKC 归一化清洗 |
aggressive_homoglyphs | boolean | 激进清理同形字符 |
keep_non_ai_metadata | boolean | 保留非 AI 元数据（图片/音视频） |
strip_all_metadata | boolean | 显式控制是否剥离全部元数据 |
also_layer_a_text | boolean | 容器内文本同时做 Unicode 层（Layer A）清洗 |
remove_pixel | string | ctrlregen/diffusion，像素级水印移除（需外部后端） |
detect_before/detect_after | boolean | 清洗前后各跑一次检测器，量化"洗掉了什么" |
deep_images | string | auto/always/lossless/never，处理 PDF 内嵌图片里的元数据 |
一个带选项的实际请求（清洗前后对比检测）：
curl -s -X POST "$WM/clean" -H 'Content-Type: application/json' \ -d "{\"file\": \"$(base64 < shot.png | tr -d '\n')\", \"name\": \"shot.png\", \"options\": {\"detect_before\": true, \"detect_after\": true}}"/detect 端点：只跑检测器，输出水印检测报告
检测与清洗是独立步骤，服务默认绝不调用任何供应商 API。/detect按文件类型分发：
- 文本→ 已配置的文本水印检测器 + 统计风格评分
- 图片→ SynthID 像素评分（需配置评分器）
- 音视频 / 容器→ 附带检查报告
curl -s -X POST "$WM/detect" -H 'Content-Type: application/json' \ -d "{\"file\": \"$(base64 < draft.txt | tr -d '\n')\", \"name\": \"draft.txt\"}" # 响应: {"ok": true, "kind": "text", "detections": [ ... ]}💡 检测器是"失败即软降级"（fail-soft）设计：未配置、超时或出错的检测器会返回{"available": false, "error": ...}，不会阻塞清洗流程。先用GET /capabilities查看当前部署里有哪些检测器可用：
curl -s "$WM/capabilities" | python3 -m json.tool批量端点：一次请求处理最多 50 个文件
/inspect/batch、/detect/batch、/clean/batch把单文件管线包在一个files数组里，默认上限 50 个（可用环境变量WATERMARKS_MAX_BATCH_FILES调整）：
curl -s -X POST "$WM/clean/batch" -H 'Content-Type: application/json' \ -d '{"files": [ {"file": "SGVsbG8=", "name": "a.md"}, {"file": "V29ybGQ=", "name": "b.txt"}]}'⚠️ 批量请求的关键特性：单个文件的失败（base64 损坏、未知选项、格式不识别）只体现在该条目的"ok": false+error字符串里，绝不中断整批处理——这是 server.py 的_batch_items明确保证的行为，非常适合对用户上传做并发清洗。
OpenAPI 规范：/openapi.json 随代码自动生成
这是本服务最值得称道的设计：GET /openapi.json返回的 OpenAPI 3.0.3 文档是从路由表 + 运行时配置动态生成的（见 server.py#L190-L25 注释与openapi_spec()实现），包含版本、当前允许的全部 options、认证要求，永远不会与实际端点漂移。
# 拉取契约，导入 Postman / Swagger Editor 即可生成客户端 curl -s "$WM/openapi.json"🎁 附带福利：当服务端配置了 API key 时，规范里会自动加入bearerAuth安全方案；CI 用openapi-spec-validator持续校验其合法性。
认证、安全与错误码速查
Bearer 认证：设置环境变量WATERMARKS_SERVER_API_KEY后，所有请求都必须携带：
curl -s -X POST "$WM/clean" \ -H "Authorization: Bearer $WATERMARKS_SERVER_API_KEY" \ -H 'Content-Type: application/json' -d '...'安全默认值：默认仅绑定回环地址（--host覆盖并打印警告）；JSON 请求体有大小上限（超限返回 413）；客户端文件名会被安全化，杜绝路径穿越。对外暴露时请经反向代理。
错误码速查
| 状态码 | 含义 | 常见原因 |
|---|---|---|
| 400 | 请求不合法 | base64 损坏、缺少file字段、unknown option（选项不在白名单）、deep_images取值错误 |
| 401 | 认证失败 | 缺少或错误的Authorization: Bearer <key> |
| 404 | 路径不存在 | 打错端点 |
| 413 | 请求体过大 | 超过 JSON 信封大小上限 |
| 500 | 内部错误 | 服务端异常（响应体只含internal error，细节见服务日志） |
排错时的可靠参考是 HTTP 服务测试套件 tests/test_http_server.py——每个端点的成功与失败路径都有对应用例，行为以它为准。
快速上手清单
make serve或docker run起服务，/health探活GET /capabilities确认本机可用的检测器与工具- 上传前用
/inspect体检，suspicious: true再走/clean - 清洗前后想留证据，加
"detect_before": true, "detect_after": true - 批量场景用
/clean/batch，逐条检查results[].ok - 需要生成客户端？
/openapi.json拉走即可
⚖️ 免责提示：watermarks-remover 面向你拥有或获授权处理的内容，用于隐私与卫生目的。统计型文本水印的去除是尽力而为（best-effort），报告中的"已验证移除"与"尽力而为"项请以
report字段为准。
延伸阅读
- 服务入口源码：service/scripts/server.py
- 部署方案（CLI + API in Docker）：docs/plans/ideas/deployment-docker-cli-api.md
- HTTP 服务行为测试：tests/test_http_server.py
- 本地自动启动服务（Windows）：docs/windows-autostart.md
【免费下载链接】watermarks-removerA privacy-first app that strips AI watermarks from content you own.项目地址: https://gitcode.com/gh_mirrors/wa/watermarks-remover
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
