适用场景与接口概述图片鉴黄NSFW内容检测是内容审核管线的核心环节。无论是用户头像、帖子配图还是直播截图都需在合规前提下自动识别涉黄、性感或正常内容。本接口支持本地NudeNet推理及百度/腾讯/阿里三家云端引擎通过统一的decision字段block、review、pass和分类得分给出结果同时附带检测框坐标用于定位。本文并不介绍接口功能本身而是站在排错角度从请求构造、参数校验、返回值解读、异常处理到工程化落地逐一拆解容易踩坑的环节。接口能力边界与QPS说明请求地址:POST https://v1.apizero.cn/api/image-nsfwQPS限制: 2次/秒。超出会返回429 Too Many Requests需实现重试或队列。超时范围: 支持timeout参数3~60秒默认值依赖后端本地NudeNet通常3-5秒云端可能更长。图片源: 支持HTTP/HTTPS URL 或 base64含data:URI。单次请求只处理一张图片数组结构实际是对单个对象封装。常见误区直接复制文档中的[{}]数组但不理解其含义导致请求体被包装成数组而非对象。实际只需传入一个对象即可参照curl示例。请求参数详解与鉴权参数表参数名类型必填说明示例image_urlstring条件必填图片HTTP(S) URL与image_b64二选一https://example.com/photo.jpgimage_b64string条件必填图片base64编码可包含data:image/...;base64,前缀–backendstring否引擎选择auto默认、nudenet、baidu、tencent、aliyun。auto优先用本地NudeNetautotimeoutnumber否超时秒数3~60。空字符串表示用默认推荐显式设值10鉴权方式请求头需携带X-API-Key值为用户API密钥。密钥管理通常在平台个人中心。常见错误忘记添加X-API-Key头返回401 Unauthorized。Header名拼写错误如X-API-KEY大小写不敏感但建议严格按文档。密钥过期或未生成返回403 Forbidden。curl示例与常见接入错误可复制示例请替换API Key和图片URLcurl -sS \ -X POST \ -H X-API-Key: YOUR_API_KEY \ -H Content-Type: application/json \ -d { image_url: https://example.com/photo.jpg, backend: auto, timeout: 10 } \ https://v1.apizero.cn/api/image-nsfw容易踩的坑JSON格式错误-d后的JSON用单引号包裹时内部双引号不能转义。若JSON中包含单引号极少见需转成\u0027。未设置 Content-Type虽然某些客户端会自动推测但显式指定application/json更安全。图片URL不可访问返回400错误描述invalid image url。确保URL可公开访问、无重定向、非本地127.0.0.1/localhost。base64乱码使用image_b64时必须正确编码且不含换行符。推荐在发送前去掉\n。backend拼写错误例如nudenet写成了nude-net。接口会返回400并提示invalid backend。返回值解读与决策逻辑响应结构成功200{ code: 200, desc: success, decision: pass, label: normal, score: 0.8511, categories: { normal: 1, porn: 0, sexy: 0 }, detections: [ { box: [381, 291, 528, 575], cls: FACE_FEMALE, score: 0.8511 } ], backend: nudenet, elapsed_ms: 115, input: { source: https://..., type: url, mime: image/jpeg, size_bytes: 993377, width: 1080, height: 1920, sha256: ... }, raw: {}, tips: 极数本源 · https://apizero.cn, notes: [] }关键字段排错decision:pass表示通过review需人工复核block表示违规。如果预期pass但得到block检查图片内容或尝试切换backend不同引擎敏感度不同。categories: 分数在0~1之间且三个分类概率之和≈1。若出现大于1或负数可能是编码错误极少见可联系支持。detections只有本地NudeNet (nudenet) 会返回此字段。云端引擎的原始结果在raw字段中。如果detections为空数组但decision为pass说明没有检测到敏感区域属于正常。elapsed_ms: 实际耗时。若远超timeout设置值说明后端可能超时但接口仍返回了结果视后端机制建议增大超时或换用本地引擎。input.sha256: 图片内容的哈希值可用于缓存或去重。若两次请求返回不同哈希值说明图片内容有变化。错误码列表HTTP状态码错误描述常见原因处理建议400invalid request bodyJSON解析失败检查JSON格式确保无多余逗号400invalid image urlURL无法访问或非图片测试URL是否公开、响应头含图片类型400invalid backendbackend值不在合法范围内只允许auto/nudenet/baidu/tencent/aliyun400invalid timeouttimeout超出 3-60设值在范围内401unauthorized缺少或无效API Key检查Header名称与密钥403forbiddenAPI Key无权限或已过期检查账户状态429too many requestsQPS超限添加请求间隔或重试逻辑500backend error后端引擎异常重试或切换backend504gateway timeout处理超时增大timeout或减小图片尺寸高频错误与排错指南错误1返回400但请求体看似正确检查点是否将整个对象包裹在数组[{}]内文档示例是数组格式但实际接口接受单个对象。建议严格按curl示例只传对象。是否传了多余字段接口未定义字段会被忽略但不会报错。image_url和image_b64必须且只能传一个。如果同时传两个接口会优先使用image_url但不会报错。错误2返回500且错误信息为backend error可能原因选择的云端引擎如百度需要单独开通权限本接口已封装但后端连通性问题。可先切换到nudenet验证本地引擎是否正常。图片过大超过云端限制例如10MB。建议压缩至2MB以内或缩小分辨率。图片格式不支持只支持常见格式JPEG、PNG、WebP、BMPGIF仅取第一帧。错误3返回decision: review但期望pass检查categories中的sexy或porn得分。有时健康图片因背景元素例如沙滩、泳装被误判。可尝试换用不同backendnudenet通常宽松百度较严。利用raw字段查看云端原始得分确认是否因阈值问题。错误4长超时导致接口无响应设置timeout为合理值如15秒。若仍超时检查网络到v1.apizero.cn的连通性。对于大批量任务建议使用本地nudenet引擎并分片控制并发QPS≤2。工程化注意事项图片获取与缓存如果使用image_url建议让接口直接从源站拉取避免频繁上传base64。但需注意源站稳定性。若图片需要鉴权才能访问可临时生成签名的临时URL。超时与重试策略网络抖动时可能返回空响应或504。建议使用指数退避重试最多3次并记录失败日志。决策业务处理decision为review时建议将图片送入人工审核队列而非直接通过。block则直接拒绝。数据合规回传的input.source包含原始URL注意不要将内部链接泄露到日志中。性能监控记录elapsed_ms和backend评估不同引擎的延迟与准确率为后续选型提供依据。单元测试准备测试图片正常、性感、涉黄各一张断言decision符合预期。注意涉黄图片不要存储在公开仓库中。参考文档图片鉴黄API官方文档原始文档Markdown文档中包含更详细的请求/响应示例及变更日志建议接入前完整阅读。
图片鉴黄API常见错误与排错指南：从参数到返回的全面排查
适用场景与接口概述图片鉴黄NSFW内容检测是内容审核管线的核心环节。无论是用户头像、帖子配图还是直播截图都需在合规前提下自动识别涉黄、性感或正常内容。本接口支持本地NudeNet推理及百度/腾讯/阿里三家云端引擎通过统一的decision字段block、review、pass和分类得分给出结果同时附带检测框坐标用于定位。本文并不介绍接口功能本身而是站在排错角度从请求构造、参数校验、返回值解读、异常处理到工程化落地逐一拆解容易踩坑的环节。接口能力边界与QPS说明请求地址:POST https://v1.apizero.cn/api/image-nsfwQPS限制: 2次/秒。超出会返回429 Too Many Requests需实现重试或队列。超时范围: 支持timeout参数3~60秒默认值依赖后端本地NudeNet通常3-5秒云端可能更长。图片源: 支持HTTP/HTTPS URL 或 base64含data:URI。单次请求只处理一张图片数组结构实际是对单个对象封装。常见误区直接复制文档中的[{}]数组但不理解其含义导致请求体被包装成数组而非对象。实际只需传入一个对象即可参照curl示例。请求参数详解与鉴权参数表参数名类型必填说明示例image_urlstring条件必填图片HTTP(S) URL与image_b64二选一https://example.com/photo.jpgimage_b64string条件必填图片base64编码可包含data:image/...;base64,前缀–backendstring否引擎选择auto默认、nudenet、baidu、tencent、aliyun。auto优先用本地NudeNetautotimeoutnumber否超时秒数3~60。空字符串表示用默认推荐显式设值10鉴权方式请求头需携带X-API-Key值为用户API密钥。密钥管理通常在平台个人中心。常见错误忘记添加X-API-Key头返回401 Unauthorized。Header名拼写错误如X-API-KEY大小写不敏感但建议严格按文档。密钥过期或未生成返回403 Forbidden。curl示例与常见接入错误可复制示例请替换API Key和图片URLcurl -sS \ -X POST \ -H X-API-Key: YOUR_API_KEY \ -H Content-Type: application/json \ -d { image_url: https://example.com/photo.jpg, backend: auto, timeout: 10 } \ https://v1.apizero.cn/api/image-nsfw容易踩的坑JSON格式错误-d后的JSON用单引号包裹时内部双引号不能转义。若JSON中包含单引号极少见需转成\u0027。未设置 Content-Type虽然某些客户端会自动推测但显式指定application/json更安全。图片URL不可访问返回400错误描述invalid image url。确保URL可公开访问、无重定向、非本地127.0.0.1/localhost。base64乱码使用image_b64时必须正确编码且不含换行符。推荐在发送前去掉\n。backend拼写错误例如nudenet写成了nude-net。接口会返回400并提示invalid backend。返回值解读与决策逻辑响应结构成功200{ code: 200, desc: success, decision: pass, label: normal, score: 0.8511, categories: { normal: 1, porn: 0, sexy: 0 }, detections: [ { box: [381, 291, 528, 575], cls: FACE_FEMALE, score: 0.8511 } ], backend: nudenet, elapsed_ms: 115, input: { source: https://..., type: url, mime: image/jpeg, size_bytes: 993377, width: 1080, height: 1920, sha256: ... }, raw: {}, tips: 极数本源 · https://apizero.cn, notes: [] }关键字段排错decision:pass表示通过review需人工复核block表示违规。如果预期pass但得到block检查图片内容或尝试切换backend不同引擎敏感度不同。categories: 分数在0~1之间且三个分类概率之和≈1。若出现大于1或负数可能是编码错误极少见可联系支持。detections只有本地NudeNet (nudenet) 会返回此字段。云端引擎的原始结果在raw字段中。如果detections为空数组但decision为pass说明没有检测到敏感区域属于正常。elapsed_ms: 实际耗时。若远超timeout设置值说明后端可能超时但接口仍返回了结果视后端机制建议增大超时或换用本地引擎。input.sha256: 图片内容的哈希值可用于缓存或去重。若两次请求返回不同哈希值说明图片内容有变化。错误码列表HTTP状态码错误描述常见原因处理建议400invalid request bodyJSON解析失败检查JSON格式确保无多余逗号400invalid image urlURL无法访问或非图片测试URL是否公开、响应头含图片类型400invalid backendbackend值不在合法范围内只允许auto/nudenet/baidu/tencent/aliyun400invalid timeouttimeout超出 3-60设值在范围内401unauthorized缺少或无效API Key检查Header名称与密钥403forbiddenAPI Key无权限或已过期检查账户状态429too many requestsQPS超限添加请求间隔或重试逻辑500backend error后端引擎异常重试或切换backend504gateway timeout处理超时增大timeout或减小图片尺寸高频错误与排错指南错误1返回400但请求体看似正确检查点是否将整个对象包裹在数组[{}]内文档示例是数组格式但实际接口接受单个对象。建议严格按curl示例只传对象。是否传了多余字段接口未定义字段会被忽略但不会报错。image_url和image_b64必须且只能传一个。如果同时传两个接口会优先使用image_url但不会报错。错误2返回500且错误信息为backend error可能原因选择的云端引擎如百度需要单独开通权限本接口已封装但后端连通性问题。可先切换到nudenet验证本地引擎是否正常。图片过大超过云端限制例如10MB。建议压缩至2MB以内或缩小分辨率。图片格式不支持只支持常见格式JPEG、PNG、WebP、BMPGIF仅取第一帧。错误3返回decision: review但期望pass检查categories中的sexy或porn得分。有时健康图片因背景元素例如沙滩、泳装被误判。可尝试换用不同backendnudenet通常宽松百度较严。利用raw字段查看云端原始得分确认是否因阈值问题。错误4长超时导致接口无响应设置timeout为合理值如15秒。若仍超时检查网络到v1.apizero.cn的连通性。对于大批量任务建议使用本地nudenet引擎并分片控制并发QPS≤2。工程化注意事项图片获取与缓存如果使用image_url建议让接口直接从源站拉取避免频繁上传base64。但需注意源站稳定性。若图片需要鉴权才能访问可临时生成签名的临时URL。超时与重试策略网络抖动时可能返回空响应或504。建议使用指数退避重试最多3次并记录失败日志。决策业务处理decision为review时建议将图片送入人工审核队列而非直接通过。block则直接拒绝。数据合规回传的input.source包含原始URL注意不要将内部链接泄露到日志中。性能监控记录elapsed_ms和backend评估不同引擎的延迟与准确率为后续选型提供依据。单元测试准备测试图片正常、性感、涉黄各一张断言decision符合预期。注意涉黄图片不要存储在公开仓库中。参考文档图片鉴黄API官方文档原始文档Markdown文档中包含更详细的请求/响应示例及变更日志建议接入前完整阅读。
