文档目录

图片审核(鉴黄)

最近更新: 2026-10-22

检测单张图片的违规程度。结果包括 L1(风险最低)到 L4(最露骨)四个等级各自的概率、概率最高的等级,以及在所选策略下"通过 / 违规"的判定。提交 HTTPS 图片 URL,异步获取结果。

模型接口价格
generalPOST /v1/predictions每个受理的任务扣 1 积分;任务失败时返还积分

相关资源:价格 · 积分 · 任务历史

请求

POST https://api.nsfwcheckapi.com/v1/predictions

Header Params

Authorizationstring必填

Bearer 加你的 API Key。

示例:
Bearer sk_…
Content-Typestring必填
可选值:
application/json
Idempotency-Keystring可选

建议填写。16~128 个字符:字母、数字、_ 或 -。只在重试完全相同的请求体时复用;重放会返回已有任务,不会重复扣费。见重试与幂等。

示例:
upload-8f2c1e7a9b3d4c5e

Body Params

modelstring可选

使用的模型。

可选值:
"general"
默认值:
"general"
inputobject必填

要检测的图片,包含 image。

input.imagestring必填

单张静态 JPEG、PNG 或 WebP 图片的公网 HTTPS URL。URL 不超过 4,096 字节;图片不超过 20 MiB,单边不超过 8,192 像素,总像素不超过 4,000 万。

示例:
"https://images.example.com/photo.jpg"
policyobject可选

结果的判定方式,包含 sensitivity。

默认值:
{"sensitivity": "standard"}
policy.sensitivitystring可选

"standard" 将 L3、L4 判为违规;"strict" 将 L2、L3、L4 判为违规。只影响 output.is_nsfw,不改变概率和等级。

可选值:
"standard"
"strict"
默认值:
"standard"
示例:
"strict"

上面未列出的字段、值为 null 的字段和重复的键都会被拒绝,返回 400 invalid_request。

图片 URL 规则

  • 只接受 https://,不能带用户名或密码,不能带 # 片段。
  • 不能是本机或内网地址,重定向的目标同样会检查。
  • 不支持 GIF、APNG 和动态 WebP。
  • 在任务结束前 URL 必须一直可访问。签名 URL 的完整查询参数也属于输入的一部分。

提交时就能发现的 URL 问题会返回 422 invalid_image_url,不会创建任务。下载或解码图片时发现的问题会让任务以 failed 结束,错误码为 invalid_image,并返还积分。

响应

状态码含义
201任务已受理,"status": "waiting"。Location 响应头是查询地址。之后发现的图片问题会出现在任务的 error 中。
200幂等重放:返回原任务的当前状态,并带响应头 Idempotent-Replayed: true。不会新建任务,也不会重复扣费。
400 401 402 409 413 422 429 503请求未被受理,不扣费。见错误码。

返回字段

字段类型说明
idstring任务 ID(UUID)。
modelstring"general"
statusstring"waiting"、"processing"、"succeeded" 或 "failed"。新任务为 "waiting"。
policy.sensitivitystring提交时的 "standard" 或 "strict"。
model_versionstring 或 null产生结果的模型版本,例如 "general-2026-08";在此之前为 null。
outputobject 或 null检测结果;status 为 "succeeded" 之前为 null。
errorobject 或 null仅在 status 为 "failed" 时有值。
created_atstring任务受理时间。
started_atstring 或 null开始处理的时间。
completed_atstring 或 null进入最终状态的时间。
urls.getstring查询这个任务的地址。

output 对象

status 为 "succeeded" 时出现。

字段类型说明
output.levelstring概率最高的等级:"L1"、"L2"、"L3" 或 "L4"。概率相同时取更高的等级。
output.probabilitiesobject各等级的概率:键为 L1~L4,值为 0~1 之间的数字。
output.is_nsfwboolean在该任务的策略下 output.level 被判为违规时为 true。

error 对象

status 为 "failed" 时出现,失败任务的积分会返还。

error.code含义
invalid_image图片无法下载或解码,或格式、尺寸不受支持。
processing_timeout任务提交后 10 分钟内未开始,或 20 分钟内未完成。
execution_failed任务未能完成。

等级与策略

策略只决定哪些等级算作违规,不会改变概率和等级,因此你可以保存原始输出,之后再按自己的规则判定。

等级"standard"(默认)"strict"
L1(风险最低)通过通过
L2通过违规
L3违规违规
L4(最露骨)违规违规

查询检测任务

GET https://api.nsfwcheckapi.com/v1/predictions/{id}

使用任务 id 和同一账户下的任意 API Key。status 为 "waiting" 或 "processing" 时 output 为 null:每 1~2 秒继续查询,遇到 429 时按 Retry-After 的秒数等待。status 为 "succeeded" 时读取 output,为 "failed" 时读取 error。详见查询任务详情。

curl 'https://api.nsfwcheckapi.com/v1/predictions/0f8e3c52-6d1a-4b7e-9c2f-5a1b3d4e6f70' \
  -H 'Authorization: Bearer YOUR_API_KEY'

代码示例

请求

curl -X POST 'https://api.nsfwcheckapi.com/v1/predictions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: upload-8f2c1e7a9b3d4c5e' \
  -d '{
    "model": "general",
    "input": { "image": "https://images.example.com/photo.jpg" },
    "policy": { "sensitivity": "standard" }
  }'

响应

201 Created,任务已受理:

{
  "id": "0f8e3c52-6d1a-4b7e-9c2f-5a1b3d4e6f70",
  "model": "general",
  "status": "waiting",
  "policy": { "sensitivity": "standard" },
  "model_version": null,
  "output": null,
  "error": null,
  "created_at": "2026-10-22T08:30:00.000Z",
  "started_at": null,
  "completed_at": null,
  "urls": {
    "get": "https://api.nsfwcheckapi.com/v1/predictions/0f8e3c52-6d1a-4b7e-9c2f-5a1b3d4e6f70"
  }
}

任务成功后,GET /v1/predictions/{id} 返回 200 OK:

{
  "id": "0f8e3c52-6d1a-4b7e-9c2f-5a1b3d4e6f70",
  "model": "general",
  "status": "succeeded",
  "policy": { "sensitivity": "standard" },
  "model_version": "general-2026-08",
  "output": {
    "level": "L1",
    "probabilities": { "L1": 0.94, "L2": 0.04, "L3": 0.01, "L4": 0.01 },
    "is_nsfw": false
  },
  "error": null,
  "created_at": "2026-10-22T08:30:00.000Z",
  "started_at": "2026-10-22T08:30:00.412Z",
  "completed_at": "2026-10-22T08:30:01.268Z",
  "urls": {
    "get": "https://api.nsfwcheckapi.com/v1/predictions/0f8e3c52-6d1a-4b7e-9c2f-5a1b3d4e6f70"
  }
}