跳到主要内容
如何使用 Fingerprint API

生成指纹,注入,融入其中。

通过一个简单的 REST 调用请求一个一致的真实浏览器指纹,然后将其字段应用到 Playwright、Puppeteer 或 Selenium,让你的自动化呈现为一台合理且一致的机器。

1. 快速开始

从你的控制台获取 API 密钥,然后请求一个指纹。/generate 合成一个全新的唯一身份;/random 从池中返回一个真实指纹。

generate.sh
# Generate a fresh, coherent fingerprint (quota deducts on success)
curl "https://api.capzy.ai/fingerprint/generate?key=YOUR_API_KEY&format=chromium&tags=Windows&country=us"
  • 使用 tags(Windows、macOS、Linux、Android、iOS)和 country(ISO alpha-2)进行筛选。
  • format=chromium 返回可直接注入的字段;format=raw 返回完整数据。
  • 仅在生成成功时扣除配额。

2. 在你的自动化中应用

在浏览器上设置机器级字段(userAgent、viewport、locale、timezone),然后在任何页面脚本运行之前,让 JS 可见的 navigator 与同一台机器保持一致。

playwright.py
import requests
from playwright.sync_api import sync_playwright

# 1. Generate a coherent fingerprint for a Windows visitor in the US
fp = requests.get("https://api.capzy.ai/fingerprint/generate", params={
    "key": "YOUR_API_KEY",
    "format": "chromium",   # injection-ready
    "tags": "Windows",
    "country": "us",
}).json()

rect = fp["screen"]["screenRect"]

with sync_playwright() as p:
    browser = p.chromium.launch()
    # 2. Apply the machine-level fields on the context
    context = browser.new_context(
        user_agent=fp["userAgent"]["userAgent"],
        locale=fp["intl"]["languages"][0],
        timezone_id=fp["intl"]["timeZone"],
        viewport={"width": rect["width"], "height": rect["height"]},
        device_scale_factor=fp["screen"]["deviceScaleFactor"],
    )
    # 3. Match the JS-visible navigator to the SAME machine (before page scripts)
    context.add_init_script(f"""
      Object.defineProperty(navigator, 'hardwareConcurrency', {{ get: () => {fp['navigator']['hardwareConcurrency']} }});
      Object.defineProperty(navigator, 'deviceMemory', {{ get: () => {fp['navigator']['deviceMemory']} }});
      Object.defineProperty(navigator, 'platform', {{ get: () => '{fp['userAgent']['platform']}' }});
    """)
    page = context.new_page()
    page.goto("https://example.com")
    print(page.title())
    browser.close()

Firefox 和 Safari 指纹的用法相同。Chromium 上存在的能力字段(deviceMemory、hardwareConcurrency、客户端提示)在真实浏览器不会暴露的情况下会被省略。

3. 响应格式

chromium 可直接注入

你在浏览器上设置的确切字段:userAgent、screen、intl、navigator、webgl。适用于上面的示例。

raw 完整数据

完整的指纹负载(canvas、fonts、visitor_id、webgl_properties),用于存储或你自己的注入器。

4. 保持一致性

一个指纹代表一台合理的真实机器,而不是一堆随机字段。两条规则让它保持可信:

一起应用字段

userAgent、客户端提示和 navigator 应来自同一个响应。覆盖 UA 而客户端提示仍报告原始浏览器,是头号自动化破绽。

每个身份一个指纹

对同一个配置/会话复用同一个指纹。在会话中途轮换字段,看起来就像一台更换了硬件的机器。

匹配代理地理位置

将你请求的国家/地区与该国家/地区的出口 IP 搭配使用,让时区、语言和 IP 保持一致。

5. 常见问题

random 还是 generate:用哪个端点?›

/fingerprint/random 从池中返回一台真实的、之前采集的设备(便宜)。/fingerprint/generate 在严格的一致性约束下合成一个全新的唯一指纹(仅在成功时扣除配额)。需要独一无二的身份时,请使用 generate。

chromium 还是 raw 格式?›

chromium 可直接注入:即你在浏览器上设置的确切字段(userAgent、screen、intl、navigator)。raw 返回完整的指纹数据(canvas、fonts、visitor_id、webgl_properties),用于存储或你自己的注入器。

我还需要设置 Sec-CH-UA 请求头吗?›

指纹是作为同一台机器推导出来的,因此 userAgent、客户端提示请求头和 navigator 全部一致。最常见的破绽是覆盖了 UA,却让客户端提示仍报告原始浏览器,所以请将这些字段一起应用,不要单独手动修改其中一个。

如何指定国家/地区或操作系统?›

传入 country(ISO alpha-2,决定语言、时区和语音)和 tags(Windows、macOS、Linux、Android、iOS)。请参阅 Fingerprint API 页面上的参数表。

准备好开始了吗?

获取 API 密钥,生成你的第一个一致性指纹。

获取你的 API 密钥