<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 图片鉴黄

> 图片NSFW内容检测。支持本地NudeNet推理（零调用费）及百度/腾讯/阿里云端三家，统一返回 decision（block/review/pass）+ 分类得分 + 检测框。

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `image-nsfw` |
| 接口名称 | 图片鉴黄 |
| 接口地址 | `https://v1.apizero.cn/api/image-nsfw` |
| 请求方法 | `POST` |
| 分类 | ai |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 2 req/s |
| 每日免费额度 | 10 次（已认证用户） |
| 匿名每日额度 | 0 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

调用必须带 apikey 参数（query 或 form-data 均可），形如 ?apikey=sk_...。已登录用户每日 10 次免费，不开放匿名访问。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `image_url` | `string` | 否 | 图片HTTP(S) URL（与image_b64二选一） | `https://example.com/photo.jpg` |
| `image_b64` | `string` | 否 | 图片base64（兼容data:URI） | — |
| `backend` | `string` | 否 | 检测后端：auto/nudenet/baidu/tencent/aliyun | `auto` |
| `timeout` | `int` | 否 | 超时秒（3~60） | — |

## 5. 请求示例 (cURL)

```bash
curl -X POST "https://v1.apizero.cn/api/image-nsfw" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "image_url": "https://example.com/photo.jpg",
  "image_b64": "<image_b64>",
  "backend": "auto",
  "timeout": ""
}'
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `code` | `string` | 业务码："200"=成功；"0001"=通用错误；"0010"=未配置后端；"0510"=本地服务不可达 | — |
| `desc` | `string` | 业务码描述（成功为 success） | — |
| `backend` | `string` | 实际使用的检测后端：nudenet / marqo / nudenet+marqo / baidu / tencent / aliyun | — |
| `elapsed_ms` | `int` | 服务端检测耗时（毫秒） | — |
| `input` | `object` | 输入图片信息：type / source / size_bytes / sha256 / mime / width / height | — |
| `decision` | `string` | 决策：block=拦截 / review=人审 / pass=放行 | — |
| `label` | `string` | 主标签：porn / sexy / normal | — |
| `score` | `float` | 主标签置信度（0~1） | — |
| `categories` | `object` | 三档概率：porn / sexy / normal | — |
| `detections` | `array` | NudeNet 部位级检出框（cls/score/box）；非 NudeNet 后端可能为空数组 | — |
| `raw` | `object` | 各后端原始返回（调试用，可选） | — |
| `tips` | `string` | 服务提示文案 | — |

## 7. 响应示例

```json
{
  "code": 200,
  "desc": "success",
  "backend": "nudenet",
  "elapsed_ms": 115,
  "input": {
    "type": "url",
    "source": "https://i0.hdslb.com/bfs/article/922692ab728ebb5f284f64296f3590a0959110a3.jpg",
    "size_bytes": 993377,
    "sha256": "f9a414bd6925f6c870e18d75252cbd764ce964fbd20387639577c9455db5a598",
    "mime": "image/jpeg",
    "width": 1080,
    "height": 1920
  },
  "decision": "pass",
  "label": "normal",
  "score": 0.8511,
  "categories": {
    "porn": 0,
    "sexy": 0,
    "normal": 1
  },
  "detections": [
    {
      "cls": "FACE_FEMALE",
      "score": 0.8511,
      "box": [
        381,
        291,
        528,
        575
      ]
    }
  ],
  "raw": {
    "nudenet": [
      {
        "class": "FACE_FEMALE",
        "score": 0.8510541915893555,
        "box": [
          381,
          291,
          528,
          575
        ]
      }
    ]
  },
  "notes": [],
  "tips": "极数本源 · https://apizero.cn"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `200` | `—` | 成功 |
| `4000` | `—` | 参数错误：必须提供 image_url 或 image_b64 |
| `4011` | `—` | 后端凭证缺失：百度 / 腾讯 / 阿里 AK·SK 未提供 |
| `4001` | `—` | 不支持的 backend 取值（应为 auto/local/baidu/tencent/aliyun） |
| `4015` | `—` | API Key 缺失或非法（v1 网关层） |
| `4044` | `—` | 接口已下线（v1 网关层） |
| `5020` | `—` | 未配置任何后端：本地 server.py 未运行且未提供云端凭证 |
| `5021` | `—` | 本地 server.py 不可达（连接被拒 / 超时 / 异常响应） |

## 9. 变更日志

- **1.0.0** (2026-05-08)
  - 首次上线
  - 支持NudeNet本地推理+百度/腾讯/阿里三家云端

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/image-nsfw`

Source: `https://apizero.cn/aidocs/image-nsfw/raw.md`
Last updated: 2026-05-11T16:15:07+08:00