适用场景为什么需要浏览器指纹风控在Web反爬虫、反欺诈、账户安全等领域单纯依赖IP或Cookie已无法有效识别自动化工具。浏览器指纹通过采集navigator、screen、canvas、WebGL等20维度的特征生成设备唯一标识并结合规则引擎输出风险评分精准检测Headless Chrome、Selenium、Puppeteer、Playwright等异常环境。本文聚焦最小可运行示例即用最少的参数和代码快速验证接口能力帮助开发者在不依赖前端SDK的情况下先通过curl或Python脚本调用理解输入输出后再进行正式集成。接口能力边界接口地址POST https://v1.apizero.cn/api/browser-fingerprint请求方法POSTContent-Typeapplication/json核心能力接收UA、平台、语言、时区、屏幕分辨率、颜色深度、像素比、硬件并发数、设备内存、插件列表、Canvas指纹、WebGL渲染器、字体列表、WebDriver标记等字段综合9类规则输出风险评分0-100与等级safe/low/medium/high/critical、命中的风险因子及异常项。QPS上限5次/秒以文档为准注意接口仅处理服务端计算前端采集SDK需自行实现。本文示例使用手动构造的JSON模拟采集数据。请求参数与鉴权鉴权方式请求头中需携带API密钥支持两种方式推荐使用X-API-KeyHeader必填说明X-API-Key是在平台获取的密钥如sk-xxxxContent-Type是application/jsonAuthorization否备用鉴权以文档为准请求字段说明以下为JSON Body中的主要字段完整字段列表见官方文档字段名类型必填说明与示例uastring是navigator.userAgent如Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ...platformstring否navigator.platform如Win32languagestring否主语言代码如zh-CNtimezonestring否IANA时区如Asia/ShanghaitimezoneOffsetnumber否getTimezoneOffset() 返回值分钟如-480screenWidthnumber否屏幕宽度如1920screenHeightnumber否屏幕高度如1080colorDepthnumber否色彩深度如24pixelRationumber否设备像素比如1.25hardwareConcurrencynumber否逻辑CPU核心数如8deviceMemorynumber否设备内存GB如8pluginsarray否插件列表每个元素含name、description等canvasstring否Canvas指纹Base64参考前端SDK采集webglstring否WebGL指纹Base64fontsarray否系统字体列表如[Arial, Microsoft YaHei]webdriverboolean否navigator.webdriver值正常为false必填字段仅为ua但字段越多风险判断越准确。推荐至少提供ua、platform、language、screenWidth/screenHeight、hardwareConcurrency、webdriver。最小可运行curl示例以下示例仅包含必填字段ua适合快速测试接口连通性请将$APIZERO_API_KEY替换为真实密钥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} \ https://v1.apizero.cn/api/browser-fingerprint若希望得到更丰富的检测结果可构造包含常见自动化标记的请求体模拟Headless Chromecurl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { ua: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/125.0.0.0 Safari/537.36, platform: Linux x86_64, language: en-US, timezone: UTC, timezoneOffset: 0, screenWidth: 1920, screenHeight: 1080, colorDepth: 24, pixelRatio: 1, hardwareConcurrency: 2, deviceMemory: 2, webdriver: true, fonts: [Arial, Courier New], plugins: [] } \ https://v1.apizero.cn/api/browser-fingerprintPython代码接入示例以下使用requests库封装函数便于集成到爬虫或风控系统中import requests import json def analyze_browser_fingerprint(api_key, fingerprint_data): 浏览器指纹风控分析 :param api_key: API密钥 :param fingerprint_data: dict至少包含ua字段 :return: dict 响应数据 url https://v1.apizero.cn/api/browser-fingerprint headers { X-API-Key: api_key, Content-Type: application/json } resp requests.post(url, headersheaders, jsonfingerprint_data, timeout10) resp.raise_for_status() return resp.json() # 使用示例 api_key sk-your-key-here payload { ua: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36, platform: MacIntel, language: zh-CN, timezone: Asia/Shanghai, screenWidth: 1440, screenHeight: 900, hardwareConcurrency: 8, webdriver: False } try: result analyze_browser_fingerprint(api_key, payload) print(json.dumps(result, indent2, ensure_asciiFalse)) except Exception as e: print(f调用失败: {e})返回值解读成功响应HTTP状态码200Body为JSON结构如下{ code: 0, msg: 成功, request_id: abc123, data: { fingerprint_id: a1b2c3d4e5f6..., risk: 72, risk_label: 高风险, risk_level: high, timestamp: 1715097600, factors: [ { name: webdriver, desc: WebDriver 标记为 true, score: 30 }, { name: virtual_gpu, desc: WebGL 渲染器包含虚拟/软渲染特征: SwiftShader, score: 15 } ], anomalies: [ UA 声称 Windows 但 platform 不匹配 ], device_profile: { browser: Chrome 125, os: Windows, device_type: Desktop, screen: 1920x1080, cores: 8, memory: 8GB, fonts_count: 42, plugins_count: 3, gpu: ANGLE (NVIDIA, GeForce RTX 3060), touch: false } } }核心字段说明字段路径类型说明codeint业务状态码0表示成功非0表示异常msgstring状态描述request_idstring本次请求唯一标识用于排查data.fingerprint_idstring生成的设备指纹IDdata.riskint风险评分 0-100越高越危险data.risk_levelstring等级safe(0-20)、low(21-40)、medium(41-60)、high(61-80)、critical(81-100)data.risk_labelstring中文标签如“高风险”data.timestampintUnix时间戳data.factorsarray命中的风险因子列表每项含名称、描述和贡献分数data.anomaliesarray异常项描述如UA与平台不匹配data.device_profileobject设备画像概览方便快速了解设备特征应用场景根据risk_level决定是否拦截。例如high或critical可触发验证码、拒绝访问或提高验证强度。factors列表可帮助安全团队定位具体风险来源。常见错误与排查HTTP状态码可能原因排查方法400请求体格式错误或缺少必填字段ua检查JSON是否合法ua是否存在401API密钥无效或未提供确认X-API-Key头是否正确密钥是否过期429QPS超限超过5次/秒降低请求频率加入重试机制500服务端内部错误稍后重试或提供request_id联系支持200但code ! 0业务逻辑错误根据msg字段定位常见如字段类型不匹配字段校验常见问题timezoneOffset需为数字分钟负数表示UTC时区因为getTimezoneOffset()返回UTC-本地如中国为-480plugins需为数组每个元素至少含name字符串fonts应为字符串数组webdriver需为布尔值传入true字符串会导致类型错误。工程化注意事项QPS控制官方限频5次/秒并发场景下需加入令牌桶或请求队列。如果业务量较大建议批量采集后异步调用或使用代理池分散请求。字段完整性虽然仅ua必填但实际指纹识别依赖多维度交叉验证。至少提供10个以上字段可显著提升准确率。前端SDK采集时注意保护用户隐私避免采集超出需要的字段。缓存策略对于同一指纹IDfingerprint_id风险等级在短时间如5分钟内通常不会剧烈变化可设置本地缓存减少重复调用。异常重试网络抖动或服务端偶发错误时采用指数退避重试如1s、2s、4s最大重试3次。注意区分可重试5xx、超时和不可重试4xx鉴权、参数错误。数据安全API密钥不要硬编码在客户端代码或版本控制中建议通过环境变量或配置中心注入。生产集成在业务侧将指纹分析作为异步非关键路径如发送消息到队列处理避免阻塞用户登录或下单流程。参考文档浏览器指纹风控API官方文档原始Markdown文档本文基于API事实卡写作所有接口地址、参数、返回结构均以官方文档为准。若字段或QPS有更新请参考最新文档。
