适用场景哪里需要图片审核在UGC社区、电商平台、直播截图、网盘存储等场景中图片NSFWNot Safe For Work检测是内容安全的第一道防线。该接口统一将后端返回包括本地NudeNet推理与三家云厂商映射为block / review / pass三级决策适用于用户头像/昵称审核上传前即时检测降低人工维护复杂度动态/商品图片过滤对大量图片做离线批量扫描直播帧截图按帧投递QPS 2/s 可满足中等规模直播流历史图库清洗通过批量任务对存量数据打标签需要注意的是接口本身不存储任何图片只返回分析结果图片最长60秒超时适合对时效性要求不是极端高的处理链路。接口能力边界多后端策略与统一决策核心能力维度维度说明检测后端支持auto自动优选、nudenet本地、baidu、tencent、aliyun五种选择决策映射三类decisionblock拦截、review人工复审、pass通过检测框返回detections数组标注人体部位/物体位置支持多目标原始结果raw字段保留后端原生输出便于二次比对QPS限制单密钥默认2/s超限返回429可通过联系平台申请提升超时范围timeout参数3~60秒推荐10~15秒以平衡响应与成功率后端选择策略auto由平台根据图片特征自动选择最优后端通常优先云服务若失败则回退NudeNet。推荐绝大多数场景使用。nudenet零调用费基于NudeNet v2本地模型适合对维护复杂度敏感或数据不出域的需求但类别较少FACE_FEMALE、FEMALE_BREAST、BELLY、BUTTOCKS等且无云厂商的细粒度分类。baidu/tencent/aliyun提供更丰富的分类如“ARTISTIC场景区分”及更高精度但会产生对应厂商的调用费用具体以各自用量说明为准本文不讨论费用。实际数据表现NudeNet在纯裸露检测上欠召回但误报低云厂商综合错误率较低尤其对二次元/艺术画的区分更好。建议业务前期同时跑两种后端做对比评估。请求参数与鉴权鉴权方式通过HTTP Header携带密钥X-API-Key: $APIZERO_API_KEY密钥需在平台申请获取方式见参考文档调用时请设为环境变量。请求体字段表参数名类型必填说明image_urlstring否与image_b64二选一图片HTTP(S)公网地址支持jpg/png/webp等常用格式image_b64string否Base64编码的图片数据可含data:image/...;base64,前缀backendstring否后端选择auto(默认)、nudenet、baidu、tencent、aliyuntimeoutnumber否单次请求超时秒数范围3~60不传则由服务端默认约20秒注意image_url与image_b64必须且只能提供一个。若同时提供image_url优先。curl接入示例可复制使用image_url发起自动后端检测curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {image_url: https://example.com/photo.jpg, backend: auto, timeout: } \ https://v1.apizero.cn/api/image-nsfw替换$APIZERO_API_KEY为真实密钥image_url为待检测图片地址。响应为JSON见下文。Python代码接入requestsimport requests import os API_KEY os.environ[APIZERO_API_KEY] API_URL https://v1.apizero.cn/api/image-nsfw payload { image_url: https://example.com/photo.jpg, backend: auto, timeout: 15 # 秒 } headers { X-API-Key: API_KEY, Content-Type: application/json } resp requests.post(API_URL, jsonpayload, headersheaders, timeout20) if resp.status_code 200: result resp.json() print(fDecision: {result[decision]}) print(fLabel: {result[label]}) print(fCategories: {result[categories]}) else: print(fError {resp.status_code}: {resp.text})返回字段详解成功响应示例解析以素材中的JSON为例字段类型说明backendstring实际使用的后端名称如nudenet、baiducategoriesobject三个分类得分normal、porn、sexy取值范围0~1decisionstring最终决策pass通过、review人工审核、block拦截detectionsarray检测到的敏感区域列表每个元素含box(四点坐标)、cls(类别)、score(置信度)elapsed_msnumber实际处理耗时毫秒inputobject图片元信息尺寸、MIME类型、sha256哈希、大小字节、来源等labelstring语义标签如normal、porn、sexynotesarray额外说明信息当前常为空rawobject后端原生完整输出键为后端名称值为对应JSON数组scorenumber最高敏感分类的得分范围0~1分数越高越疑似NSFW决策逻辑简要说明decision:passscore通常≤0.3categories.normal接近1无需人工介入。decision:reviewscore在0.3~0.7之间或分类争议较大建议人工复核。decision:blockscore≥0.7且porn或sexy得分高直接拦截。不同后端的决策阈值存在差异但最终socre已经过归一化处理业务方可直接依赖decision字段。常见错误与处理状态码常见原因处理建议400请求体格式错误或image_url/image_b64同时为空检查JSON结构确保至少一个图片源401密钥无效或未提供X-API-Key检查密钥环境变量确认未过期429QPS超限2/s添加本地限流或任务队列增加重试退避500后端服务内部错误或云厂商超时增加重试机制建议指数退避或切换backend为nudenet504节点超时图片下载或推理超过timeout增大timeout参数最长60秒检查图片地址是否可访问工程化注意事项1. 后端选择与降级策略建议业务侧实现多级降级高优先级走云后端auto优先若连续失败3次则临时切换到nudenet并记录报警。生产环境可单独解析raw字段以保留云厂商的细粒度标签。2. 图片预处理避免大尺寸原图接口内部会自动缩放至合理范围但传输耗时会增加。建议在上传前压缩至1920px以内。图片格式优先使用JPEG/PNGWebP部分后端兼容性较好。临时图片地址需确保授权访问若使用带签名的S3 URL注意URL过期时间大于timeout值。3. 批量调用与并发控制由于QPS限制2/s批量处理时建议import time from concurrent.futures import ThreadPoolExecutor, wait def check_image(image_url): # 调用API... time.sleep(0.5) # 保证两个请求之间间隔至少500ms return image_url, result with ThreadPoolExecutor(max_workers2) as executor: futures {executor.submit(check_image, url): url for url in image_urls[:10]} for future in wait(futures): if future.exception(): # 记录失败更推荐使用消息队列RabbitMQ/Kafka配合固定速率消费。4. 结果缓存与人工标注对于重复图片相同sha256可缓存上次检测结果以避免重复调用。input.sha256可以作为缓存键。对于review状态的图片建议搭建人工复核面板将human label回写至数据库持续优化阈值。参考文档接口文档页https://apizero.cn/aidocs/image-nsfw原始文档Markdownhttps://apizero.cn/aidocs/image-nsfw/raw.md平台支持如有参数或SDK相关问题可通过文档页底部的联系方式与技术支持沟通。
