图片审核(鉴黄)
最近更新: 2026-10-22
检测单张图片的违规程度。结果包括 L1(风险最低)到 L4(最露骨)四个等级各自的概率、概率最高的等级,以及在所选策略下"通过 / 违规"的判定。提交 HTTPS 图片 URL,异步获取结果。
| 模型 | 接口 | 价格 |
|---|---|---|
general | POST /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 | 请求未被受理,不扣费。见错误码。 |
返回字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 任务 ID(UUID)。 |
model | string | "general" |
status | string | "waiting"、"processing"、"succeeded" 或 "failed"。新任务为 "waiting"。 |
policy.sensitivity | string | 提交时的 "standard" 或 "strict"。 |
model_version | string 或 null | 产生结果的模型版本,例如 "general-2026-08";在此之前为 null。 |
output | object 或 null | 检测结果;status 为 "succeeded" 之前为 null。 |
error | object 或 null | 仅在 status 为 "failed" 时有值。 |
created_at | string | 任务受理时间。 |
started_at | string 或 null | 开始处理的时间。 |
completed_at | string 或 null | 进入最终状态的时间。 |
urls.get | string | 查询这个任务的地址。 |
output 对象
status 为 "succeeded" 时出现。
| 字段 | 类型 | 说明 |
|---|---|---|
output.level | string | 概率最高的等级:"L1"、"L2"、"L3" 或 "L4"。概率相同时取更高的等级。 |
output.probabilities | object | 各等级的概率:键为 L1~L4,值为 0~1 之间的数字。 |
output.is_nsfw | boolean | 在该任务的策略下 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" }
}'
import requests
response = requests.post(
"https://api.nsfwcheckapi.com/v1/predictions",
headers={
"Authorization": "Bearer YOUR_API_KEY",
"Idempotency-Key": "upload-8f2c1e7a9b3d4c5e",
},
json={
"model": "general",
"input": {"image": "https://images.example.com/photo.jpg"},
"policy": {"sensitivity": "standard"},
},
timeout=30,
)
task = response.json()
print(task["id"], task["status"])
const response = await fetch('https://api.nsfwcheckapi.com/v1/predictions', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
'Idempotency-Key': 'upload-8f2c1e7a9b3d4c5e',
},
body: JSON.stringify({
model: 'general',
input: { image: 'https://images.example.com/photo.jpg' },
policy: { sensitivity: 'standard' },
}),
});
const task = await response.json();
console.log(task.id, task.status);
响应
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"
}
}