# 轻湖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）：

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

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

```bash
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）

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "decision": "review",
    "scores": { "nsfw": 0.883104, "sfw": 0.116896 },
    "thresholds": { "allow": 0.10, "block": 0.90 },
    "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）。处置权在调用方。 |
| `scores.nsfw` 可比性 | 分数跨重标定不可比较——保存分数时请连同当次 `thresholds` 一起保存。 |
| `thresholds` | 本次响应生效的阈值。阈值可能随时间重标定——保存分数时请连同阈值一起保存。 |
| `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 | 服务暂时不可用 | 不要当作「安全」（见失败方向） |

```json
{ "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），完整明文只在创建时展示一次。

```bash
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
```

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

```json
{ "code": 0, "message": "ok", "data": { "status": "ok", "service": "lite-nsfw-detector", "version": "1.3.0", "skill_version": "1.3.0" } }
```

## AI Agent Skill

安装指南：[`https://nsfwdetector.litelake.com/docs/skill.md`](/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` 环境变量）调用认证端点，享受按账号计的额度。