适用场景与接口定位在反爬虫、防自动化作弊、设备风险识别等场景中浏览器指纹风控API是后端决策的核心数据源。开发者通过前端SDK采集用户浏览器的UA、Canvas、WebGL、字体、时区、硬件并发数、WebDriver标记等20维度信息提交至本API接口综合9类规则输出0-100风险评分、风险等级safe/low/medium/high/critical以及命中的风险因子和异常项帮助识别Headless Chrome、Selenium、虚拟机等异常环境。接口能力边界调用限制与用量边界本API在提供高精度指纹分析的同时设定了明确的调用限制确保服务稳定性。开发者需要重点理解以下几个维度QPS限制5次/秒接口的每秒查询数QPS上限为5。这意味着单个API Key在同一秒内发起的请求不能超过5个。超出后服务端将返回HTTP 429 Too Many Requests并可能周期性拒接后续请求。建议在客户端实现队列或限流器例如使用令牌桶或滑动窗口算法控制并发。请求体大小限制每次请求携带的JSON数据应控制在合理范围内。尽管文档未明确给出上限但从实际经验看建议请求体不超过100KB。当采集数据包含大量字体列表或详细Canvas二进制Base64时需注意体积。若超出限制服务端可能返回413 Payload Too Large。可考虑对非必要字段进行裁剪或仅提交API规定必须的字段。并发连接数虽然没有明确限制但建议单客户端保持的连接数不超过10个以避免触发服务端连接池保护。对于高并发场景可以通过轮询多个API Key或请求负载均衡的方式提升吞吐量但需确保每个Key的QPS不超限。超时设置接口响应时间通常取决于请求数据量和服务端负载。建议客户端设置合理的超时时间如10秒。生产环境中可使用长连接HTTP Keep-Alive减少TCP握手开销但需注意连接池大小与空闲超时的配置。鉴权与请求格式Header参数参数必须类型说明Authorization否stringAPI Key通过X-API-Key也可传递Content-Type是string固定为 application/json实际调用时更常见的做法是在Header中设置X-API-Key字段。文档提供了curl示例中使用-H X-API-Key: $APIZERO_API_KEY。请求体字段节选请求体为JSON对象至少需要包含ua字段。其他字段按需填写数量越多分析越精准。主要字段如下字段名必须类型描述ua是stringnavigator.userAgentplatform否stringnavigator.platformlanguage否string主语言如zh-CNtimezone否stringIANA时区如Asia/ShanghaitimezoneOffset否numbergetTimezoneOffset()分钟screenWidth否numberscreen.widthscreenHeight否numberscreen.heightcolorDepth否numberscreen.colorDepthpixelRatio否numberdevicePixelRatiohardwareConcurrency否number逻辑CPU核心数...更多字段请参考文档curl接入示例以下是一个可复制的请求示例使用环境变量APIZERO_API_KEY保存API Key。export APIZERO_API_KEYyour_api_key_here curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { ua: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36, platform: Win32, language: zh-CN, timezone: Asia/Shanghai, timezoneOffset: -480, screenWidth: 1920, screenHeight: 1080, colorDepth: 24, pixelRatio: 1, hardwareConcurrency: 8 } \ https://v1.apizero.cn/api/browser-fingerprint请将your_api_key_here替换为真实API Key。注意若在Windows CMD下运行需调整引号语法。返回值解读成功响应HTTP 200返回如下结构{ code: 0, msg: 成功, request_id: abc123, data: { fingerprint_id: a1b2c3d4..., risk: 72, risk_label: 高风险, risk_level: high, timestamp: 1715097600, device_profile: { browser: Chrome 125, os: Windows, device_type: Desktop, screen: 1920x1080, cores: 8, memory: 8GB, fonts_count: 42, gpu: ANGLE (NVIDIA, GeForce RTX 3060), plugins_count: 3, touch: false }, factors: [ { name: webdriver, desc: WebDriver 标记为 true, score: 30 }, { name: virtual_gpu, desc: WebGL 渲染器包含虚拟/软渲染特征: SwiftShader, score: 15 } ], anomalies: [ UA 声称 Windows 但 platform 不匹配 ] } }关键字段说明fingerprint_id本次指纹的唯一ID可用于后续标记或黑名单。risk0-100整数风险评分越高代表越可疑。risk_level枚举值 safe/low/medium/high/critical。risk_label中文描述如“高风险”。device_profile设备画像可用于比对预期环境。factors命中的风险因子列表每个因子包含名称、描述、贡献分数。anomalies异常项列表如“UA声称Windows但platform不匹配”。错误处理与常见问题HTTP状态码常见原因处理建议400请求体格式错误或缺少必填字段检查JSON合法性确保ua存在且为字符串401未提供API Key或Key无效验证Authorization或X-API-Key头是否正确429超过QPS限制降低请求频率引入限流413请求体过大精简采集字段或联系支持调整上限500服务端内部错误重试若持续报错则上报此外网络波动可能导致超时curl中可通过--connect-timeout 5 --max-time 10设置。建议实现指数退避重试策略首次等待1秒下次2秒最大5秒重试最多3次。工程化注意事项数据采集前端SDK使用官方或自主开发的SDK在浏览器端采集数据尽量异步执行避免阻塞主线程。采集完成后通过后端中继转发至API避免暴露API Key。请求合并在高频访问场景下可将多个用户请求合并为一个批次但该API当前设计为单用户单次请求不支持批量。因此应考虑将多个用户的请求异步提交但需维持单个请求的独立性。缓存策略同一指纹ID在短期内如5分钟内的检测结果可仅缓存一次避免重复调用。注意指纹ID的生成是每次请求独立返回需同时缓存请求指纹数据或利用前端生成的持久性标识。降级与熔断当API连续返回500或超时超过阈值应启动降级允许用户继续操作但记录风险未知。待服务恢复后再重新检测。安全密钥管理API Key不应出现在前端代码或版本控制中。建议通过后端环境变量或密钥管理服务如Vault读取并通过API网关转发请求。参考文档浏览器指纹风控API文档原始文档Markdown