API 文档

程序化图片鉴权：一张图一次 POST，HTTP 状态码即失败类别。英文文档为权威版本。

🤖 AI Agent：请直接抓取下方 markdown 原文而不是本页——它们是唯一事实源。Skill 安装指南 /docs/api.md（EN）/docs/api.zhs.md（中文）/docs/skill.md

轻湖NSFW检测 API 文档

轻湖NSFW检测（Lite NSFW Detector）是轻湖（Lite Lake）提供的免费、免登录图片内容安全服务：上传一张图片，返回其中色情/裸露内容（NSFW）的概率分数与建议判定。处置策略由调用方决定——本服务不做任何拦截，也绝不存储用户图片。

产品首页：https://nsfwdetector.litelake.com/
AI Agent Skill：https://nsfwdetector.litelake.com/docs/skill.md

基础地址

https://nsfwdetector.litelake.com

这是当前部署的唯一公共入口，下文示例可直接照抄。

通用规则

免登录、无 API Key（匿名档）：10 次/分钟 + 30 次/天/IP。 需要更多额度？注册免费账号得 100 次/天，订阅 Pro 得 10000 次/天——然后用 API Key 调用（见下方「带 API Key 检测」）。429 响应带 Retry-After 头，请遵守。
隐私：图片仅在内存中分析后立即丢弃，不落盘、不入存储。
单图大小上限：50 MB。放行格式（按文件内容探测，不信任扩展名）：JPEG / PNG / WebP / BMP / TIFF / GIF。动图（GIF/WebP/APNG）只检测首帧，image.frames 会回显帧数。
尺寸上限按格式分层（均在解码之前拒绝，解压炸弹防护）：
- JPEG：长边 ≤ 30000 px 且总像素 ≤ 2 亿——单反/无反超大原图经降采样直解，无需预处理；
- 非 JPEG（PNG / WebP / BMP / TIFF / GIF）：长边 ≤ 8192 px 且总像素 ≤ 3600 万（全分辨率解码代价过高，超限文件直接廉价拒绝）。
失败方向：推理后端不可用时返回 503 + code 5001。请把它当作「结果未知、需要人工复核」，绝不要当作「安全」。

接口：单图检测

POST https://nsfwdetector.litelake.com/api/public/detect

两种传图方式二选一：

方式 A —— multipart 表单（curl -F）：

curl -F file=@/path/to/image.jpg https://nsfwdetector.litelake.com/api/public/detect

方式 B —— 原始字节直传（请求体即图片）：

curl --data-binary @/path/to/image.jpg -H "Content-Type: image/jpeg" \
  https://nsfwdetector.litelake.com/api/public/detect

可选请求头：X-Device-Id: <uuid>——合法 UUID（v4），用于设备维度防滥用；非法或缺失按「无设备号」处理。

成功响应（HTTP 200）

{
  "code": 0,
  "message": "ok",
  "data": {
    "decision": "review",
    "scores": { "nsfw": 0.883104, "sfw": 0.116896 },
    "thresholds": { "allow": 0.10, "block": 0.90 },
    "model": "marqo-nsfw-384",
    "model_version": "fp32-opset17-20260915",
    "image": {
      "sha256": "9f2c...",
      "format": "jpeg",
      "width": 800,
      "height": 600,
      "bytes": 123456,
      "frames": 1
    },
    "timing_ms": 61.3
  }
}

字段说明

字段	说明
`scores.nsfw` / `scores.sfw`	[0,1] 概率，两者之和约等于 1。按标签名取值，绝不要按下标猜：标签顺序反转是此类模型的历史头号事故。
`decision`	基于当前阈值的建议：`allow`（< 0.10）、`review`（灰区 0.10–0.90，建议人工复核）、`block`（≥ 0.90）。处置权在调用方。
`thresholds`	本次响应生效的阈值。分数不可跨模型版本比较——保存分数时必须同时保存 `model_version`。
`model` / `model_version`	模型标识，用于回溯与阈值重标定。
`image.sha256`	内容哈希——调用方可用它做自己的结果缓存（重复图片极多；本服务不缓存）。
`image.frames`	输入帧数；`> 1` 表示动图，仅首帧参与判定——是否拒收由调用方决定。
`timing_ms`	服务端单次推理耗时（毫秒）。

错误（HTTP 状态码即失败类别）

HTTP	code	含义	备注
400	4001	请求参数错误	缺 file、空文件、多文件、Content-Type 不对
400	4002	不支持的图片格式	非白名单格式
400	4003	文件过大	> 50 MB
400	4004	图片尺寸超限	按格式分层（JPEG 30000px/2 亿；非 JPEG 8192px/3600 万）
400	4005	图片无法解码	文件损坏、伪装类型
401	4011	API Key 无效	`/api/open/detect` 上 Key 缺失/格式非法/已吊销；不降级为匿名
429	4290	触发频率限制	每分钟；带 `Retry-After`
429	4291	触发日配额	每天；带 `Retry-After`
503	5001	推理服务不可用	不要当作「安全」（见失败方向）

{ "code": 4004, "message": "image edge exceeds limit" }

接口：带 API Key 检测

POST https://nsfwdetector.litelake.com/api/open/detect
Authorization: Bearer nsk_live_<32hex>

图片格式、请求体方式（multipart file= 或 image/* 原始字节）与响应结构都和匿名接口完全一致——只有认证与计量维度不同：

额度按账号计，不按 Key 计。 同一账号的多个 Key 共享同一份日额度。注册账号 100 次/天；Pro 10000 次/天（且 30 次/分钟）。
响应头回显账号额度：X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset（下一个 UTC 零点的 Unix 秒）与 X-Quota-Tier（free / pro）。
Key 缺失、格式非法、已吊销或不存在一律 401 + code 4011，绝不降级为匿名额度。 Key 在产品控制台创建（登录 → 控制台 → API Keys），完整明文只在创建时展示一次。

curl -H "Authorization: Bearer nsk_live_xxxx" -F file=@/path/to/image.jpg \
  https://nsfwdetector.litelake.com/api/open/detect

接口：健康检查

GET https://nsfwdetector.litelake.com/api/public/health

返回服务标识与版本（不探测推理链路；无限流）：

{ "code": 0, "message": "ok", "data": { "status": "ok", "service": "lite-nsfw-detector", "model": "marqo-nsfw-384", "version": "1.3.0", "skill_version": "1.3.0" } }

AI Agent Skill

安装指南：https://nsfwdetector.litelake.com/docs/skill.md——纯标准库 CLI（detect、detect --url、--json、--version，大文件自动压缩，可用 --raw/--compress 覆盖），Agent 可从 https://nsfwdetector.litelake.com/skill/SKILL.md 与 https://nsfwdetector.litelake.com/skill/nsfwdetector.py 自装。CLI 支持 --api-key（或 NSFWDETECTOR_API_KEY 环境变量）调用认证端点，享受按账号计的额度。